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.
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.
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.
In production, Unbox consists of three layers:
ifarchive-unbox
is the app itself. It maintains a cache ofzip/tgz/tar.gz/tar.Z
files downloaded from ifarchive.org. It also keeps a local copy of the Archive'sMaster-Index.xml
file.nginx
is a caching web server that runs in front ofifarchive-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.