Skip to content

Add Internet Archive filesystem implementation - #2121

Open
lfoppiano wants to merge 5 commits into
fsspec:masterfrom
lfoppiano:ia-filesystem
Open

lfoppiano wants to merge 5 commits into
fsspec:masterfrom
lfoppiano:ia-filesystem

Conversation

@lfoppiano

@lfoppiano lfoppiano commented Sep 8, 2026

Copy link
Copy Markdown

Adds InternetArchiveFileSystem (fsspec/implementations/ia.py, protocol ia): ia://<identifier>/<filename> for files in archive.org items, plus registry entry, API docs, changelog and tests.

It remap to HTTP (HTTPFileSystem) with a path mapping and credentials, from https://archive.org/download//, which redirects to a data node that support HTTP Range queries. That is the same URL the internetarchive package downloads from.

S3-like API (s3.us.archive.org, which an S3FileSystem + endpoint_url would use): Internet Archive data nodes ignore Range and answer a ranged GET with 200 and the whole file, so every block read would download the entire object. Measured on a 1.6 GB public item (Range: bytes=0-99 on every request):

Endpoint URL Status Bytes sent
S3-like front end https://s3.us.archive.org// 307 → http://dnNNN.s3dns.us.archive.org:80/… 410 (XML)
S3-like data node (following the 307) http://dnNNN.s3dns.us.archive.org// 200, Accept-Ranges: bytes, no Content-Range 1,689,855,303
Download endpoint https://archive.org/download// 302 → https://dnNNN.ca.archive.org/0/items/… 0
Download data node (following the 302) https://dnNNN.ca.archive.org/0/items// 206, Content-Range: bytes 0-99/1689855303 100

IA documents this: "HTTP 1.1 Range headers are ignored" (https://archive.org/developers/ias3.html#how-this-is-different-from-normal-s3). botocore also misreads the 307 as an AWS region redirect and recurses on HeadBucket until RecursionError.

Credentials. Public items need none. For restricted items the class reads the ia.ini written by ia configure, found the way the internetarchive package finds it ($IA_CONFIG_FILE, $XDG_CONFIG_HOME/internetarchive/ia.ini, ~/.config/ia.ini, ~/.ia), with IA_ACCESS_KEY_ID/IA_SECRET_ACCESS_KEY overriding the file.
Cookies go into the session's cookie jar scoped to .archive.org rather than a Cookie header, because every download is a cross-origin redirect and aiohttp drops Cookie/Authorization headers there; the jar re-attaches them to the data node. 401/403 raise PermissionError (otherwise HTTPFileSystem._info reports a 403 as FileNotFoundError).

Tested with fsspec/implementations/tests/test_ia.py.

@martindurant

Copy link
Copy Markdown
Member

This looks like fun - please let me know when you are ready. Are you affiliated with IA in any way? If not, should we approach someone for their opinion?

@lfoppiano

Copy link
Copy Markdown
Author

@martindurant thank you for reaching out. I'm from the Common Crawl Foundation.
We've started discussing with the IA about it and I still have to do some testing, I let you know as soon as it's ready 🙂

@wumpus

wumpus commented Sep 15, 2026

Copy link
Copy Markdown

I asked Mark Graham @ IA a week ago and he did not reply. (I used to work there.)

We want to stress test this PR and also PR #2124 -- I have a 500 TByte dataset of ~10 GByte files that I want to read from IA that ought to be a good stress test.

Comment thread fsspec/implementations/ia.py Outdated
Comment thread fsspec/implementations/ia.py Outdated
Comment thread fsspec/implementations/ia.py
@wumpus

wumpus commented Sep 15, 2026

Copy link
Copy Markdown

@martindurant I have asked jjjake to weigh in.

@jjjake

jjjake commented Sep 15, 2026

Copy link
Copy Markdown

@wumpus Thanks for the heads up on this.

My only suggestion is to use IA-S3 keys via Authorization header for everything, and not use cookies at all. You'll just need to make sure that the Authorization header survives the redirect to the data node. Everything else looks good to me.

I'll pass this along to the rest of our team in case anyone else has feedback, but the rest looks good to me! Thanks for submitting this, lfoppiano!

lfoppiano and others added 3 commits September 15, 2026 21:03
…e data node

aiohttp builds a new request from the session's request_class for every
hop, so InternetArchiveFileSystem now passes a ClientRequest subclass that
sets `Authorization: LOW <access>:<secret>` on any request to a host in
`.archive.org`. That both re-attaches the header on the data-node hop and
keeps it from leaving archive.org should a data node redirect elsewhere;
it is no longer in the session's default headers.

Tests: the stand-in archive.org is now two servers on localhost (a
different port is a different origin), asserting the header on every hop,
and no header when the node is off-domain.
@lfoppiano

Copy link
Copy Markdown
Author

@jjjake thanks for your feedback. I've replaced the cookies auth with the authorization header.

@wumpus thanks for the corrections, I've fixed the naming.

@lfoppiano
lfoppiano marked this pull request as ready for review September 16, 2026 15:37
@martindurant

Copy link
Copy Markdown
Member

The failures seem to be real and persistent - but I don't see what they have to do with changes here.

Perhaps update the branch to see if these were already fixed?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants