dirigent-plugin 0.26.1__tar.gz → 0.27.0__tar.gz

{dirigent_plugin-0.26.1 → dirigent_plugin-0.27.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: dirigent-plugin
-Version: 0.26.1
+Version: 0.27.0
 Summary: The dirigent plugin contract: block specs, protocols, and markers.
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: dirigent-common==0.26.1
+Requires-Dist: dirigent-common==0.27.0
 Requires-Dist: httpx2>=2.12.0
 Requires-Dist: pluginkit>=0.5.0
 Requires-Dist: pydantic>=2.13.5

{dirigent_plugin-0.26.1 → dirigent_plugin-0.27.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-plugin"
-version = "0.26.1"
+version = "0.27.0"
 description = "The dirigent plugin contract: block specs, protocols, and markers."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -11,7 +11,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "dirigent-common==0.26.1",
+    "dirigent-common==0.27.0",
     "httpx2>=2.12.0",
     "pluginkit>=0.5.0",
     "pydantic>=2.13.5",

{dirigent_plugin-0.26.1 → dirigent_plugin-0.27.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-plugin"
-version = "0.26.1"
+version = "0.27.0"
 description = "The dirigent plugin contract: block specs, protocols, and markers."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -11,7 +11,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "dirigent-common==0.26.1",
+    "dirigent-common==0.27.0",
     "httpx2>=2.12.0",
     "pluginkit>=0.5.0",
     "pydantic>=2.13.5",

{dirigent_plugin-0.26.1 → dirigent_plugin-0.27.0}/src/dirigent_plugin/__init__.py

@@ -16,7 +16,6 @@ from dirigent_plugin.blocks import (
     ConnectionKind,
     ConnectionRef,
     ContainerResult,
-    Contribution,
     ErrorClass,
     FormatCheck,
     Logger,
@@ -45,10 +44,10 @@ from dirigent_plugin.blocks import (
     StorageBackend,
     classify_default,
     mark_refusal,
-    merge_contributions,
     reference_fields,
     shell_string_fields,
 )
+from dirigent_plugin.contribution import Contribution, merge_contributions
 from dirigent_plugin.markers import (
     ENTRY_POINT_GROUP,
     PROJECT_NAME,

{dirigent_plugin-0.26.1 → dirigent_plugin-0.27.0}/src/dirigent_plugin/blocks.py

@@ -12,24 +12,20 @@ from uuid import UUID
 
 import httpx2
 from jsonschema import FormatChecker
-from pydantic import BaseModel, ConfigDict, Field, GetJsonSchemaHandler, JsonValue, field_validator, model_validator
+from pydantic import BaseModel, ConfigDict, Field, GetJsonSchemaHandler, JsonValue, model_validator
 from pydantic.json_schema import JsonSchemaValue, SkipJsonSchema
 from pydantic_core import CoreSchema
 
 from dirigent_common import (
-    API_VERSION,
     SHELL_MEDIA_TYPE,
     BlockModel,
-    Catalogue,
     HealthReport,
     Issue,
     JsonMap,
     Message,
 )
 from dirigent_plugin.messages import (
-    DUPLICATE_ID,
     INVALID_MARK,
-    UNSUPPORTED_API_VERSION,
 )
 
 type RunId = UUID
@@ -347,8 +343,8 @@ class NotYet(BaseModel):
     from again. So a poke must tolerate reading the same ground twice.
 
     The cursor's life is the waiting attempt. A poke that succeeds ends the step, and only
-    :meth:`Sensor.resume_cursor` carries a cursor past it: a watch hands what that returns to
-    the first poke of the run it arms next.
+    :meth:`Sensor.resume_cursor` carries a cursor past it: a ``sensor`` source hands what that
+    returns to the poke that starts its next wait.
     """
 
 
@@ -400,6 +396,14 @@ class SensorSpec(BaseModel):
     default_poll: timedelta = timedelta(minutes=1)
     default_deadline: timedelta = timedelta(hours=24)
 
+    source: bool = False
+    """Whether a ``sensor`` source may poke it outside any run, a run started by each success.
+
+    Such a sensor reads nothing of a run but ``ctx.cursor`` and ``ctx.started_at``, which is
+    when the source began waiting, and says through :meth:`Sensor.resume_cursor` where the
+    next wait carries on, so the same ground does not succeed twice.
+    """
+
     @model_validator(mode="before")
     @classmethod
     def _shelve(cls, data: Any) -> Any:
@@ -636,9 +640,9 @@ class StepContext(Protocol):
     cursor: JsonMap | None
     """The cursor the last committed :class:`NotYet` returned, and None on the first poke.
 
-    The first poke of a run a watch armed is handed where the watch's last success left off
-    instead, which is what :meth:`Sensor.resume_cursor` returned. Only a sensor's poke reads
-    it; every other call sees None.
+    A poke by a ``sensor`` source is handed where the source's last success left off instead,
+    which is what :meth:`Sensor.resume_cursor` returned. Only a sensor's poke reads it; every
+    other call sees None.
     """
 
     def connection[C: BaseModel](self, ref: ConnectionRef, model: type[C]) -> C:
@@ -777,10 +781,10 @@ class Sensor[ConfigT: BaseModel, OutputT: BaseModel](ABC):
     def resume_cursor(self, output: OutputT) -> JsonMap | None:
         """Say where a poke that succeeded left off, read from the output it succeeded with.
 
-        A watch stores what this returns and hands it to the first poke of the next run it
-        arms as ``ctx.cursor``. None, the default, starts every run fresh. It is stored in the
-        transaction that settles the step, so it is only as far along as the last success that
-        committed, and the next poke may read that ground again.
+        A ``sensor`` source stores what this returns and hands it to the poke that starts its
+        next wait as ``ctx.cursor``. None, the default, starts every wait fresh. It is stored in
+        the transaction that starts the run the success became, so it is only as far along as
+        the last success that committed, and the next poke may read that ground again.
         """
         return None
 
@@ -875,7 +879,7 @@ _PATH_DATA: Final = re.compile(r"^[MmZzLlHhVvCcSsQqTtAaEe0-9,.+\-\s]+$")
 
 
 def mark_refusal(kind: str, mark: str | None) -> str | None:
-    """Say why a connection kind may not wear the mark it declares, or ``None`` when it may.
+    """Say why a connection or source kind may not wear the mark it declares, or ``None`` when it may.
 
     A mark reaches a browser as the ``d`` of one path, so anything that is not path data is
     refused here rather than drawn: non-empty, ASCII, path-data characters only, and at most
@@ -923,89 +927,3 @@ class ConnectionKind(ABC):
 
 type AnyOperator = Operator[Any, Any]
 type AnySensor = Sensor[Any, Any]
-
-
-class Contribution(BaseModel):
-    """Everything one plugin adds, across all seven surfaces, gathered by the host at startup."""
-
-    model_config = ConfigDict(arbitrary_types_allowed=True, frozen=True)
-
-    api_version: int = Field(default=API_VERSION, ge=1)
-    operators: list[AnyOperator] = Field(default_factory=list[AnyOperator])
-    sensors: list[AnySensor] = Field(default_factory=list[AnySensor])
-    storage_backends: list[StorageBackend] = Field(default_factory=list[StorageBackend])
-    notifiers: list[Notifier] = Field(default_factory=list[Notifier])
-    connection_kinds: list[ConnectionKind] = Field(default_factory=list[ConnectionKind])
-    formats: dict[str, FormatCheck] = Field(default_factory=dict[str, FormatCheck])
-    """JSON Schema format checkers this plugin adds, by format name. A schema that writes
-    ``format: <name>`` then asserts wherever the contributing pack is installed, and stays a
-    passing annotation on an instance without it."""
-
-    labels: list[Catalogue] = Field(default_factory=list[Catalogue])
-    """The message catalogues this plugin refuses out of, so a surface can render its codes.
-
-    A pack's refusal reaches a browser under the pack's own code, and the browser holds no table
-    for it. Contributing the catalogue is what puts one there: the host serves every code and its
-    template, and a renderer that knows the code says its own sentence rather than repeating the
-    English this process happened to mint."""
-
-    @field_validator("api_version")
-    @classmethod
-    def _check_api_version(cls, value: int) -> int:
-        """Reject a contribution written against a different revision of this contract."""
-        if value != API_VERSION:
-            raise ValueError(UNSUPPORTED_API_VERSION.render(version=value, host_version=API_VERSION))
-        return value
-
-    @model_validator(mode="after")
-    def _check_ids(self) -> "Contribution":
-        """Reject a contribution whose blocks or surfaces collide on an id."""
-        _require_unique("block id", [*(op.spec.id for op in self.operators), *(se.spec.id for se in self.sensors)])
-        _require_unique("storage scheme", [backend.scheme for backend in self.storage_backends])
-        _require_unique("notifier id", [notifier.id for notifier in self.notifiers])
-        _require_unique("connection kind id", [connection.id for connection in self.connection_kinds])
-        _require_unique("format", list(self.formats))
-        _require_unique("label prefix", [catalogue.prefix for catalogue in self.labels])
-        return self
-
-    @model_validator(mode="after")
-    def _check_marks(self) -> "Contribution":
-        """Reject a connection kind whose declared mark is not path data a browser may draw."""
-        for connection in self.connection_kinds:
-            refusal = mark_refusal(connection.id, connection.mark)
-            if refusal is not None:
-                raise ValueError(refusal)
-        return self
-
-    def block_ids(self) -> list[str]:
-        """List every operator and sensor id this contribution registers."""
-        return [*(operator.spec.id for operator in self.operators), *(sensor.spec.id for sensor in self.sensors)]
-
-
-def _require_unique(label: str, values: list[str]) -> None:
-    """Raise when a list of contributed ids contains a duplicate."""
-    seen: set[str] = set()
-    for value in values:
-        if value in seen:
-            raise ValueError(DUPLICATE_ID.render(label=label, value=repr(value)))
-        seen.add(value)
-
-
-def merge_contributions(contributions: list[Contribution]) -> Contribution:
-    """Merge every plugin's contribution into the single catalog the host dispatches from."""
-    merged: dict[str, list[Any]] = {
-        "operators": [],
-        "sensors": [],
-        "storage_backends": [],
-        "notifiers": [],
-        "connection_kinds": [],
-        "labels": [],
-    }
-    for contribution in contributions:
-        for surface, collected in merged.items():
-            collected.extend(getattr(contribution, surface))
-    formats: dict[str, FormatCheck] = {}
-    _require_unique("format", [name for contribution in contributions for name in contribution.formats])
-    for contribution in contributions:
-        formats.update(contribution.formats)
-    return Contribution(api_version=API_VERSION, formats=formats, **merged)

dirigent_plugin-0.27.0/src/dirigent_plugin/contribution.py

@@ -0,0 +1,129 @@
+"""What one plugin contributes, across every surface, and how the host merges them."""
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from dirigent_common import API_VERSION, Catalogue
+from dirigent_plugin.blocks import (
+    AnyOperator,
+    AnySensor,
+    ConnectionKind,
+    FormatCheck,
+    Notifier,
+    StorageBackend,
+    mark_refusal,
+)
+from dirigent_plugin.messages import DUPLICATE_ID, SOURCE_NOT_HOSTED, UNSUPPORTED_API_VERSION
+from dirigent_plugin.sources import AnySource, HeldSource, PolledSource, ReceivedSource, SourceHosting
+
+
+class Contribution(BaseModel):
+    """Everything one plugin adds, across all eight surfaces, gathered by the host at startup."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True, frozen=True)
+
+    api_version: int = Field(default=API_VERSION, ge=1)
+    operators: list[AnyOperator] = Field(default_factory=list[AnyOperator])
+    sensors: list[AnySensor] = Field(default_factory=list[AnySensor])
+    storage_backends: list[StorageBackend] = Field(default_factory=list[StorageBackend])
+    notifiers: list[Notifier] = Field(default_factory=list[Notifier])
+    connection_kinds: list[ConnectionKind] = Field(default_factory=list[ConnectionKind])
+    sources: list[AnySource] = Field(default_factory=list[AnySource])
+    """The source kinds this plugin adds, each keyed by the ``kind`` a document writes under ``source``."""
+
+    formats: dict[str, FormatCheck] = Field(default_factory=dict[str, FormatCheck])
+    """JSON Schema format checkers this plugin adds, by format name. A schema that writes
+    ``format: <name>`` then asserts wherever the contributing pack is installed, and stays a
+    passing annotation on an instance without it."""
+
+    labels: list[Catalogue] = Field(default_factory=list[Catalogue])
+    """The message catalogues this plugin refuses out of, so a surface can render its codes.
+
+    A pack's refusal reaches a browser under the pack's own code, and the browser holds no table
+    for it. Contributing the catalogue is what puts one there: the host serves every code and its
+    template, and a renderer that knows the code says its own sentence rather than repeating the
+    English this process happened to mint."""
+
+    @field_validator("api_version")
+    @classmethod
+    def _check_api_version(cls, value: int) -> int:
+        """Reject a contribution written against a different revision of this contract."""
+        if value != API_VERSION:
+            raise ValueError(UNSUPPORTED_API_VERSION.render(version=value, host_version=API_VERSION))
+        return value
+
+    @model_validator(mode="after")
+    def _check_ids(self) -> "Contribution":
+        """Reject a contribution whose blocks or surfaces collide on an id."""
+        _require_unique("block id", [*(op.spec.id for op in self.operators), *(se.spec.id for se in self.sensors)])
+        _require_unique("storage scheme", [backend.scheme for backend in self.storage_backends])
+        _require_unique("notifier id", [notifier.id for notifier in self.notifiers])
+        _require_unique("connection kind id", [connection.id for connection in self.connection_kinds])
+        _require_unique("source kind", [source.spec.kind for source in self.sources])
+        _require_unique("format", list(self.formats))
+        _require_unique("label prefix", [catalogue.prefix for catalogue in self.labels])
+        return self
+
+    @model_validator(mode="after")
+    def _check_marks(self) -> "Contribution":
+        """Reject a connection or source kind whose declared mark is not path data a browser may draw."""
+        marks = [
+            *((connection.id, connection.mark) for connection in self.connection_kinds),
+            *((source.spec.kind, source.mark) for source in self.sources),
+        ]
+        for kind, mark in marks:
+            refusal = mark_refusal(kind, mark)
+            if refusal is not None:
+                raise ValueError(refusal)
+        return self
+
+    @model_validator(mode="after")
+    def _check_sources(self) -> "Contribution":
+        """Reject a source kind whose class is not the one its hosting names, or that nothing hosts."""
+        hosted = {
+            SourceHosting.RECEIVED: ReceivedSource,
+            SourceHosting.POLLED: PolledSource,
+            SourceHosting.HELD: HeldSource,
+        }
+        for source in self.sources:
+            contract = hosted.get(source.spec.hosting)
+            if contract is None or not isinstance(source, contract):
+                raise ValueError(
+                    SOURCE_NOT_HOSTED.render(kind=repr(source.spec.kind), hosting=source.spec.hosting.value)
+                )
+        return self
+
+    def block_ids(self) -> list[str]:
+        """List every operator and sensor id this contribution registers."""
+        return [*(operator.spec.id for operator in self.operators), *(sensor.spec.id for sensor in self.sensors)]
+
+
+def _require_unique(label: str, values: list[str]) -> None:
+    """Raise when a list of contributed ids contains a duplicate."""
+    seen: set[str] = set()
+    for value in values:
+        if value in seen:
+            raise ValueError(DUPLICATE_ID.render(label=label, value=repr(value)))
+        seen.add(value)
+
+
+def merge_contributions(contributions: list[Contribution]) -> Contribution:
+    """Merge every plugin's contribution into the single catalog the host dispatches from."""
+    merged: dict[str, list[Any]] = {
+        "operators": [],
+        "sensors": [],
+        "storage_backends": [],
+        "notifiers": [],
+        "connection_kinds": [],
+        "sources": [],
+        "labels": [],
+    }
+    for contribution in contributions:
+        for surface, collected in merged.items():
+            collected.extend(getattr(contribution, surface))
+    formats: dict[str, FormatCheck] = {}
+    _require_unique("format", [name for contribution in contributions for name in contribution.formats])
+    for contribution in contributions:
+        formats.update(contribution.formats)
+    return Contribution(api_version=API_VERSION, formats=formats, **merged)

{dirigent_plugin-0.26.1 → dirigent_plugin-0.27.0}/src/dirigent_plugin/markers.py

@@ -9,7 +9,7 @@ from pluginkit import Extension, ExtensionPoint
 from dirigent_common import Formatter
 
 if TYPE_CHECKING:
-    from dirigent_plugin.blocks import Contribution
+    from dirigent_plugin.contribution import Contribution
 
 PROJECT_NAME = "dirigent"
 
@@ -22,7 +22,7 @@ extension = Extension(PROJECT_NAME)
 
 @extension_point
 def contribute() -> "Contribution":
-    """Collect everything a plugin adds across the five surfaces, once at host startup."""
+    """Collect everything a plugin adds across every surface, once at host startup."""
     raise NotImplementedError("an extension point is a declaration; call it via PluginManager.caller(...)")
 
 

{dirigent_plugin-0.26.1 → dirigent_plugin-0.27.0}/src/dirigent_plugin/messages.py

@@ -39,7 +39,13 @@ DUPLICATE_ID = PLUGIN.define("duplicate_id", "duplicate {label} {value} in contr
 
 INVALID_MARK = PLUGIN.define(
     "invalid_mark",
-    "the mark connection kind {kind} declares is not SVG path data: {detail}",
+    "the mark that kind {kind} declares is not SVG path data: {detail}",
+)
+
+SOURCE_NOT_HOSTED = PLUGIN.define(
+    "source_not_hosted",
+    "source kind {kind} is {hosting}, and a contributed kind is the ReceivedSource, PolledSource "
+    "or HeldSource its hosting names",
 )
 
 # What a received source's path template refuses.

{dirigent_plugin-0.26.1 → dirigent_plugin-0.27.0}/src/dirigent_plugin/sources.py

@@ -7,6 +7,7 @@ receives it, a worker polls it, or a worker holds it open.
 
 import re
 from abc import ABC, abstractmethod
+from contextlib import AbstractAsyncContextManager
 from datetime import datetime, timedelta
 from enum import StrEnum
 from typing import Any, ClassVar, Final, Literal, Protocol
@@ -15,7 +16,7 @@ from jsonschema import FormatChecker
 from pydantic import BaseModel, ConfigDict, Field
 
 from dirigent_common import Issue, JsonMap, Message
-from dirigent_plugin.blocks import ErrorClass, Logger, classify_default
+from dirigent_plugin.blocks import ConnectionRef, ErrorClass, Logger, Storage, classify_default
 from dirigent_plugin.messages import (
     ROUTE_BAD_PARAMETER,
     ROUTE_BAD_SEGMENT,
@@ -70,8 +71,13 @@ class SourceAuth(BaseModel):
 
     model_config = ConfigDict(frozen=True, extra="forbid", use_attribute_docstrings=True)
 
-    kind: Literal["token", "public"] = "token"
-    """``token`` takes ``Authorization: Bearer`` with the token the instance minted; ``public`` admits anyone."""
+    kind: Literal["token", "hmac", "public"] = "token"
+    """``token`` takes ``Authorization: Bearer`` with the token the instance minted; ``hmac`` takes a
+    signature of the body, made with the source's signing secret; ``public`` admits anyone."""
+
+    header: str = Field(default="X-Dirigent-Signature", min_length=1)
+    """For ``hmac``, the header the signature arrives in: the hex HMAC-SHA256 of the raw body,
+    with or without a leading ``sha256=``."""
 
 
 class SourceRate(BaseModel):
@@ -247,6 +253,63 @@ class ReceiveContext(Protocol):
         ...
 
 
+class PollContext(Protocol):
+    """What a polled kind may reach while it asks for new inputs: storage bound as the instance configures it."""
+
+    @property
+    def log(self) -> Logger:
+        """Where the kind says what it found."""
+        ...
+
+    @property
+    def storage(self) -> Storage:
+        """Storage, every scheme configured from the connection the instance names for it."""
+        ...
+
+
+class HoldContext(Protocol):
+    """What a held kind may reach while it listens: storage, and the connections the instance holds."""
+
+    @property
+    def log(self) -> Logger:
+        """Where the kind says what it is doing."""
+        ...
+
+    @property
+    def storage(self) -> Storage:
+        """Storage, every scheme configured from the connection the instance names for it."""
+        ...
+
+    def connection[C: BaseModel](self, ref: ConnectionRef, model: type[C]) -> C:
+        """Resolve a connection by code, opened and validated against the kind's own model."""
+        ...
+
+
+class Listener[OutputT: BaseModel](Protocol):
+    """One open consumer a held kind answers ``listen`` with."""
+
+    async def receive(self, limit: int, wait: timedelta) -> list[OutputT]:
+        """Take at most ``limit`` inputs, waiting no longer than ``wait`` for the first."""
+        ...
+
+    async def ack(self) -> None:
+        """Acknowledge every input received so far, once each has become a run."""
+        ...
+
+
+class Polled[OutputT: BaseModel](BaseModel):
+    """What one poll found: the inputs, oldest first, and where the next poll carries on from."""
+
+    model_config = ConfigDict(frozen=True)
+
+    inputs: list[OutputT] = Field(default_factory=list[OutputT])
+    cursor: JsonMap | None = None
+    """Stored once every input became a run, and handed to the next poll."""
+
+    next_poll_in: timedelta | None = None
+    """How long until the next poll, or None for the source's own cadence."""
+
+
 class Source[ConfigT: BaseModel, OutputT: BaseModel](ABC):
     """One source kind: its config, its output, and what it refuses at apply."""
 
@@ -322,4 +385,49 @@ class ReceivedSource[ConfigT: BaseModel, OutputT: BaseModel](Source[ConfigT, Out
         ...
 
 
+class PolledSource[ConfigT: BaseModel, OutputT: BaseModel](Source[ConfigT, OutputT]):
+    """A kind a worker asks on a cadence, carrying a cursor from one poll to the next."""
+
+    def poll_every(self, config: ConfigT) -> timedelta:
+        """Say how long a worker waits between two polls of this source."""
+        return self.spec.default_poll or DEFAULT_POLL
+
+    def label_of(self, output: OutputT) -> str | None:
+        """Name one input in a line of the source's journal, such as the object it found."""
+        return None
+
+    @abstractmethod
+    async def poll(self, config: ConfigT, cursor: JsonMap | None, ctx: PollContext, limit: int) -> Polled[OutputT]:
+        """Find what is new since the cursor, at most ``limit`` inputs, oldest first.
+
+        A failure it raises is the source's: it is recorded on the row and the next poll backs
+        off, from the same cursor.
+        """
+        ...
+
+
+class HeldSource[ConfigT: BaseModel, OutputT: BaseModel](Source[ConfigT, OutputT]):
+    """A kind a worker holds open under a lease: a consumer whose messages are the inputs.
+
+    The worker makes a run of each input it receives, commits them, and only then acknowledges
+    them, so an input is never lost and may, after a crash between the two, arrive twice.
+    """
+
+    def label_of(self, output: OutputT) -> str | None:
+        """Name one input in a line of the source's journal, such as where it was read from."""
+        return None
+
+    @abstractmethod
+    def listen(self, config: ConfigT, ctx: HoldContext) -> AbstractAsyncContextManager[Listener[OutputT]]:
+        """Open a consumer for as long as the worker holds the source; leaving it closes the consumer.
+
+        A failure it raises, opening or receiving, is the source's: it is recorded on the row,
+        the lease is let go, and the source is taken up again after a backoff.
+        """
+        ...
+
+
+#: How long a worker waits between two polls of a kind whose spec names no cadence.
+DEFAULT_POLL: Final = timedelta(minutes=1)
+
 type AnySource = Source[Any, Any]