dirigent-common 0.9.0__tar.gz

dirigent_common-0.9.0/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2026 Morten Olav Hansen <morten@winterop.com>. All rights reserved.
+
+This source code and accompanying documentation are the property of
+Morten Olav Hansen. No license, express or implied, is granted to use, copy,
+modify, merge, publish, distribute, sublicense, or sell copies of this
+software or its derivatives.
+
+The source is published for reference only. Any use beyond reading
+requires written permission from the copyright holder.
+
+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 COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES,
+OR OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE.
+
+Third-party components redistributed with this software, and the licences they
+carry, are listed in THIRD_PARTY_NOTICES.md.

dirigent_common-0.9.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: dirigent-common
+Version: 0.9.0
+Summary: Value types and shared schemas every dirigent package may depend on.
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
+Requires-Dist: httpx2>=2.12.0
+Requires-Dist: jsonschema[format-nongpl]>=4.23.0
+Requires-Dist: pydantic>=2.13.5
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# dirigent-common
+
+Value types and shared schemas every other dirigent package may depend on, and which depend on
+nothing of dirigent's in turn.
+
+A `Duration` a document writes as `30s`, a `Size` it writes as `16KB`, the name rules an entity
+obeys, and the small schemas more than one package has to agree on. It holds nothing about
+blocks, the wire, or the engine: those are `dirigent-plugin`, `dirigent-client` and
+`dirigent-core`, all of which may depend on this and none of which it knows about.
+
+See [the architecture page](../../docs/architecture.md) for what belongs here and what does not.

dirigent_common-0.9.0/README.md

@@ -0,0 +1,11 @@
+# dirigent-common
+
+Value types and shared schemas every other dirigent package may depend on, and which depend on
+nothing of dirigent's in turn.
+
+A `Duration` a document writes as `30s`, a `Size` it writes as `16KB`, the name rules an entity
+obeys, and the small schemas more than one package has to agree on. It holds nothing about
+blocks, the wire, or the engine: those are `dirigent-plugin`, `dirigent-client` and
+`dirigent-core`, all of which may depend on this and none of which it knows about.
+
+See [the architecture page](../../docs/architecture.md) for what belongs here and what does not.

dirigent_common-0.9.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "dirigent-common"
+version = "0.9.0"
+description = "Value types and shared schemas every dirigent package may depend on."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+dependencies = [
+    "httpx2>=2.12.0",
+    "jsonschema[format-nongpl]>=4.23.0",
+    "pydantic>=2.13.5",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"

dirigent_common-0.9.0/pyproject.toml.orig

@@ -0,0 +1,19 @@
+[project]
+name = "dirigent-common"
+version = "0.9.0"
+description = "Value types and shared schemas every dirigent package may depend on."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+dependencies = [
+    "httpx2>=2.12.0",
+    # nongpl: the format-nongpl extra pulls permissively-licensed format validators, not the
+    # GPL rfc3987 the plain format extra carries -- safe while the project's own licence is undecided.
+    "jsonschema[format-nongpl]>=4.23.0",
+    "pydantic>=2.13.5",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"

dirigent_common-0.9.0/src/dirigent_common/__init__.py

@@ -0,0 +1,96 @@
+"""Value types and shared schemas every dirigent package may depend on.
+
+This package knows nothing of blocks, the wire, or the engine. Everything here is something
+more than one package has to agree on: how a document spells a duration or a size, what a
+name may be, and the small schemas a plugin and the API both name.
+"""
+
+from dirigent_common.clients import build_client
+from dirigent_common.docstrings import as_markdown
+from dirigent_common.durations import (
+    DURATION_PATTERN,
+    Duration,
+    DurationError,
+    HumaneJsonSchema,
+    NegativeDuration,
+    format_duration,
+    parse_duration,
+    to_timedelta,
+)
+from dirigent_common.formats import base_format_checker, format_checker_with
+from dirigent_common.formatters import Formatter
+from dirigent_common.names import (
+    EMAIL_MAX_LENGTH,
+    EMAIL_PATTERN,
+    ENTITY_NAME_MAX_LENGTH,
+    ENTITY_NAME_PATTERN,
+    STEP_NAME_MAX_LENGTH,
+    STEP_NAME_PATTERN,
+    Email,
+    EntityName,
+    StepName,
+    entity_name_error,
+    is_entity_name,
+    is_step_name,
+    step_name_error,
+)
+from dirigent_common.programs import JQ_MEDIA_TYPE, SHELL_MEDIA_TYPE
+from dirigent_common.schemas import BlockModel, HealthReport, HttpConnectionConfig
+from dirigent_common.sizes import (
+    SIZE_PATTERN,
+    NegativeSize,
+    Size,
+    SizeError,
+    format_size,
+    parse_size,
+)
+from dirigent_common.types import JsonList, JsonMap
+from dirigent_common.uris import STORAGE_URI_FORMAT, StorageUri
+from dirigent_common.values import spelled
+from dirigent_common.versions import API_VERSION
+
+__all__ = [
+    "base_format_checker",
+    "format_checker_with",
+    "API_VERSION",
+    "DURATION_PATTERN",
+    "EMAIL_MAX_LENGTH",
+    "EMAIL_PATTERN",
+    "ENTITY_NAME_MAX_LENGTH",
+    "ENTITY_NAME_PATTERN",
+    "JQ_MEDIA_TYPE",
+    "SHELL_MEDIA_TYPE",
+    "SIZE_PATTERN",
+    "STORAGE_URI_FORMAT",
+    "STEP_NAME_MAX_LENGTH",
+    "STEP_NAME_PATTERN",
+    "BlockModel",
+    "Duration",
+    "DurationError",
+    "Email",
+    "EntityName",
+    "Formatter",
+    "HealthReport",
+    "HttpConnectionConfig",
+    "HumaneJsonSchema",
+    "JsonList",
+    "JsonMap",
+    "NegativeDuration",
+    "NegativeSize",
+    "Size",
+    "SizeError",
+    "StepName",
+    "StorageUri",
+    "as_markdown",
+    "entity_name_error",
+    "build_client",
+    "format_duration",
+    "format_size",
+    "is_entity_name",
+    "is_step_name",
+    "parse_duration",
+    "parse_size",
+    "spelled",
+    "step_name_error",
+    "to_timedelta",
+]

dirigent_common-0.9.0/src/dirigent_common/clients.py

@@ -0,0 +1,27 @@
+"""Turning a connection's configuration into the client that talks to it.
+
+This lives beside the configuration rather than in the standard library of blocks, so an
+adapter pack can use the shared HTTP connection without depending on that library.
+"""
+
+import httpx2
+
+from dirigent_common.schemas import HttpConnectionConfig
+
+
+def build_client(config: HttpConnectionConfig) -> httpx2.AsyncClient:
+    """Build a client carrying a connection's base URL, auth, TLS setting, and timeout."""
+    headers: dict[str, str] = {}
+    if config.bearer_token is not None:
+        headers["Authorization"] = f"Bearer {config.bearer_token.get_secret_value()}"
+    auth: httpx2.Auth | None = None
+    if config.basic_username:
+        password = config.basic_password.get_secret_value() if config.basic_password else ""
+        auth = httpx2.BasicAuth(config.basic_username, password)
+    return httpx2.AsyncClient(
+        base_url=config.base_url,
+        headers=headers,
+        auth=auth,
+        verify=config.verify_tls,
+        timeout=config.timeout.total_seconds(),
+    )

dirigent_common-0.9.0/src/dirigent_common/docstrings.py

@@ -0,0 +1,18 @@
+"""Reading a Python docstring as the markdown every reader of it renders.
+
+A description of a block's config, a setting or a surface is authored as a docstring, so it is
+written in reStructuredText; the UI, the CLI and the generated reference all render markdown.
+This is the rule for crossing between the two, and it is applied where a docstring becomes a
+description rather than by anything that later reads one.
+"""
+
+import re
+from typing import Final
+
+#: A reStructuredText inline literal, which is how a docstring writes code.
+RST_LITERAL: Final = re.compile(r"``(.+?)``", re.DOTALL)
+
+
+def as_markdown(text: str) -> str:
+    """Rewrite a docstring's inline literals as markdown inline code."""
+    return RST_LITERAL.sub(r"`\1`", text)

dirigent_common-0.9.0/src/dirigent_common/durations.py

@@ -0,0 +1,182 @@
+"""Humane durations: ``30s`` and ``5m`` in a document, ``timedelta`` in the engine."""
+
+import re
+from datetime import timedelta
+from typing import Annotated, Any, Final, cast
+
+from pydantic import AfterValidator, BeforeValidator, PlainSerializer, WithJsonSchema
+from pydantic.json_schema import GenerateJsonSchema, JsonSchemaMode, JsonSchemaValue
+from pydantic_core import CoreSchema
+
+#: Ordered largest first; the greedy decomposition in :func:`format_duration` depends on it.
+UNITS: Final[tuple[tuple[str, float], ...]] = (
+    ("w", 604800.0),
+    ("d", 86400.0),
+    ("h", 3600.0),
+    ("m", 60.0),
+    ("s", 1.0),
+    ("ms", 0.001),
+)
+
+_TERM: Final = re.compile(r"(\d+(?:\.\d+)?)(ms|[wdhms])")
+
+#: A whole duration: one or more suffixed terms. Public, because it is the grammar an export
+#: must never write outside of.
+DURATION_PATTERN: Final = re.compile(r"^(?:\d+(?:\.\d+)?(?:ms|[wdhms]))+$")
+
+#: The same grammar spelled for JSON Schema, with the bare number of seconds allowed as well.
+DURATION_JSON_PATTERN: Final = r"^(?:(?:\d+(?:\.\d+)?(?:ms|[wdhms]))+|\d+(?:\.\d+)?)$"
+
+ZERO: Final = "0s"
+
+
+class NegativeDuration(ValueError):
+    """A duration was negative, which the grammar has no spelling for."""
+
+    def __init__(self, value: object) -> None:
+        """Name the offending value."""
+        super().__init__(
+            f"{value!r} is negative, and a duration is a delay, a cadence, or a budget: "
+            "the format has no way to write one that runs backwards"
+        )
+
+
+class DurationError(ValueError):
+    """A duration was written in a way the format does not define."""
+
+    def __init__(self, value: object) -> None:
+        """Name the value and the grammar it failed."""
+        super().__init__(
+            f"{value!r} is not a duration: write a number of seconds, or unit-suffixed terms "
+            f"such as '30s', '5m', '6h', '1h30m', '250ms' (units: w, d, h, m, s, ms)"
+        )
+
+
+def parse_duration(value: object) -> object:
+    """Turn a humane duration string into a timedelta, passing anything else through."""
+    match value:
+        case timedelta():
+            return value
+        case bool():
+            raise DurationError(value)
+        case int() | float():
+            return timedelta(seconds=float(value))
+        case str():
+            return _parse_text(value.strip())
+        case _:
+            return value
+
+
+def _parse_text(text: str) -> timedelta:
+    """Parse the string form: a bare number of seconds, or a sequence of suffixed terms."""
+    if not text:
+        raise DurationError(text)
+    try:
+        return timedelta(seconds=float(text))
+    except ValueError:
+        pass
+    if DURATION_PATTERN.fullmatch(text) is None:
+        raise DurationError(text)
+    lengths = dict(UNITS)
+    seconds = sum(float(amount) * lengths[unit] for amount, unit in _TERM.findall(text))
+    return timedelta(seconds=seconds)
+
+
+def to_timedelta(value: object) -> timedelta:
+    """Read a humane duration as a timedelta, refusing anything the grammar does not define."""
+    parsed = parse_duration(value)
+    if not isinstance(parsed, timedelta):
+        raise DurationError(value)
+    return parsed
+
+
+def format_duration(value: timedelta) -> str:
+    """Render a timedelta the one way the canonical document writes it.
+
+    Every duration must have exactly one spelling, or an export stops being byte-stable.
+    """
+    total = value.total_seconds()
+    if total < 0:
+        raise NegativeDuration(value)
+    if total == 0:
+        return ZERO
+    remaining = round(total * 1000) / 1000
+    parts: list[str] = []
+    for unit, length in UNITS:
+        if length > remaining and unit != "ms":
+            continue
+        count = int(remaining / length) if unit != "ms" else round(remaining / length)
+        if count == 0:
+            continue
+        parts.append(f"{count}{unit}")
+        remaining = round((remaining - count * length) * 1000) / 1000
+        if remaining <= 0:
+            break
+    return "".join(parts) or ZERO
+
+
+def refuse_negative(value: timedelta) -> timedelta:
+    """Refuse a negative duration, because the grammar has no way to write one down."""
+    if value < timedelta(0):
+        raise NegativeDuration(value)
+    return value
+
+
+def is_duration(value: object) -> bool:
+    """Whether the value is a duration as a document writes one: humane spelling, not negative."""
+    if not isinstance(value, str):
+        return False
+    try:
+        return to_timedelta(value) >= timedelta(0)
+    except DurationError:
+        return False
+
+
+#: A duration as a document writes it and as the code uses it: a timedelta.
+#:
+#: The published schema is the humane grammar, because a document writes ``5m`` and never
+#: ``PT5M``, and the catalog check is what a document is validated against before it is
+#: ever run. The format is named ``humane-duration`` rather than the standard ``duration``,
+#: which names ISO 8601 and would refuse every value this type accepts.
+type Duration = Annotated[
+    timedelta,
+    BeforeValidator(parse_duration),
+    AfterValidator(refuse_negative),
+    PlainSerializer(format_duration, return_type=str, when_used="json"),
+    WithJsonSchema({"type": "string", "pattern": DURATION_JSON_PATTERN, "format": "humane-duration"}),
+]
+
+#: Bounds pydantic leaves on a field it could not express in JSON Schema, which is every
+#: bound on a duration: JSON Schema has no keyword for one.
+_UNEXPRESSED_BOUNDS: Final = ("gt", "ge", "lt", "le")
+
+
+class HumaneJsonSchema(GenerateJsonSchema):
+    """The schema generator every schema dirigent publishes is built with.
+
+    A default reaches JSON Schema through pydantic's own encoder, which renders a timedelta
+    in ISO 8601 whatever the field's serializer says, so a schema built without this writes
+    ``PT5M`` where the document it describes writes ``5m``.
+    """
+
+    def encode_default(self, dft: Any) -> Any:
+        """Encode a default, writing a duration the one way a document spells it."""
+        if isinstance(dft, timedelta):
+            return format_duration(dft)
+        return super().encode_default(dft)
+
+    def generate(self, schema: CoreSchema, mode: JsonSchemaMode = "validation") -> JsonSchemaValue:
+        """Generate the schema, dropping the bounds JSON Schema has no keyword for."""
+        return cast("JsonSchemaValue", _without_unexpressed_bounds(super().generate(schema, mode=mode)))
+
+
+def _without_unexpressed_bounds(node: object) -> object:
+    """Walk a schema, dropping every bound pydantic could not express as a keyword."""
+    if isinstance(node, dict):
+        entries = cast("dict[str, object]", node)
+        return {
+            key: _without_unexpressed_bounds(value) for key, value in entries.items() if key not in _UNEXPRESSED_BOUNDS
+        }
+    if isinstance(node, list):
+        return [_without_unexpressed_bounds(item) for item in cast("list[object]", node)]
+    return node

dirigent_common-0.9.0/src/dirigent_common/formats.py

@@ -0,0 +1,109 @@
+"""The base JSON Schema format checker every validation in dirigent draws from.
+
+A JSON Schema ``format`` keyword only asserts when a validator is given a checker for it;
+without one it is an annotation the value ignores. This is the one checker the engine and
+the blocks share, so ``format: date-time``, ``uuid`` and the like actually gate -- and it is
+the seam a plugin pack later adds its own formats to, which is why it lives in the shared
+leaf rather than in any one package.
+
+It seeds from the library's standard formats (the non-GPL extra provides their validators)
+and adds dirigent's own. None of the ones added here are standard JSON Schema formats, so a
+tool that does not know them treats them as annotations and passes anything -- the graceful
+degradation every non-core format has; on a dirigent instance they assert. Each guards on a
+string first and parses where parsing is more correct than a pattern. The draft is 2020-12.
+"""
+
+import base64
+import binascii
+import re
+import uuid
+from collections.abc import Callable, Mapping
+
+from jsonschema import FormatChecker
+
+from dirigent_common.durations import is_duration
+
+#: A Crockford base32 ULID: 26 characters, the first at most ``7`` so the timestamp fits 48 bits.
+_ULID = re.compile(r"[0-7][0-9A-HJKMNP-TV-Z]{25}")
+
+#: Hex digests, by their fixed nibble length; a digest is hex of either case.
+_HEX = {"md5": 32, "sha1": 40, "sha256": 64, "sha512": 128}
+
+
+def _is_uuid_version(value: object, version: int) -> bool:
+    """Whether the value parses as a UUID of exactly this version."""
+    if not isinstance(value, str):
+        return False
+    try:
+        return uuid.UUID(value).version == version
+    except ValueError:
+        return False
+
+
+def _is_hex_digest(value: object, length: int) -> bool:
+    """Whether the value is a hex string of exactly this many characters."""
+    return isinstance(value, str) and re.fullmatch(rf"[0-9a-fA-F]{{{length}}}", value) is not None
+
+
+def _is_base64(value: object) -> bool:
+    """Whether the value is standard base64. The empty string is valid: it decodes to no bytes."""
+    if not isinstance(value, str):
+        return False
+    try:
+        base64.b64decode(value, validate=True)
+    except (binascii.Error, ValueError):
+        return False
+    return True
+
+
+def base_format_checker() -> FormatChecker:
+    """Build the format checker dirigent validates values against, standard formats plus its own."""
+    checker = FormatChecker()
+
+    @checker.checks("ulid")
+    def _is_ulid(value: object) -> bool:  # pyright: ignore[reportUnusedFunction] - the decorator registers it
+        """A 26-character Crockford base32 ULID. Canonically uppercase; lowercase decodes too."""
+        return isinstance(value, str) and _ULID.fullmatch(value.upper()) is not None
+
+    @checker.checks("uuid4")
+    def _is_uuid4(value: object) -> bool:  # pyright: ignore[reportUnusedFunction] - the decorator registers it
+        """A UUID that is specifically version 4 (random)."""
+        return _is_uuid_version(value, 4)
+
+    @checker.checks("uuid7")
+    def _is_uuid7(value: object) -> bool:  # pyright: ignore[reportUnusedFunction] - the decorator registers it
+        """A UUID that is specifically version 7 (time-ordered) -- what dirigent's own ids are."""
+        return _is_uuid_version(value, 7)
+
+    for _name, _length in _HEX.items():
+
+        @checker.checks(_name)
+        def _is_digest(value: object, length: int = _length) -> bool:  # pyright: ignore[reportUnusedFunction] - the decorator registers it
+            """A hex digest of the fixed length this algorithm produces, either case."""
+            return _is_hex_digest(value, length)
+
+    @checker.checks("humane-duration")
+    def _humane_duration(value: object) -> bool:  # pyright: ignore[reportUnusedFunction] - the decorator registers it
+        """A duration in dirigent's spelling, such as ``30s`` or ``1h30m``; never ISO 8601."""
+        return is_duration(value)
+
+    @checker.checks("base64")
+    def _base64(value: object) -> bool:  # pyright: ignore[reportUnusedFunction] - the decorator registers it
+        """A standard base64 string; the empty string counts, decoding to no bytes."""
+        return _is_base64(value)
+
+    return checker
+
+
+def format_checker_with(contributed: Mapping[str, Callable[[object], bool]]) -> FormatChecker:
+    """Build the checker an instance validates against: the base formats plus contributed ones.
+
+    A pack contributes a predicate per format name; a value is invalid when the predicate
+    returns False or raises, which is the whole shape of a jsonschema format check. The base
+    checker is copied rather than added to, so each host's assembly is its own and the shared
+    base stays exactly the standard-plus-dirigent set every call builds.
+    """
+    checker = base_format_checker()
+    for name, predicate in contributed.items():
+        checker.checks(name, raises=(Exception,))(predicate)
+    return checker

dirigent_common-0.9.0/src/dirigent_common/formatters.py

@@ -0,0 +1,25 @@
+"""The formatter contract: a name, a version, and one method turning a record into a line.
+
+A formatter is contributed by a package that depends on neither the CLI nor the block
+contract, so the protocol every implementation is checked against lives here.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from dirigent_common.types import JsonMap
+
+
+@runtime_checkable
+class Formatter(Protocol):
+    """One way of turning a record into a line."""
+
+    name: str
+    version: str
+
+    def render(self, record: JsonMap) -> object:
+        """Render one record: a line, or a line with what the kind puts beneath it.
+
+        What the CLI prints is a string, or anything rich's console renders -- a table, a
+        group of both. The type is left open here so that this package names no renderer.
+        """
+        ...

dirigent_common-0.9.0/src/dirigent_common/names.py

@@ -0,0 +1,65 @@
+"""The two name grammars every dirigent identifier obeys, as shared validated types."""
+
+import re
+from typing import Annotated, Final
+
+from pydantic import StringConstraints
+
+#: The grammar reads most naturally as ``^[a-z]([a-z0-9]|-(?=[a-z0-9]))*$``, but this
+#: pattern is published in JSON Schema and compiled by pydantic-core's Rust engine, which
+#: supports no look-ahead. The form below is its exact equivalent: every hyphen must be
+#: followed by an alphanumeric, which forbids a trailing hyphen and a doubled one alike.
+ENTITY_NAME_PATTERN: Final = r"^[a-z](-?[a-z0-9])*$"
+
+ENTITY_NAME_MAX_LENGTH: Final = 63
+
+STEP_NAME_PATTERN: Final = r"^[a-z][a-z0-9_]*$"
+
+STEP_NAME_MAX_LENGTH: Final = 63
+
+#: An address with one ``@`` and a dotted host, which is as far as a pattern can honestly go.
+EMAIL_PATTERN: Final = r"^[^@\s]+@[^@\s]+\.[^@\s]+$"
+
+EMAIL_MAX_LENGTH: Final = 320
+
+type EntityName = Annotated[
+    str, StringConstraints(pattern=ENTITY_NAME_PATTERN, max_length=ENTITY_NAME_MAX_LENGTH, min_length=1)
+]
+
+type StepName = Annotated[
+    str, StringConstraints(pattern=STEP_NAME_PATTERN, max_length=STEP_NAME_MAX_LENGTH, min_length=1)
+]
+
+type Email = Annotated[
+    str, StringConstraints(strip_whitespace=True, pattern=EMAIL_PATTERN, max_length=EMAIL_MAX_LENGTH)
+]
+
+_ENTITY_NAME = re.compile(ENTITY_NAME_PATTERN)
+_STEP_NAME = re.compile(STEP_NAME_PATTERN)
+
+
+def is_entity_name(value: str) -> bool:
+    """Report whether a string is a valid kebab-case entity name."""
+    return len(value) <= ENTITY_NAME_MAX_LENGTH and _ENTITY_NAME.fullmatch(value) is not None
+
+
+def is_step_name(value: str) -> bool:
+    """Report whether a string is a valid snake_case step name."""
+    return len(value) <= STEP_NAME_MAX_LENGTH and _STEP_NAME.fullmatch(value) is not None
+
+
+def entity_name_error(label: str, value: str) -> str:
+    """Render the one message every entity-name rejection uses, so the advice never varies."""
+    return (
+        f"{label} {value!r} is not a valid name: names are lowercase letters, digits, and single "
+        f"hyphens, start with a letter, end alphanumeric, and are at most "
+        f"{ENTITY_NAME_MAX_LENGTH} characters"
+    )
+
+
+def step_name_error(value: str) -> str:
+    """Render the one message every step-name rejection uses, including why it differs."""
+    return (
+        f"step name {value!r} is not valid: step names are snake_case ({STEP_NAME_PATTERN}), because "
+        f"they appear inside ${{steps.<name>.output.…}} where a hyphen or a dot would be ambiguous"
+    )

dirigent_common-0.9.0/src/dirigent_common/programs.py

@@ -0,0 +1,9 @@
+"""The media types a config field carrying a program publishes itself under."""
+
+from typing import Final
+
+#: A jq program, as ``transform.jq``, ``map.jq`` and ``filter.jq`` take one.
+JQ_MEDIA_TYPE: Final = "application/jq"
+
+#: A string handed to a shell to parse, as ``shell.run`` and ``docker.run`` take one.
+SHELL_MEDIA_TYPE: Final = "text/x-shellscript"

dirigent_common-0.9.0/src/dirigent_common/schemas.py

@@ -0,0 +1,65 @@
+"""The pydantic types more than one package has to agree on.
+
+A block's config and output are published as JSON Schema, so their base makes a field's
+docstring its description. The HTTP connection is here rather than in the standard library
+so an adapter pack presents the same one, instead of redefining base URL, auth, TLS and
+timeouts into a fourth slightly different form.
+"""
+
+from datetime import timedelta
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr
+
+from dirigent_common.durations import Duration
+
+
+class BlockModel(BaseModel):
+    """The base every block's config and output model should use.
+
+    Each field's docstring becomes its description in the published JSON Schema, and an
+    unknown key is refused rather than ignored -- which also publishes the schema with
+    ``additionalProperties: false``, so a document is refused at apply and not at the run.
+    """
+
+    model_config = ConfigDict(use_attribute_docstrings=True, extra="forbid")
+
+
+class HealthReport(BaseModel):
+    """The outcome of checking a connection against its external system."""
+
+    healthy: bool
+    detail: str | None = None
+    version: str | None = None
+
+
+class HttpConnectionConfig(BlockModel):
+    """Everything needed to talk to one HTTP service, credentials included."""
+
+    base_url: str = Field(min_length=1)
+    """The service root every request path is resolved against."""
+
+    bearer_token: SecretStr | None = None
+    """A bearer credential, sent as an Authorization header."""
+
+    basic_username: str | None = None
+    """The user half of HTTP basic authentication."""
+
+    basic_password: SecretStr | None = None
+    """The secret half of HTTP basic authentication."""
+
+    hmac_secret: SecretStr | None = None
+    """A shared secret an outbound POST is signed with, mirroring an inbound webhook's.
+
+    It lives on the connection rather than in a document for the same reason every other
+    credential does: a document is portable and a secret is not. It is not sent as a header
+    and never authenticates a request on its own -- ``webhook.post`` uses it to sign the
+    exact bytes it puts on the wire."""
+
+    verify_tls: bool = True
+    """Whether certificates are verified; turning this off is a per-connection decision."""
+
+    timeout: Duration = Field(default=timedelta(seconds=30), gt=timedelta(0))
+    """The timeout applied to every request through this connection."""
+
+    health_path: str = "/"
+    """What a connection check requests to decide whether the service is reachable."""

dirigent_common-0.9.0/src/dirigent_common/sizes.py

@@ -0,0 +1,139 @@
+"""Humane sizes: ``64mb`` in a document, an ``int`` of bytes in the code.
+
+Both unit families are accepted and both are powers of 1024, which is what an operator
+means by "64 megabytes of memory" whatever the SI prefix says. ``64mb`` and ``64mib`` are
+therefore the same number, and the canonical rendering is the short spelling.
+"""
+
+import math
+import re
+from typing import Annotated, Final
+
+from pydantic import AfterValidator, BeforeValidator, PlainSerializer, WithJsonSchema
+
+#: Ordered largest first; the greedy rendering in :func:`format_size` depends on it.
+UNITS: Final[tuple[tuple[str, int], ...]] = (
+    ("tb", 1024**4),
+    ("gb", 1024**3),
+    ("mb", 1024**2),
+    ("kb", 1024),
+    ("b", 1),
+)
+
+#: The long spelling of each unit, accepted on the way in and never written on the way out.
+ALIASES: Final[dict[str, str]] = {"tib": "tb", "gib": "gb", "mib": "mb", "kib": "kb"}
+
+#: A whole size: one number and one unit. Public, because it is the grammar an export must
+#: never write outside of.
+SIZE_PATTERN: Final = re.compile(r"^\d+(?:\.\d+)?(?:t|g|m|k)?i?b$", re.IGNORECASE)
+
+#: The same grammar spelled for JSON Schema, which has no portable case-insensitive flag,
+#: with the bare number of bytes allowed as well.
+SIZE_JSON_PATTERN: Final = r"^\d+(?:\.\d+)?(?:[TtGgMmKk]?[Ii]?[Bb])?$"
+
+#: How a zero size is written.
+ZERO: Final = "0b"
+
+
+class NegativeSize(ValueError):
+    """A size was negative, which the grammar has no spelling for."""
+
+    def __init__(self, value: object) -> None:
+        """Name the value, since the fix is always to drop the sign."""
+        super().__init__(f"{value!r} is negative, and a size is a quantity of bytes: it cannot run backwards")
+
+
+class SizeError(ValueError):
+    """A size was written in a way the format does not define."""
+
+    def __init__(self, value: object) -> None:
+        """Name the value and the grammar, because the fix is always a spelling change."""
+        super().__init__(
+            f"{value!r} is not a size: write a number of bytes, or a unit-suffixed amount such as "
+            f"'512kb', '64mb', '1.5gb' (units: b, kb, mb, gb, tb, and the kib/mib/gib/tib spelling of each, "
+            f"all powers of 1024)"
+        )
+
+
+def parse_size(value: object) -> object:
+    """Turn a humane size string into a count of bytes, passing anything else through.
+
+    Numbers are read as bytes, so ``min_size: 4096`` means the obvious thing.
+    """
+    match value:
+        case bool():
+            raise SizeError(value)
+        case int():
+            return value
+        case float():
+            return _whole(value, value)
+        case str():
+            return _parse_text(value.strip())
+        case _:
+            return value
+
+
+def _parse_text(text: str) -> int:
+    """Parse the string form: a bare number of bytes, or one unit-suffixed amount."""
+    if not text:
+        raise SizeError(text)
+    try:
+        return _whole(float(text), text)
+    except ValueError:
+        pass
+    if SIZE_PATTERN.fullmatch(text) is None:
+        raise SizeError(text)
+    lowered = text.lower()
+    sizes: dict[str, int] = dict(UNITS)
+    suffix = next(unit for unit in (*ALIASES, *sizes) if lowered.endswith(unit))
+    amount = lowered[: -len(suffix)] or "0"
+    return _whole(float(amount) * sizes[ALIASES.get(suffix, suffix)], text)
+
+
+def _whole(value: float, written: object) -> int:
+    """Refuse a size that is not a whole number of bytes, which nothing can store."""
+    if not math.isfinite(value) or value != int(value):
+        raise SizeError(written)
+    return int(value)
+
+
+def format_size(value: int) -> str:
+    """Render a count of bytes the one way the canonical document writes it.
+
+    The largest unit that divides the value exactly, so a rendered size is never a decimal
+    and reading it back yields the same number of bytes.
+    """
+    if value < 0:
+        raise NegativeSize(value)
+    if value == 0:
+        return ZERO
+    unit, multiplier = next((unit, size) for unit, size in UNITS if value % size == 0)
+    return f"{value // multiplier}{unit}"
+
+
+def refuse_negative(value: int) -> int:
+    """Refuse a negative size, because the grammar has no way to write one down."""
+    if value < 0:
+        raise NegativeSize(value)
+    return value
+
+
+#: A size as a document writes it and as the code uses it: a whole number of bytes.
+#:
+#: The published schema names both spellings, because a document may write either and the
+#: catalog check is what a document is validated against before it is ever run.
+type Size = Annotated[
+    int,
+    BeforeValidator(parse_size),
+    AfterValidator(refuse_negative),
+    PlainSerializer(format_size, return_type=str, when_used="json"),
+    WithJsonSchema(
+        {
+            "anyOf": [
+                {"type": "string", "pattern": SIZE_JSON_PATTERN},
+                {"type": "integer", "minimum": 0},
+            ],
+            "format": "size",
+        }
+    ),
+]

dirigent_common-0.9.0/src/dirigent_common/types.py

@@ -0,0 +1,9 @@
+"""The JSON shapes a document, a record and a wire body are all made of."""
+
+from typing import Any
+
+#: A JSON object, as a document's config, a block's output and a response body all are.
+type JsonMap = dict[str, Any]
+
+#: A JSON array.
+type JsonList = list[Any]

dirigent_common-0.9.0/src/dirigent_common/uris.py

@@ -0,0 +1,16 @@
+"""A storage URI as a block declares it, so an instance can check the scheme before a run."""
+
+from typing import Annotated, Final
+
+from pydantic import Field
+
+#: The JSON Schema ``format`` a storage URI is published under. A document's value for a field
+#: carrying it is checked against the schemes this instance's backends claim, at apply, rather
+#: than failing the first time a step runs.
+STORAGE_URI_FORMAT: Final = "storage-uri"
+
+#: A URI addressing stored bytes: ``file://`` or ``s3://``, whatever a backend registered.
+#:
+#: The marker is what tells a validator this string is storage and not, say, the URL an HTTP
+#: request is sent to. Nothing distinguishes the two by looking.
+StorageUri = Annotated[str, Field(json_schema_extra={"format": STORAGE_URI_FORMAT})]

dirigent_common-0.9.0/src/dirigent_common/values.py

@@ -0,0 +1,40 @@
+"""How a value that is not already JSON is spelled as JSON.
+
+One conversion, so a parquet column, a database column and anything else that arrives as a
+Python object reach a document as the same string. A caller that has already refused a shape
+its own format cannot carry -- a nested arrow column, say -- refuses it before asking here.
+"""
+
+import base64
+import datetime
+import decimal
+import math
+import uuid
+
+from pydantic import JsonValue
+
+
+def spelled(value: object) -> JsonValue:
+    """Give one Python value its JSON spelling, refusing what has none.
+
+    A date, time or timestamp becomes ISO 8601. A decimal becomes its exact digits as a
+    string, because a float would round it. A UUID becomes its canonical text. Bytes become
+    standard base64. A float that is not finite becomes null, JSON having no ``NaN``.
+    """
+    if isinstance(value, datetime.datetime | datetime.date | datetime.time):
+        return value.isoformat()
+    if isinstance(value, datetime.timedelta):
+        return value.total_seconds()
+    if isinstance(value, decimal.Decimal):
+        return str(value)
+    if isinstance(value, uuid.UUID):
+        return str(value)
+    if isinstance(value, bytes | bytearray):
+        return base64.b64encode(value).decode()
+    if isinstance(value, memoryview):
+        return base64.b64encode(value.tobytes()).decode()
+    if isinstance(value, float) and not math.isfinite(value):
+        return None
+    if value is None or isinstance(value, bool | int | float | str):
+        return value
+    raise ValueError(f"a value of type {type(value).__name__} has no JSON spelling")

dirigent_common-0.9.0/src/dirigent_common/versions.py

@@ -0,0 +1,6 @@
+"""The contract version the plugin surface and the wire catalog both name."""
+
+from typing import Final
+
+#: Bumped when the contract changes incompatibly; the entry point group carries it too.
+API_VERSION: Final = 1