globusfs 0.1.0__py3-none-any.whl

globusfs/__init__.py

@@ -0,0 +1,29 @@
+"""fsspec filesystem for Globus collections."""
+
+from .core import GlobusFileSystem
+from .credentials import (
+    AnonymousCredentials,
+    AppCredentials,
+    CallableToken,
+    GlobusCredentials,
+    StaticToken,
+)
+from .errors import GlobusFSError, TransientBackendError
+from .login import filesystem, login
+from .transfer import TransferMetadata
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AnonymousCredentials",
+    "AppCredentials",
+    "CallableToken",
+    "GlobusCredentials",
+    "GlobusFSError",
+    "GlobusFileSystem",
+    "StaticToken",
+    "TransferMetadata",
+    "TransientBackendError",
+    "filesystem",
+    "login",
+]

globusfs/core.py

@@ -0,0 +1,486 @@
+"""fsspec filesystem for Globus collections.
+
+URLs look like ``globus://<collection-uuid>/path/to/file``. The UUID is
+the authority because it is the stable identifier for a collection; the
+``https_url`` that actually serves bytes is a deployment detail resolved
+at runtime.
+
+Why this subclasses HTTPFileSystem
+----------------------------------
+Globus Connect Server serves full HTTP range semantics -- verified
+against a live collection: 206 responses, correct ``Content-Range``,
+mid-file seeks, and multipart ranges. ``HTTPFileSystem`` already speaks
+exactly that dialect, including 416 for out-of-range. So the read path
+is inherited rather than rewritten.
+
+What has to be overridden
+-------------------------
+Two things, both about *not trusting a 404*:
+
+``_raise_not_found_for_status``
+    fsspec maps 404 to ``FileNotFoundError``. On GCS a 404 is just as
+    likely to be a transient backend fault (see :mod:`globusfs.errors`),
+    so this inspects the body first. Every read path in HTTPFileSystem
+    funnels through this one method, which is why the fix is small.
+
+``_info`` / ``_ls``
+    The HTTPS interface has no directory listings at all, so metadata
+    comes from the Transfer API instead.
+
+The Transfer API also supplies real file sizes, which sidesteps a third
+quirk: GCS returns 416 for suffix ranges (``bytes=-8``), the usual way
+parquet readers seek to a footer. With the size known, readers can
+address the footer absolutely.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from fsspec import AbstractFileSystem
+from fsspec.asyn import sync
+from fsspec.implementations.http import HTTPFileSystem
+
+from .credentials import AnonymousCredentials, GlobusCredentials
+from .errors import TransientBackendError, is_transient_body
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["GlobusFileSystem"]
+
+DEFAULT_RETRIES = 5
+DEFAULT_BACKOFF = 0.3
+
+
+class _RetryingFetcher:
+    """Block fetcher that routes through the transient-404 retry path.
+
+    ``HTTPFile.async_fetch_range`` calls ``raise_for_status()`` directly,
+    so a backend fault reaches the caller as a bare 404 with no
+    classification -- the exact failure this package exists to prevent.
+    Substituting the fetcher puts file-object reads on the same footing
+    as ``cat_file``.
+
+    A class rather than a closure so the file object stays picklable.
+    """
+
+    def __init__(self, fs: GlobusFileSystem, url: str) -> None:
+        self.fs = fs
+        self.url = url
+
+    def __call__(self, start, end):
+        return sync(self.fs.loop, self.fs._cat_file, self.url, start=start, end=end)
+
+
+class GlobusFileSystem(HTTPFileSystem):
+    """Read files from Globus collections over HTTPS.
+
+    Parameters
+    ----------
+    collection_id:
+        Default collection UUID, used when a path omits the authority.
+    credentials:
+        A :class:`~globusfs.credentials.GlobusCredentials`. Defaults to
+        anonymous, which works for public collections and fails with a
+        clean 401 elsewhere.
+    https_url:
+        Override the collection's base URL instead of resolving it via
+        the Transfer API. Useful offline, in tests, and when the caller
+        already knows it.
+    retries:
+        Attempts before giving up on a transient backend fault.
+    """
+
+    protocol = "globus"
+    sep = "/"
+
+    def __init__(
+        self,
+        collection_id: str | None = None,
+        credentials: GlobusCredentials | None = None,
+        https_url: str | None = None,
+        retries: int = DEFAULT_RETRIES,
+        backoff: float = DEFAULT_BACKOFF,
+        metadata: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        self.collection_id = collection_id
+        self.credentials = credentials or AnonymousCredentials()
+        self._https_url = https_url.rstrip("/") if https_url else None
+        self.retries = retries
+        self.backoff = backoff
+        # TransferMetadata (or a stand-in). Optional: the byte path works
+        # without it, so reading public data needs no globus-sdk.
+        self.metadata = metadata
+        self._base_cache: dict[str, str] = {}
+        super().__init__(**kwargs)
+
+    @property
+    def fsid(self) -> str:
+        return "globus"
+
+    # ---------------------------------------------------------------- paths
+
+    @classmethod
+    def _strip_protocol(cls, path: str) -> str:
+        """``globus://uuid/a/b`` -> ``uuid/a/b``; leave bare paths alone."""
+        for prefix in ("globus://", "globus:/"):
+            if path.startswith(prefix):
+                path = path[len(prefix) :]
+                break
+        return path.lstrip("/").rstrip("/") or ""
+
+    def split_path(self, path: str) -> tuple[str, str]:
+        """Split a stripped path into ``(collection_id, remainder)``."""
+        stripped = self._strip_protocol(path)
+        if not stripped:
+            if not self.collection_id:
+                raise ValueError(
+                    "No collection: use globus://<collection-uuid>/path or pass "
+                    "collection_id= to GlobusFileSystem."
+                )
+            return self.collection_id, ""
+
+        head, _, tail = stripped.partition("/")
+        # A leading segment is the collection only when no default is set,
+        # or when it actually differs from the default. This lets both
+        # "uuid/a/b" and "a/b" work against a configured default.
+        if self.collection_id and head != self.collection_id:
+            return self.collection_id, stripped
+        return head, tail
+
+    def _url(self, path: str) -> str:
+        """Full HTTPS URL for a globus path.
+
+        Idempotent: an already-resolved ``https://`` URL passes through
+        unchanged. fsspec re-enters with whatever it was handed (``_open``
+        resolves, then the parent calls ``info`` with the result), so
+        resolving twice must not double the prefix.
+        """
+        if path.startswith(("http://", "https://")):
+            return path
+        collection, rel = self.split_path(path)
+        return (
+            f"{self._resolve_base(collection)}/{rel}"
+            if rel
+            else (self._resolve_base(collection) + "/")
+        )
+
+    def _resolve_base(self, collection_id: str) -> str:
+        """Map a collection UUID to its ``https_url``, caching the result."""
+        if self._https_url:
+            return self._https_url
+        if collection_id in self._base_cache:
+            return self._base_cache[collection_id]
+        if self.metadata is None:
+            raise ValueError(
+                f"Cannot resolve collection {collection_id} to a URL: pass "
+                f"https_url= if you know it, or metadata= (a TransferMetadata) "
+                f"to look it up."
+            )
+        base = self.metadata.https_url(collection_id)
+        self._base_cache[collection_id] = base
+        return base
+
+    # ------------------------------------------------------------ requests
+
+    def _auth_headers(self, path: str) -> dict[str, str]:
+        collection, _ = self.split_path(path)
+        token = self.credentials.token_for(collection)
+        return {"Authorization": f"Bearer {token}"} if token else {}
+
+    async def _check(self, response, url: str) -> None:
+        """Classify a response, distinguishing a backend fault from a miss.
+
+        This is async because the distinction lives in the response body
+        and aiohttp bodies must be awaited -- which is exactly why the
+        inherited sync ``_raise_not_found_for_status`` hook cannot do the
+        job on its own.
+        """
+        if response.status == 404:
+            body = await response.text(errors="ignore")
+            if is_transient_body(body):
+                raise TransientBackendError(
+                    f"{url}: GCS backend fault reported as HTTP 404. This is a "
+                    f"transient failure of the collection, not a missing file. "
+                    f"Body: {body[:200]!r}"
+                )
+            raise FileNotFoundError(url)
+        response.raise_for_status()
+
+    async def _retry(self, attempt_factory, what: str):
+        """Run ``attempt_factory()``, retrying transient backend faults.
+
+        Each attempt re-issues the request, because the failing backend is
+        selected at connect time and is sticky for that connection.
+        """
+        last: Exception | None = None
+        for attempt in range(1, self.retries + 1):
+            try:
+                return await attempt_factory()
+            except TransientBackendError as exc:
+                last = exc
+                if attempt < self.retries:
+                    logger.debug(
+                        "%s: transient backend fault (attempt %d/%d), retrying",
+                        what,
+                        attempt,
+                        self.retries,
+                    )
+                    await asyncio.sleep(self.backoff * attempt)
+        raise TransientBackendError(
+            f"{what}: {self.retries} attempts all hit GCS backend faults. The "
+            f"collection is degraded; this is not a missing file."
+        ) from last
+
+    async def _cat_file(self, path, start=None, end=None, **kwargs):
+        """Read bytes, retrying past transient backend faults.
+
+        Overridden rather than inherited so that a 404 gets classified
+        before fsspec turns it into ``FileNotFoundError``.
+        """
+        url = self._url(path)
+
+        async def attempt():
+            headers = dict(kwargs.pop("headers", {}))
+            headers.update(self._auth_headers(path))
+            if start is not None or end is not None:
+                if start == end:
+                    return b""
+                headers["Range"] = await self._process_limits(url, start, end)
+            session = await self.set_session()
+            async with session.get(
+                self.encode_url(url), headers=headers, **self.kwargs
+            ) as r:
+                if r.status >= 400:
+                    await self._check(r, url)
+                return await r.read()
+
+        return await self._retry(attempt, f"cat_file({path})")
+
+    # --------------------------------------------------------------- write
+
+    async def _pipe_file(self, path, value, mode="overwrite", **kwargs):
+        """Upload bytes with PUT.
+
+        GCS supports PUT on the same URL that serves GET, so writing is a
+        single request. Retried like reads: a backend fault must not be
+        mistaken for a permission or path problem.
+
+        Note there is no server-side atomicity. A PUT that fails partway
+        can leave a truncated object, so callers who need all-or-nothing
+        should write to a temporary name and rename via the Transfer API.
+        """
+        url = self._url(path)
+
+        async def attempt():
+            headers = dict(kwargs.pop("headers", {}))
+            headers.update(self._auth_headers(path))
+            session = await self.set_session()
+            async with session.put(
+                self.encode_url(url), data=value, headers=headers, **self.kwargs
+            ) as r:
+                if r.status >= 400:
+                    await self._check(r, url)
+                return
+
+        return await self._retry(attempt, f"pipe_file({path})")
+
+    async def _rm_file(self, path, **kwargs):
+        """Delete one file with DELETE."""
+        url = self._url(path)
+
+        async def attempt():
+            headers = dict(kwargs.pop("headers", {}))
+            headers.update(self._auth_headers(path))
+            session = await self.set_session()
+            async with session.delete(
+                self.encode_url(url), headers=headers, **self.kwargs
+            ) as r:
+                if r.status >= 400:
+                    await self._check(r, url)
+                return
+
+        return await self._retry(attempt, f"rm_file({path})")
+
+    # -------------------------------------------------------------- listing
+
+    # NOTE: both the async and sync forms are overridden on purpose.
+    # fsspec's mirror_sync_methods only wires sync `ls` -> `_ls` when the
+    # sync version is still AbstractFileSystem's default; HTTPFileSystem
+    # binds its own, so overriding `_ls` alone leaves the parent's HTML
+    # link-scraping in place and the override silently never runs.
+
+    _NEED_META = (
+        "{op}() needs the Transfer API: the Globus HTTPS interface has no "
+        "directory listings and its HEAD responses cannot be classified. "
+        "Construct with metadata=TransferMetadata(...) -- see the README."
+    )
+
+    def _metadata(self, op: str):
+        if self.metadata is None:
+            raise NotImplementedError(self._NEED_META.format(op=op))
+        return self.metadata
+
+    def ls(self, path, detail=True, **kwargs):
+        collection, rel = self.split_path(self._unresolve(path))
+        return self._metadata("ls").ls(collection, rel, detail=detail)
+
+    async def _ls(self, path, detail=True, **kwargs):
+        return self.ls(path, detail=detail, **kwargs)
+
+    def _unresolve(self, path: str) -> str:
+        """Inverse of :meth:`_url` for a base this filesystem knows.
+
+        ``_open`` hands the parent a resolved URL, and fsspec then calls
+        back into ``info``/``ls`` with it. Transfer speaks collection
+        paths, not URLs, so a URL coming back in has to be turned back
+        into ``uuid/rel`` before it is used as a path.
+        """
+        if not path.startswith(("http://", "https://")):
+            return path
+        bases = [self._https_url] if self._https_url else []
+        bases += list(self._base_cache.values())
+        for base in bases:
+            if base and path.startswith(base):
+                rel = path[len(base) :].lstrip("/")
+                collection = next(
+                    (c for c, b in self._base_cache.items() if b == base),
+                    self.collection_id,
+                )
+                return f"{collection}/{rel}" if collection else rel
+        return path
+
+    def info(self, path, **kwargs):
+        """Stat a path, preferring the Transfer API.
+
+        Falls back to a **ranged GET** when no Transfer client is
+        configured, so anonymous public reads keep working: ``open()``
+        needs a size, and a plain HEAD cannot supply one safely (a HEAD
+        404 has no body, so it cannot be told apart from a backend
+        fault). A ranged GET returns a body and puts the total in
+        ``Content-Range``.
+
+        The fallback can only ever report a file. Directory detection
+        genuinely requires Transfer.
+        """
+        collection, rel = self.split_path(self._unresolve(path))
+        if self.metadata is not None:
+            return self.metadata.info(collection, rel)
+        return {
+            "name": self._strip_protocol(path),
+            "size": self._size_via_range(path),
+            "type": "file",
+        }
+
+    def _size_via_range(self, path) -> int | None:
+        """Total size via an open-ended ranged GET.
+
+        Uses ``Range: bytes=0-`` rather than ``bytes=0-0``: GCS reports
+        the total as ``*`` in Content-Range (``bytes 0-0/*``), so a
+        one-byte probe cannot see the size. The open-ended form answers
+        ``bytes 0-<last>/*`` with a matching Content-Length, which does.
+        The body is never read, so this costs headers, not bytes.
+        """
+        url = self._url(path)
+
+        async def attempt():
+            headers = {"Range": "bytes=0-"}
+            headers.update(self._auth_headers(path))
+            session = await self.set_session()
+            async with session.get(
+                self.encode_url(url), headers=headers, **self.kwargs
+            ) as r:
+                if r.status >= 400:
+                    await self._check(r, url)
+                start, _, last = (
+                    r.headers.get("Content-Range", "")
+                    .removeprefix("bytes ")
+                    .partition("/")[0]
+                    .partition("-")
+                )
+                if start.isdigit() and last.isdigit():
+                    return int(last) - int(start) + 1
+                cl = r.headers.get("Content-Length")
+                return int(cl) if cl and cl.isdigit() else None
+
+        return sync(self.loop, self._retry, attempt, f"info({path})")
+
+    def _open(self, path, mode="rb", **kwargs):
+        """Open by resolved URL, with retry-aware block fetches.
+
+        Two fixes over the parent. It builds its file object straight
+        from the path it is handed (``uuid/rel``, not a URL), so the URL
+        is resolved first. And ``HTTPFile.async_fetch_range`` calls
+        ``raise_for_status()`` directly, bypassing the transient-404
+        classification -- so the returned file's fetcher is wrapped to
+        route block reads through :meth:`_cat_file`, which retries.
+        """
+        f = super()._open(self._url(path), mode=mode, **kwargs)
+        # The cache binds `self.fetcher = f._fetch_range` at construction,
+        # so rebinding the method afterwards is too late -- the cache must
+        # be repointed as well.
+        f._fetch_range = _RetryingFetcher(self, self._url(path))
+        if getattr(f, "cache", None) is not None:
+            f.cache.fetcher = f._fetch_range
+        return f
+
+    async def _info(self, path, **kwargs):
+        return self.info(path, **kwargs)
+
+    # HTTPFileSystem overrides _glob/_exists with logic built on scraping
+    # links out of HTML index pages -- meaningless for a Globus
+    # collection. Delegating to AbstractFileSystem puts them back on top
+    # of ls()/info(), which are Transfer-backed and correct.
+
+    def glob(self, path, maxdepth=None, **kwargs):
+        return AbstractFileSystem.glob(self, path, maxdepth=maxdepth, **kwargs)
+
+    async def _glob(self, path, maxdepth=None, **kwargs):
+        return self.glob(path, maxdepth=maxdepth, **kwargs)
+
+    def find(self, path, maxdepth=None, withdirs=False, detail=False, **kwargs):
+        return AbstractFileSystem.find(
+            self, path, maxdepth=maxdepth, withdirs=withdirs, detail=detail, **kwargs
+        )
+
+    async def _find(self, path, maxdepth=None, withdirs=False, detail=False, **kwargs):
+        return self.find(
+            path, maxdepth=maxdepth, withdirs=withdirs, detail=detail, **kwargs
+        )
+
+    def exists(self, path, **kwargs):
+        """True if the path exists.
+
+        Built on info() rather than the parent's HTTP probe so that a
+        transient backend fault propagates instead of being flattened
+        into "does not exist".
+        """
+        try:
+            self.info(path, **kwargs)
+        except FileNotFoundError:
+            return False
+        return True
+
+    async def _exists(self, path, **kwargs):
+        return self.exists(path, **kwargs)
+
+    def isdir(self, path):
+        try:
+            return self.info(path)["type"] == "directory"
+        except FileNotFoundError:
+            return False
+
+    async def _isdir(self, path):
+        return self.isdir(path)
+
+    def isfile(self, path):
+        try:
+            return self.info(path)["type"] == "file"
+        except FileNotFoundError:
+            return False
+
+    async def _isfile(self, path, **kwargs):
+        return self.isfile(path)

globusfs/credentials.py

@@ -0,0 +1,140 @@
+"""Credential providers for Globus collections.
+
+Kept separate from the filesystem because token acquisition is the part
+that varies: a public collection needs nothing, a portal has a token
+already, and an interactive user needs a browser login. The filesystem
+only ever asks for a bearer string.
+
+Two constraints drive the design here, both from the globus-sdk docs:
+
+* ``GlobusApp`` is explicitly **not thread safe**, but fsspec shares one
+  filesystem instance across threads. Anything wrapping an app has to
+  serialize access.
+* fsspec pickles filesystems to worker processes
+  (``AbstractFileSystem.__reduce__`` re-instantiates from the constructor
+  args). A live bearer token in those args would be written into every
+  worker payload, so providers serialize the *recipe* for getting a
+  token, never the token itself.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class GlobusCredentials(Protocol):
+    """Supplies bearer tokens for Globus collections."""
+
+    def token_for(self, collection_id: str) -> str | None:
+        """Return a bearer token for ``collection_id``, or None for anonymous.
+
+        Must be safe to call from multiple threads.
+        """
+        ...
+
+
+class AnonymousCredentials:
+    """No credentials; for collections that allow public read.
+
+    The default. Real collections will 401, which is the correct and
+    legible failure -- better than pulling in an auth dependency that
+    most reads of public data would not need.
+    """
+
+    def token_for(self, collection_id: str) -> str | None:
+        return None
+
+    def __repr__(self) -> str:
+        return "AnonymousCredentials()"
+
+
+class StaticToken:
+    """A token the caller already has.
+
+    Intended for portals and services that run their own OAuth flow, and
+    for tests. Note the token lives in memory for the life of the object;
+    ``__reduce__`` deliberately refuses to pickle it rather than silently
+    copying a secret into worker processes.
+    """
+
+    def __init__(self, token: str) -> None:
+        self._token = token
+
+    def token_for(self, collection_id: str) -> str | None:
+        return self._token
+
+    def __reduce__(self):
+        raise TypeError(
+            "StaticToken refuses to pickle: this would copy a bearer token "
+            "into every worker process and into any serialized fsspec state. "
+            "Use CallableToken with a function that reads the token from the "
+            "environment or a file, so workers re-read it instead."
+        )
+
+    def __repr__(self) -> str:
+        # Never render the token.
+        return "StaticToken(token=<redacted>)"
+
+
+class CallableToken:
+    """Fetch a token on demand from a user-supplied callable.
+
+    The pickle-safe way to carry credentials into dataloader workers: the
+    *function* crosses the process boundary, the secret does not. Point it
+    at an env var or a file on shared storage.
+
+    The callable may be invoked concurrently, so it must be thread-safe.
+    """
+
+    def __init__(self, fn: Callable[[str], str | None]) -> None:
+        self._fn = fn
+
+    def token_for(self, collection_id: str) -> str | None:
+        return self._fn(collection_id)
+
+    def __repr__(self) -> str:
+        return f"CallableToken(fn={getattr(self._fn, '__name__', '<callable>')})"
+
+
+class AppCredentials:
+    """Wrap a globus_sdk ``UserApp``/``ClientApp``.
+
+    Every call is serialized through a lock because GlobusApp is not
+    thread safe and fsspec will share this across threads.
+
+    Two things to get right when constructing the app:
+
+    * Set ``request_refresh_tokens=True``. It defaults to False, and
+      without it a long training run dies when the access token expires
+      mid-epoch.
+    * Point token storage at a path on shared storage. A UserApp cannot
+      run a browser login inside a dataloader worker, so workers must be
+      able to *load* tokens rather than acquire them.
+    """
+
+    def __init__(self, app, scope_suffix: str = "https") -> None:
+        self._app = app
+        self._scope_suffix = scope_suffix
+        self._lock = threading.Lock()
+
+    def token_for(self, collection_id: str) -> str | None:
+        """Current access token for a collection, refreshing if needed.
+
+        Goes through ``GlobusApp.get_authorizer()`` rather than reading
+        stored token data directly: the authorizer owns refresh, so an
+        expired access token is renewed here instead of failing a read
+        partway through a long job.
+        """
+        with self._lock:
+            authorizer = self._app.get_authorizer(collection_id)
+            # RefreshTokenAuthorizer renews on demand; others just hold one.
+            ensure = getattr(authorizer, "ensure_valid_token", None)
+            if ensure is not None:
+                ensure()
+            return getattr(authorizer, "access_token", None)
+
+    def __repr__(self) -> str:
+        return f"AppCredentials(scope_suffix={self._scope_suffix!r})"

globusfs/errors.py

@@ -0,0 +1,64 @@
+"""Exceptions, and the transient-vs-real 404 distinction.
+
+Globus Connect Server load-balances across GridFTP backends. When a
+backend is unhealthy it returns::
+
+    Mapping collection to specified ID failed.
+    GlobusError: v=1 c=ENDPOINT_ERROR
+    GCS Manager Internal Error
+
+with **HTTP status 404** -- byte-identical in status to a genuinely
+missing file. Measured against a healthy public collection, failure
+rates swung from 0/20 to 20/20 within minutes, hitting files,
+directories, and the collection root alike.
+
+This is the single most dangerous behavior of the platform for a
+filesystem client: fsspec maps 404 to ``FileNotFoundError``, so without
+this distinction a transient backend fault silently becomes "your data
+does not exist" -- intermittently, and only under load.
+
+The only signal is the response body.
+"""
+
+from __future__ import annotations
+
+# Markers seen in GCS backend-failure bodies. ENDPOINT_ERROR is what the
+# GCS Manager emits; INTERNAL_ERROR / GridFTP-Errno 108 is the older
+# GridFTP-level form.
+_TRANSIENT_MARKERS = (
+    "ENDPOINT_ERROR",
+    "INTERNAL_ERROR",
+    "GCS Manager Internal Error",
+)
+
+# GridFTP-Errno 2 is PATH_NOT_FOUND: a real, permanent miss.
+_PERMANENT_MARKERS = ("GridFTP-Errno: 2",)
+
+
+class GlobusFSError(Exception):
+    """Base for globusfs errors."""
+
+
+class TransientBackendError(GlobusFSError):
+    """A GCS backend failed a request that should have succeeded.
+
+    Raised only after retries are exhausted. Deliberately *not* a
+    subclass of ``FileNotFoundError``: the whole point is that callers
+    must not confuse it with absence.
+    """
+
+
+def is_transient_body(body: str | None) -> bool:
+    """True if a >=400 response body indicates backend flakiness.
+
+    A permanent marker wins if both appear, so a real miss is never
+    retried into a timeout.
+    """
+    if not body:
+        # No body is not evidence of a transient fault. Treating unknown
+        # as permanent keeps a real 404 fast; a genuine transient will
+        # normally carry the marker.
+        return False
+    if any(m in body for m in _PERMANENT_MARKERS):
+        return False
+    return any(m in body for m in _TRANSIENT_MARKERS)

globusfs/login.py

@@ -0,0 +1,211 @@
+"""Interactive login helper.
+
+Authenticating to Globus requires a browser and a human identity, so this
+cannot be automated. What it can do is make the flow one command and put
+the tokens somewhere workers can read them.
+
+Two settings here are load-bearing for HPC use:
+
+* ``refresh_tokens=True``. The SDK default is False, and without it an
+  access token expires (typically hours) and a long training run dies
+  mid-epoch.
+* Tokens land in a file, by default under ``~/.globusfs``. Dataloader
+  workers cannot run a browser flow, so they must *load* tokens rather
+  than acquire them. On a cluster, point this at shared storage.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# Globus's public tutorial native client, intended for exactly this.
+DEFAULT_CLIENT_ID = "61338d24-54d5-408f-a10d-66c06b59f6d2"
+TRANSFER_SCOPE = "urn:globus:auth:scope:transfer.api.globus.org:all"
+
+DEFAULT_TOKEN_PATH = Path(
+    os.environ.get("GLOBUSFS_TOKENS", Path.home() / ".globusfs" / "tokens.json")
+)
+
+
+def needs_data_access(collection_id: str, client=None) -> bool:
+    """True if a collection requires the ``data_access`` scope.
+
+    Only mapped, non-High-Assurance collections do. Guest collections
+    manage access through ACLs and High Assurance ones forbid it, so
+    requesting it where it does not apply costs the user a consent
+    prompt for nothing.
+
+    Needs an authenticated ``TransferClient``: the Transfer API rejects
+    unauthenticated metadata lookups (400, no credentials). Without one,
+    or if the lookup fails, errs toward True -- a needless prompt is a
+    smaller failure than omitting a scope that is genuinely required.
+    """
+    if client is None:
+        return True
+    try:
+        doc = client.get_endpoint(collection_id)
+    except Exception:  # noqa: BLE001 - detection must never block login
+        return True
+    if doc.get("high_assurance"):
+        return False
+    return "guest" not in (doc.get("entity_type") or "").lower()
+
+
+def _require_sdk():
+    """Import globus_sdk, or explain how to get it.
+
+    Deliberately narrow: it reports a *missing package* only when the
+    package is genuinely missing. An earlier version wrapped a wider
+    block and told users to install a dependency they already had,
+    hiding the real error (a renamed submodule).
+    """
+    try:
+        import globus_sdk
+    except ImportError as exc:  # pragma: no cover - trivial
+        raise ImportError(
+            "Logging in to Globus needs globus-sdk. "
+            "Install with: pip install 'globusfs[auth]'"
+        ) from exc
+    return globus_sdk
+
+
+def _json_token_storage(globus_sdk):
+    """Locate ``JSONTokenStorage`` across globus-sdk versions.
+
+    Renamed from ``globus_sdk.tokenstorage`` (v3) to
+    ``globus_sdk.token_storage`` (v4). Both are supported, so the
+    dependency floor does not have to jump a major version.
+    """
+    try:
+        from globus_sdk.token_storage import JSONTokenStorage  # v4+
+    except ImportError:
+        try:
+            from globus_sdk.tokenstorage import JSONTokenStorage  # v3
+        except ImportError as exc:
+            raise ImportError(
+                f"Cannot locate JSONTokenStorage in globus-sdk "
+                f"{getattr(globus_sdk, '__version__', '?')}: tried "
+                f"globus_sdk.token_storage (v4) and globus_sdk.tokenstorage "
+                f"(v3). Please report this with your globus-sdk version."
+            ) from exc
+    return JSONTokenStorage
+
+
+def collection_scopes(collection_id: str, data_access: bool = True) -> list[str]:
+    """Scopes needed to read one collection over HTTPS.
+
+    ``data_access`` applies only to **mapped**, non-High-Assurance
+    collections. Guest and High Assurance collections do not use it, and
+    requesting it there forces an avoidable extra consent prompt -- so
+    pass ``data_access=False`` for those. :func:`login` detects the
+    collection type automatically when it can.
+    """
+    base = f"https://auth.globus.org/scopes/{collection_id}"
+    scopes = [f"{base}/https"]
+    if data_access:
+        scopes.append(f"{base}/data_access")
+    return scopes
+
+
+def login(
+    collection_id: str | None = None,
+    client_id: str = DEFAULT_CLIENT_ID,
+    token_path: Path | str = DEFAULT_TOKEN_PATH,
+    data_access: bool | None = None,
+    run_flow: bool = True,
+):
+    """Log in to Globus and persist tokens.
+
+    Runs the login flow if the required scopes are not already held, then
+    returns a ``globus_sdk.UserApp`` usable for both Transfer and HTTPS.
+    Calling it again once tokens exist is cheap and does not re-prompt.
+
+    Parameters
+    ----------
+    data_access:
+        Whether to request the ``data_access`` scope. ``None`` (default)
+        detects it: mapped non-High-Assurance collections need it, guest
+        and High Assurance collections do not, and asking for it where it
+        does not apply costs an extra consent prompt. Detection is a
+        single unauthenticated metadata lookup; pass True/False to skip
+        it.
+    run_flow:
+        Set False to build the app without logging in (tests, or when the
+        caller drives the flow itself). The returned app will still
+        trigger a login on first use if it lacks tokens.
+    """
+    globus_sdk = _require_sdk()
+    JSONTokenStorage = _json_token_storage(globus_sdk)
+
+    token_path = Path(token_path)
+    token_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if data_access is None and collection_id:
+        # Detection needs an authenticated client, so log in for Transfer
+        # alone first; that consent is needed either way and is not
+        # wasted. Then re-enter with the answer.
+        probe = login(None, client_id, token_path, run_flow=run_flow)
+        try:
+            data_access = needs_data_access(
+                collection_id, globus_sdk.TransferClient(app=probe)
+            )
+        except Exception:  # noqa: BLE001 - fall back to the common case
+            data_access = True
+    elif data_access is None:
+        data_access = False
+
+    # Transfer needs data_access as a *dependent* scope, written
+    # `transfer:all[*<collection>/data_access]` -- not as a standalone
+    # requirement. Requesting it flat yields tokens that look complete but
+    # fail every operation_ls with 403 ConsentRequired.
+    transfer_scope = globus_sdk.Scope(TRANSFER_SCOPE)
+    if collection_id and data_access:
+        transfer_scope = transfer_scope.with_dependency(
+            globus_sdk.Scope(
+                f"https://auth.globus.org/scopes/{collection_id}/data_access",
+                optional=True,
+            )
+        )
+    requirements = {"transfer.api.globus.org": [transfer_scope]}
+    if collection_id:
+        # The HTTPS scope stays a direct requirement of the collection
+        # itself; only Transfer needs the dependent form.
+        requirements[collection_id] = collection_scopes(collection_id, data_access)
+
+    config = globus_sdk.GlobusAppConfig(
+        token_storage=JSONTokenStorage(str(token_path)),
+        # Not the SDK default; without it long runs die on token expiry.
+        request_refresh_tokens=True,
+    )
+    app = globus_sdk.UserApp(
+        "globusfs", client_id=client_id, config=config, scope_requirements=requirements
+    )
+    # Constructing the app does NOT authenticate. Without this the call
+    # returns cleanly, writes no tokens, and the failure only shows up
+    # later as a surprise login prompt from deep inside a read.
+    if run_flow and app.login_required():
+        app.login()
+    return app
+
+
+def filesystem(collection_id: str, app=None, **kwargs):
+    """Build a ready-to-use :class:`GlobusFileSystem` for one collection.
+
+    Convenience wrapper: logs in if needed, resolves the collection's
+    HTTPS URL, and wires up Transfer-backed listing.
+    """
+    import globus_sdk
+
+    from .core import GlobusFileSystem
+    from .credentials import AppCredentials
+    from .transfer import TransferMetadata
+
+    app = app or login(collection_id)
+    client = globus_sdk.TransferClient(app=app)
+    return GlobusFileSystem(
+        collection_id=collection_id,
+        credentials=AppCredentials(app),
+        metadata=TransferMetadata(client),
+        **kwargs,
+    )

globusfs/transfer.py

@@ -0,0 +1,143 @@
+"""Transfer-API-backed metadata: the half HTTPS cannot provide.
+
+The Globus HTTPS interface serves bytes but has no directory listings,
+and its ``HEAD`` responses are unclassifiable (a 404 from HEAD carries no
+body, and the body is the only thing separating a backend fault from a
+real miss). So ``ls``/``info`` come from the Transfer API instead, which
+returns real name/size/type/last_modified via ``operation_ls`` and
+``operation_stat``.
+
+The Transfer API also supplies true file sizes, which neutralizes a third
+quirk: GCS answers suffix ranges (``bytes=-8``) with 416, the usual way
+parquet readers seek to a footer. With the size known, readers address
+the footer absolutely.
+
+Kept in its own module so the byte path stays usable with no globus-sdk
+installed -- anonymous public collections need nothing else.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .errors import TransientBackendError, is_transient_body
+
+
+def _require_sdk():
+    try:
+        import globus_sdk
+    except ImportError as exc:  # pragma: no cover - trivial
+        raise ImportError(
+            "Listing Globus collections needs the Transfer API. "
+            "Install with: pip install 'globusfs[auth]'"
+        ) from exc
+    return globus_sdk
+
+
+def _stat_to_info(entry: dict[str, Any], path: str) -> dict[str, Any]:
+    """Convert a Globus ``file`` document to an fsspec info dict.
+
+    Globus types are ``dir``/``file`` plus the unix special types
+    (``chr``, ``blk``, ``pipe``, ``other``). Anything that is not a
+    directory is reported to fsspec as a file, since fsspec has no richer
+    vocabulary and callers only ever read bytes.
+    """
+    gtype = entry.get("type")
+    return {
+        "name": path,
+        "size": entry.get("size"),
+        "type": "directory" if gtype == "dir" else "file",
+        "globus_type": gtype,
+        "last_modified": entry.get("last_modified"),
+    }
+
+
+class TransferMetadata:
+    """Metadata lookups for one collection, via a ``TransferClient``.
+
+    Parameters
+    ----------
+    client:
+        A ``globus_sdk.TransferClient``. Injected rather than constructed
+        here so the caller owns login, and so tests can pass a fake.
+    """
+
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    @classmethod
+    def from_authorizer(cls, authorizer: Any) -> TransferMetadata:
+        globus_sdk = _require_sdk()
+        return cls(globus_sdk.TransferClient(authorizer=authorizer))
+
+    def https_url(self, collection_id: str) -> str:
+        """Resolve a collection UUID to the base URL that serves bytes."""
+        ep = self._client.get_endpoint(collection_id)
+        url = ep.get("https_server")
+        if not url:
+            raise ValueError(
+                f"Collection {collection_id} reports no https_server, so it "
+                f"cannot serve files over HTTPS. Only Globus Connect Server "
+                f"collections with HTTPS enabled are readable this way."
+            )
+        return str(url).rstrip("/")
+
+    @staticmethod
+    def _abs(path: str) -> str:
+        """Anchor a path at the collection root.
+
+        Globus resolves a *relative* path against ``/~/`` (the mapped
+        user's home), so ``home`` becomes ``/~/home`` and 404s while
+        ``/home`` lists fine. Paths reaching here have already been
+        stripped of their protocol and leading slash by fsspec, so
+        absoluteness has to be restored or every nested listing fails.
+        """
+        return "/" + path.lstrip("/") if path else "/"
+
+    def info(self, collection_id: str, path: str) -> dict[str, Any]:
+        """Stat one path. Raises FileNotFoundError if genuinely absent."""
+        globus_sdk = _require_sdk()
+        try:
+            res = self._client.operation_stat(collection_id, path=self._abs(path))
+        except globus_sdk.TransferAPIError as exc:
+            raise self._translate(exc, collection_id, path) from exc
+        # GlobusHTTPResponse is not dict()-able (dict() iterates it as a
+        # sequence and fails); .data is the underlying document.
+        return _stat_to_info(res.data, path)
+
+    def ls(
+        self, collection_id: str, path: str, detail: bool = True
+    ) -> list[dict[str, Any]] | list[str]:
+        globus_sdk = _require_sdk()
+        try:
+            res = self._client.operation_ls(collection_id, path=self._abs(path))
+        except globus_sdk.TransferAPIError as exc:
+            raise self._translate(exc, collection_id, path) from exc
+
+        base = path.rstrip("/")
+        out = [
+            _stat_to_info(e, f"{base}/{e['name']}" if base else e["name"]) for e in res
+        ]
+        return out if detail else [e["name"] for e in out]
+
+    @staticmethod
+    def _translate(exc: Any, collection_id: str, path: str) -> Exception:
+        """Map a TransferAPIError to the right Python exception.
+
+        The same transient-vs-permanent care as the HTTPS path: a backend
+        fault must never surface as ``FileNotFoundError``, or callers will
+        conclude healthy data is missing.
+        """
+        code = getattr(exc, "code", "") or ""
+        message = getattr(exc, "message", "") or str(exc)
+
+        if is_transient_body(f"{code} {message}"):
+            return TransientBackendError(
+                f"{collection_id}:{path}: Globus backend fault ({code}). "
+                f"Transient, not a missing file."
+            )
+        if "NotFound" in code or "ClientError.NotFound" == code:
+            return FileNotFoundError(f"{collection_id}:{path}")
+        if getattr(exc, "http_status", None) == 404:
+            return FileNotFoundError(f"{collection_id}:{path}")
+        return exc

globusfs-0.1.0.dist-info/METADATA

@@ -0,0 +1,195 @@
+Metadata-Version: 2.5
+Name: globusfs
+Version: 0.1.0
+Summary: fsspec filesystem for Globus collections
+Project-URL: Homepage, https://github.com/saforem2/globusfs
+Project-URL: Source, https://github.com/saforem2/globusfs
+Project-URL: Issues, https://github.com/saforem2/globusfs/issues
+Author-email: Sam Foreman <saforem2@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Sam Foreman
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: data,filesystem,fsspec,globus,hpc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Filesystems
+Requires-Python: >=3.10
+Requires-Dist: aiohttp
+Requires-Dist: fsspec>=2023.1
+Provides-Extra: auth
+Requires-Dist: globus-sdk>=3.30; extra == 'auth'
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: requests; extra == 'dev'
+Requires-Dist: ruff>=0.14; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# globusfs
+
+An [fsspec](https://filesystem-spec.readthedocs.io/) filesystem for
+[Globus](https://www.globus.org/) collections.
+
+> **Status: working.** Verified against three live collections —
+> including **ALCF Eagle** (`alcf#dtn_eagle`, 747 project directories),
+> where `ls`, `glob`, `info`, `open()` with mid-file seek, and sparse
+> ranged reads all work against production Lustre. Writes (`PUT`/`DELETE`)
+> round-trip on Globus Tutorial Collection 1. Anonymous pyarrow column
+> projection works on a public collection — one column of sixty, a few KB
+> instead of 360 KB — while that collection was intermittently returning
+> backend-fault 404s.
+
+```python
+import globusfs
+
+# Browser login once; tokens persist to ~/.globusfs/tokens.json
+fs = globusfs.filesystem("<collection-uuid>")
+
+fs.ls("/")
+with fs.open("data/file.parquet", "rb") as f:
+    ...
+```
+
+Public collections need no credentials — and no `globus-sdk`:
+
+```python
+import fsspec, pyarrow.parquet as pq
+
+fs = fsspec.filesystem(
+    "globus",
+    collection_id="isaac",
+    https_url="https://g-05a4b6.2d513.8443.data.globus.org",
+)
+
+with fs.open("isaac/ability/ALL_2007-01.parquet", "rb") as f:
+    # Reads only the bytes this column needs, over HTTP range requests.
+    table = pq.ParquetFile(f).read(columns=["author"])
+```
+
+## Why
+
+Globus is how large scientific datasets actually move between facilities,
+but there is no fsspec backend for it — so pyarrow, pandas, dask, and
+grain can't read a Globus collection the way they read `s3://` or
+`gs://`. This fills that gap with one backend that serves all of them.
+
+## How it works
+
+Globus Connect Server exposes two services, and this needs both:
+
+| Concern | Service | Why |
+|---|---|---|
+| Reading bytes | HTTPS collection endpoint | Serves full HTTP range semantics: 206, `Content-Range`, mid-file seeks, multipart |
+| Listing / metadata | Transfer API | The HTTPS interface has no directory listings |
+
+The read path subclasses `fsspec`'s `HTTPFileSystem`, which already
+speaks exactly the range dialect GCS serves.
+
+### Server quirks this works around
+
+Verified against a live collection:
+
+- **Backend flakiness surfaces as a `404`.** GCS load-balances across
+  GridFTP backends; a failing one returns `ENDPOINT_ERROR` / `GCS Manager
+  Internal Error` rendered as HTTP 404 — byte-identical in status to a
+  genuinely missing file, and sticky for the life of a connection.
+  Observed failure rates on the public test collection swung from 0/20 to
+  20/20 within minutes, hitting files, directories, and the collection
+  root alike. Retries need a *fresh* connection, and the only way to tell
+  a transient error from a real miss is to parse the body. **A client
+  that treats 404 as "absent" will report healthy data as missing.**
+- **Suffix ranges (`bytes=-8`) return `416`**, which is how parquet
+  readers typically seek to the footer. Because `info()` knows the true
+  size, readers can use absolute offsets instead.
+- **`HEAD` is unusable.** A HEAD 404 carries no body — and the body is
+  the *only* thing distinguishing a backend fault from a real miss. So
+  HEAD results are permanently ambiguous. Size and existence come from
+  the Transfer API, or from a ranged `GET` (which does return a body and
+  carries the total in `Content-Range`).
+- **The HTTPS interface has no directory listings at all** — hence the
+  Transfer API for metadata.
+
+## Known ALCF collections
+
+Resolved via `endpoint_search`; ALCF's docs list names, not UUIDs.
+
+| Collection | UUID | Type |
+|---|---|---|
+| `alcf#dtn_eagle` | `05d2c76a-e867-4f67-aa57-76edeb0beda0` | mapped |
+| `alcf#dtn_flare` | `f39a7a0f-5bfc-46ce-9615-ba9f8592814f` | mapped |
+| `alcf#dtn_grand` | `3caddd4a-bb35-4c3d-9101-d9a0ad7f3a30` | mapped |
+| Globus Tutorials on ALCF Eagle | `a6f165fa-aee2-4fe5-95f3-97429c28bf82` | guest, public |
+
+Eagle's collection root is already `/eagle/projects`, so paths are
+project-relative: `fs.ls("/datascience")`, not `/eagle/projects/datascience`.
+
+Expect roughly **2 s per metadata or read operation** through the DTN —
+fine for sparse reads and exploration, not for per-record access in a
+training loop. See the note on training workloads below.
+
+## Credentials
+
+Token acquisition is pluggable, because it varies more than anything
+else: a public collection needs nothing, a portal already has a token,
+an interactive user needs a browser.
+
+| Provider | Use |
+|---|---|
+| `AnonymousCredentials` | Public collections (default) |
+| `StaticToken` | A token you already hold |
+| `CallableToken` | Fetch on demand — the pickle-safe option |
+| `AppCredentials` | Wraps `globus_sdk` `UserApp`/`ClientApp` |
+
+Two constraints worth knowing, both from the globus-sdk docs:
+
+- **`GlobusApp` is not thread-safe**, but fsspec shares one filesystem
+  across threads. `AppCredentials` serializes every call through a lock.
+- **fsspec pickles filesystems to worker processes.** A live token in the
+  constructor args would be copied into every worker payload, so
+  `StaticToken` refuses to pickle; use `CallableToken` reading from the
+  environment or shared storage so workers re-read rather than receive.
+
+Also set `request_refresh_tokens=True` — it defaults to `False`, and
+without it a long run dies when the access token expires mid-epoch.
+
+## A note on training workloads
+
+This is built for *remote and sparse* reads: column projection,
+exploration, data not yet staged. For distributed training, staging with
+Globus Transfer to node-local scratch beats per-record HTTPS on every
+axis — no per-record latency, no token expiry mid-epoch, and it works
+with formats like ArrayRecord whose readers do their own seeking.
+
+## Tests
+
+Characterization tests hit a real public collection and are marked
+`network`:
+
+```bash
+pytest                    # everything
+pytest -m "not network"   # offline only
+```
+
+## License
+
+MIT

globusfs-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+globusfs/__init__.py,sha256=PmAnKEFosF5vDC4Dlnj26kkM2tJh58sB6eFIiVQPiCk,633
+globusfs/core.py,sha256=rTK_9WNVez6yDmL0BJzxPLpRxvu5OfHaAcld19rjFec,19148
+globusfs/credentials.py,sha256=HzpyvEiP2pzfoUwrWpsauyZmnkaoWCP2SeepY9BT2kI,5026
+globusfs/errors.py,sha256=AJbjTPioc4KasMMVKErKrCkxkCz0vdadIorO6O8p1lU,2171
+globusfs/login.py,sha256=gFCGvHEspPoM-3zvuguEiTWVTk_-kCKTAQFKlDu43so,8208
+globusfs/transfer.py,sha256=dG2fU5wq_WFw0mv0hfB0AywIJoSKH9AyXSoDt_3XF1Y,5642
+globusfs-0.1.0.dist-info/METADATA,sha256=SumkyMvKMrsBZ7S-Wr035QHMmpkpXaWgRE-BSx4RKpo,8037
+globusfs-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+globusfs-0.1.0.dist-info/entry_points.txt,sha256=T56Qbm74xtAyb2hFOhxBmCoCeL38yrcr6h8TJamE654,50
+globusfs-0.1.0.dist-info/licenses/LICENSE,sha256=XdTXLjEKBNTBqjyjVWs1MIQBryn4Fq5lPvzMMW9biKo,1068
+globusfs-0.1.0.dist-info/RECORD,,

globusfs-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

globusfs-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[fsspec.specs]
+globus = globusfs:GlobusFileSystem

globusfs-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sam Foreman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.