Skip to content

livery.workshop._tokens

livery.workshop._tokens

The forge token surface: two names, host-qualified variants.

FORGE_TOKEN and FORGE_ADMIN_TOKEN are the only token names the workshop speaks. The shared rung may store host-qualified variants (FORGE_TOKEN__<HOST>), resolved through the contract's forge URL, so one machine serves several forges and two instances of one kind never collide. Everything per-forge (ambient job tokens, secret APIs, dialects, their own fallback variables) lives in the backends.

Functions:

Name Description
host_qualifier

The key suffix the contract's forge resolves through.

forge_token

The everyday token and the variable that supplied it.

admin_token

The admin ladder: FORGE_ADMIN_TOKEN first, then the everyday token.

host_qualifier

host_qualifier(kind: str, url: str) -> str

The key suffix the contract's forge resolves through.

The host (and port, when one is spelled) uppercased, every other character folded to _: https://forge.example.com:3000 is FORGE_EXAMPLE_COM_3000. Empty when neither the URL nor the kind names a host, and the bare names are the whole ladder.

Source code in packages/workshop/src/livery/workshop/_tokens.py
def host_qualifier(kind: str, url: str) -> str:
    """The key suffix the contract's forge resolves through.

    The host (and port, when one is spelled) uppercased, every other
    character folded to ``_``: ``https://forge.example.com:3000`` is
    ``FORGE_EXAMPLE_COM_3000``. Empty when neither the URL nor the
    kind names a host, and the bare names are the whole ladder.
    """
    host = urlparse(url).netloc if url else ""
    if not host:
        host = _DEFAULT_HOSTS.get(kind, "")
    return re.sub(r"[^A-Z0-9]", "_", host.upper())

forge_token

forge_token(kind: str, url: str) -> tuple[str, str]

The everyday token and the variable that supplied it.

Host-qualified first, then bare FORGE_TOKEN; both empty means the backend's own documented resolution decides (GitHub asks gh auth token; a backend may read its own dialect's variables).

Source code in packages/workshop/src/livery/workshop/_tokens.py
def forge_token(kind: str, url: str) -> tuple[str, str]:
    """The everyday token and the variable that supplied it.

    Host-qualified first, then bare ``FORGE_TOKEN``; both empty means
    the backend's own documented resolution decides (GitHub asks
    ``gh auth token``; a backend may read its own dialect's
    variables).
    """
    return _lookup("FORGE_TOKEN", host_qualifier(kind, url))

admin_token

admin_token(kind: str, url: str) -> tuple[str, str]

The admin ladder: FORGE_ADMIN_TOKEN first, then the everyday token.

The fallback keeps a solo developer whose one token already administers working with nothing extra. The variable name rides along so a refusal can teach the missing grant; it is empty when nothing resolved.

Source code in packages/workshop/src/livery/workshop/_tokens.py
def admin_token(kind: str, url: str) -> tuple[str, str]:
    """The admin ladder: ``FORGE_ADMIN_TOKEN`` first, then the everyday token.

    The fallback keeps a solo developer whose one token already
    administers working with nothing extra. The variable name rides
    along so a refusal can teach the missing grant; it is empty when
    nothing resolved.
    """
    token, var = _lookup("FORGE_ADMIN_TOKEN", host_qualifier(kind, url))
    if token:
        return token, var
    return forge_token(kind, url)