"""The one rule about identifier origins.
A capability or protocol identifier is `https://<origin>/<name>/<major>.<minor>`.
The Fleetmesh origin (the one every PIURI in schema/messages.json shares) is
RESERVED: identifiers under it are governed by the schema digest, so nothing
registered at runtime -- a plugin's wire protocol, a sidecar manifest, an
operator config entry -- may claim one. Everyone else uses their own origin.
This module is a leaf: standard library only, zero dependencies.
"""
from __future__ import annotations
import urllib.parse
__all__ = ['origin_of', 'reserved']
[docs]def origin_of(identifier: str) -> str:
"""`https://<host>/grasp/1.0` -> `https://<host>/`.
Scheme and host via urllib.parse, not a character-wise prefix: a prefix
every identifier shares by accident would refuse one of our own protocols
added later and admit a lookalike host as foreign. ValueError when the
identifier is not https://<host>/...
"""
parts = urllib.parse.urlsplit(identifier)
if parts.scheme != 'https' or not parts.hostname or parts.username or parts.password:
raise ValueError('identifier is not https://<origin>/...: %r' % (identifier,))
return '%s://%s/' % (parts.scheme, parts.netloc)
[docs]def reserved(identifier: str, origin: str) -> bool:
"""True when `identifier` lives under the reserved `origin`.
Compared origin-to-origin after normalisation, never by string prefix,
so a lookalike host that merely starts with ours is foreign and a
trailing-slash difference is not a loophole.
"""
try:
return origin_of(identifier).rstrip('/') == origin.rstrip('/')
except ValueError:
return False