Skip to content

Latest commit

 

History

History
94 lines (57 loc) · 4.69 KB

spec.md

File metadata and controls

94 lines (57 loc) · 4.69 KB

What Unbox does

The front page (https://unbox.ifarchive.org/) requests an Archive URL or path. This must be the URL of a zip, tar.gz, tgz, or tar.Z on the IF Archive. (http: and https: URLs are both accepted, since they give the same result. You may also omit the domain and enter an absolute path URI, beginning with a slash.)

The URL or path accepted as a ?url= parameter (with the usual query encoding). For example:

https://unbox.ifarchive.org/?url=%2Fif-archive%2Fgames%2Ftwine%2FAbsent_Heroes.zip

This returns a page listing the package contents:

Click on index.html to launch the Twine game. You can also view the images or the CSS file, if you so desire.

File URLs

URLs below the root are of two forms:

https://unbox.ifarchive.org/HASH/FILENAME
https://HASH.unbox.ifarchive.org/HASH/FILENAME

Each Archive path gets a unique hash. In the example above, games/twine/Absent_Heroes.zip has the hash 1u3qlfmqda.

HTML and SVG files are served out of the HASH.unbox.ifarchive.org subdomain. This ensures that games cannot wrangle each other's cookies or other stored data.

All other files are considered media files. They are served from the main unbox.ifarchive.org domain.

Requests for HTML/SVG in the main domain, and requests for media files in the subdomain, are redirected to the proper destination.

Why this dual treatment? We want to use a CDN (Cloudflare) to cache large files and protect us against high traffic. However, CDNs are normally configured for a single domain at a time. Happily, we can divide our files into media (large, safe to keep on a common domain) and HTML/SVG (small, must be kept in subdomains). The CDN caches media files. HTML/SVG files are cached by an nginx process running on the Unbox server.

Parameters

The front page accepts these additional parameters:

  • &open=FILENAME: Redirect to a given file within the package. For example:
https://unbox.ifarchive.org/?url=%2Fif-archive%2Fgames%2Ftwine%2FAbsent_Heroes.zip&open=index.html

This will launch the game immediately by redirecting to index.html in the contents listing.

If the named file is not found, Unbox will look for another file with the same suffix. (This is a concession to misnamed links in IFDB. See the open_file_of_same_type option.)

  • &search=STRING

This will return a list of all files in the package whose name contains STRING (case-insensitive). For example:

https://unbox.ifarchive.org/?url=%2Fif-archive%2Fgames%2Ftwine%2FAbsent_Heroes.zip&search=n

This lists two files: anigif_excited-ron-6869-1311881136-43.gif and index.html.

  • &json

When JSON mode is requested the app will return a JSON file for lists, searches, and errors. If the app redirects to a zip file it has no effect.

Details

In production, Unbox consists of three layers:

  • ifarchive-unbox is the app itself. It maintains a cache of zip/tgz/tar.gz/tar.Z files downloaded from ifarchive.org. It also keeps a local copy of the Archive's Master-Index.xml file.
  • nginx is a caching web server that runs in front of ifarchive-unbox. This caches HTML/SVG files.
  • A CDN such as CloudFlare is configured in front of nginx. This handles caching of media files.

This repository sets up the first two layers. The CDN must be set up separately.

(You can run Unbox without the CDN, but then media files will not be cached. Unbox will do an unzip for every media file request. Only run this way for testing.)

The hash value for a URI is computed by taking the SHA512 hash of the URI, taking the first 48 bits of that, and converting that integer to an alphanumeric string using toString(36). For example: "games/twine/Absent_Heroes.zip" -> 186486238769662 -> "1u3qlfmqda". There is no reason for you to need this information.