mundane.api.set_loader

Fetch, allowlist, validate, and snapshot external card sets — the only HTTP-aware card code.

The engine never reaches the network; this module does. Given a list of set URLs it: (1) allowlists each (only the mundane-cards raw origin), (2) fetches with hardening (https, timeout, no redirects, size cap, content-type check), (3) validates each body against the vendored schema, (4) builds the cards via the engine loader, rejecting duplicate composed ids, and (5) returns the resolved pool plus a JSON-ready snapshot with a content hash so an exported game replays self-contained. On any failure it raises before the caller stores anything.

Attributes

DEFAULT_SET_URLS
ALLOWLIST_HOST
ALLOWLIST_PATH_PREFIX
MAX_SET_BYTES
FETCH_TIMEOUT_SECONDS
_SCHEMA
_VALIDATOR
Fetcher	Fetches the raw bytes of a set at a URL. Injectable so tests can serve a fixture offline.

Exceptions

SetURLNotAllowedError	A requested set URL is not on the allowlist. Maps to HTTP 422.
SetFetchError	A set could not be fetched (network, timeout, status, content-type, or size). Maps to 502.
SetSchemaError	A fetched set was not valid JSON or failed schema validation. Maps to HTTP 422.

Classes

ResolvedPool

The engine-facing pool plus the serialisable snapshot (resolved cards + content hash).

Functions

_check_allowed(→ None)	Reject url unless it is https, exactly on host, and under prefix (parsed, not substring).
default_fetch(→ bytes)	Fetch url with hardening: a hard timeout, no redirects, a size cap, and a content-type check.
load_sets(→ ResolvedPool)	Allowlist, fetch, validate, and build the combined pool + snapshot for set_urls.

Module Contents

mundane.api.set_loader.DEFAULT_SET_URLS: tuple[str, Ellipsis] = ('https://raw.githubusercontent.com/letsbuilda/mundane-cards/main/sets/core.json',)

mundane.api.set_loader.ALLOWLIST_HOST = 'raw.githubusercontent.com'

mundane.api.set_loader.ALLOWLIST_PATH_PREFIX = '/letsbuilda/mundane-cards/'

mundane.api.set_loader.MAX_SET_BYTES = 1048576

mundane.api.set_loader.FETCH_TIMEOUT_SECONDS = 5.0

mundane.api.set_loader._SCHEMA: dict[str, object]

mundane.api.set_loader._VALIDATOR

mundane.api.set_loader.Fetcher

Fetches the raw bytes of a set at a URL. Injectable so tests can serve a fixture offline.

exception mundane.api.set_loader.SetURLNotAllowedError

Bases: Exception

A requested set URL is not on the allowlist. Maps to HTTP 422.

exception mundane.api.set_loader.SetFetchError

Bases: Exception

A set could not be fetched (network, timeout, status, content-type, or size). Maps to 502.

exception mundane.api.set_loader.SetSchemaError

Bases: Exception

A fetched set was not valid JSON or failed schema validation. Maps to HTTP 422.

class mundane.api.set_loader.ResolvedPool

The engine-facing pool plus the serialisable snapshot (resolved cards + content hash).

cards: dict[str, mundane.engine.state.Card]

snapshot: dict[str, object]

mundane.api.set_loader._check_allowed(url: str, host: str, prefix: str) → None

Reject url unless it is https, exactly on host, and under prefix (parsed, not substring).

mundane.api.set_loader.default_fetch(url: str) → bytes

Fetch url with hardening: a hard timeout, no redirects, a size cap, and a content-type check.

mundane.api.set_loader.load_sets(set_urls: collections.abc.Sequence[str], *, fetch: Fetcher = default_fetch, allowlist_host: str = ALLOWLIST_HOST, allowlist_prefix: str = ALLOWLIST_PATH_PREFIX) → ResolvedPool

Allowlist, fetch, validate, and build the combined pool + snapshot for set_urls.

Raises before returning on any problem: SetURLNotAllowedError / SetSchemaError / engine UnknownEffectError / InvalidEffectParamsError / DuplicateCardError (all 422 at the API), or SetFetchError (502).