spatialdds 0.3.1__tar.gz → 0.5.0__tar.gz

{spatialdds-0.3.1 → spatialdds-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatialdds
-Version: 0.3.1
+Version: 0.5.0
 Summary: SpatialDDS over plain HTTPS and a WebSocket: a client for the web binding (Appendix N), and the reference registry behind one command.
 Author: Open AR Cloud
 License: Apache-2.0
@@ -356,13 +356,71 @@ Latched reads revalidate with the ETag the endpoint gave; `fetch_asset` checks
 the bytes. Opting out exists and is loud: `verify_integrity=False`, at the call
 site, nowhere else.
 
-## Not in 0.3.1
+## New in 0.4.0: a command surface on the server half
+
+`spatialdds[server]` now implements Appendix N.6. A command is a POST to the
+lane that accepts one, and an embedder registers what a verb means:
+
+| Part | What it is |
+| --- | --- |
+| the seam | `spatialdds.server.commands.Registry().register(fqn, handler)` |
+| a handler gets | the validated, lifted record — the same JSON a GET would serve |
+| a handler returns | `Outcome.accept()` or `Outcome.decline("why")` |
+| the wire | `202` accepted, `409` declined with the reason, `405` where no handler is registered |
+
+`python -m spatialdds.serve --demo` registers one so the surface is reachable
+without writing a backend. An endpoint with no handlers is northbound-only and
+every command POST is a clean `405`, which is what N.6 requires and what every
+earlier version did.
+
+**The client half has no command method.** This release adds the surface, not
+a helper for calling it — `requests.post(topic_url, json=record)` with the
+operator token is the whole of it, and `docs/WIRE.md` documents the response
+shapes. Said plainly because "commands are supported" invites a reader to look
+for `hit.command(...)`, and there isn't one.
+
+## New in 0.5.0: embedding the gateway against your own live source
+
+0.4.0 let a backend own the verbs. 0.5.0 lets it own the data, which took two
+changes found by doing it:
+
+| Call | What it does |
+| --- | --- |
+| `publish.apply_sample(st, topic, res, key, data)` | what a **new** subscriber replays, and what the collection GET returns |
+| `gw_http.notify(app, topic, event)` | wakes the subscribers **already** connected |
+
+They are halves of one contract. Until 0.5.0 only the first was public, so an
+embedder could update the latched set and reach every client except the ones
+currently watching — measured as three seconds of silence on an open socket,
+with the same event arriving instantly once it was handed to the queue by
+hand.
+
+And `make_app` has a second switch, because it used to have one doing two
+jobs:
+
+| Argument | What it controls |
+| --- | --- |
+| `publish_enabled` | the PUT/DELETE write surface, and nothing else |
+| `live_subscriptions` | whether an N.5 subscription stays open past the end of a recorded stream |
+
+`live_subscriptions` defaults to following `publish_enabled`, so nothing that
+already worked changed. An embedder with its own source passes
+`publish_enabled=False, live_subscriptions=True` and gets the live lane with
+no write surface at all — which was unreachable before, when keeping
+subscribers connected meant exposing writes.
+
+## Not in 0.5.0
 
 Stated so nobody waits for them: no async API, no caching beyond ETag
 revalidation, no retry policy, no MCAP tooling beyond the journal the server
-writes, and no DDS dependency of any kind. The wire is HTTP and a WebSocket.
+writes, no client-side command helper, and no DDS dependency of any kind. The
+wire is HTTP and a WebSocket.
+
+0.4.0 added the N.6 command surface described above; 0.5.0 made it usable
+from an embedder with a live source, which is two releases for one capability
+and the honest shape of finding the second half by using the first.
 
-0.3.1 is this page: two code blocks on it had no gate behind them and both
+0.3.1 was this page: two code blocks on it had no gate behind them and both
 were broken, and a long description is baked into the artifact, so the page on
 PyPI only heals with a release. Every block here is executed by a gate now,
 and the gate also refuses a relative link, an empty table header and a serve

{spatialdds-0.3.1 → spatialdds-0.5.0}/README.md

@@ -332,13 +332,71 @@ Latched reads revalidate with the ETag the endpoint gave; `fetch_asset` checks
 the bytes. Opting out exists and is loud: `verify_integrity=False`, at the call
 site, nowhere else.
 
-## Not in 0.3.1
+## New in 0.4.0: a command surface on the server half
+
+`spatialdds[server]` now implements Appendix N.6. A command is a POST to the
+lane that accepts one, and an embedder registers what a verb means:
+
+| Part | What it is |
+| --- | --- |
+| the seam | `spatialdds.server.commands.Registry().register(fqn, handler)` |
+| a handler gets | the validated, lifted record — the same JSON a GET would serve |
+| a handler returns | `Outcome.accept()` or `Outcome.decline("why")` |
+| the wire | `202` accepted, `409` declined with the reason, `405` where no handler is registered |
+
+`python -m spatialdds.serve --demo` registers one so the surface is reachable
+without writing a backend. An endpoint with no handlers is northbound-only and
+every command POST is a clean `405`, which is what N.6 requires and what every
+earlier version did.
+
+**The client half has no command method.** This release adds the surface, not
+a helper for calling it — `requests.post(topic_url, json=record)` with the
+operator token is the whole of it, and `docs/WIRE.md` documents the response
+shapes. Said plainly because "commands are supported" invites a reader to look
+for `hit.command(...)`, and there isn't one.
+
+## New in 0.5.0: embedding the gateway against your own live source
+
+0.4.0 let a backend own the verbs. 0.5.0 lets it own the data, which took two
+changes found by doing it:
+
+| Call | What it does |
+| --- | --- |
+| `publish.apply_sample(st, topic, res, key, data)` | what a **new** subscriber replays, and what the collection GET returns |
+| `gw_http.notify(app, topic, event)` | wakes the subscribers **already** connected |
+
+They are halves of one contract. Until 0.5.0 only the first was public, so an
+embedder could update the latched set and reach every client except the ones
+currently watching — measured as three seconds of silence on an open socket,
+with the same event arriving instantly once it was handed to the queue by
+hand.
+
+And `make_app` has a second switch, because it used to have one doing two
+jobs:
+
+| Argument | What it controls |
+| --- | --- |
+| `publish_enabled` | the PUT/DELETE write surface, and nothing else |
+| `live_subscriptions` | whether an N.5 subscription stays open past the end of a recorded stream |
+
+`live_subscriptions` defaults to following `publish_enabled`, so nothing that
+already worked changed. An embedder with its own source passes
+`publish_enabled=False, live_subscriptions=True` and gets the live lane with
+no write surface at all — which was unreachable before, when keeping
+subscribers connected meant exposing writes.
+
+## Not in 0.5.0
 
 Stated so nobody waits for them: no async API, no caching beyond ETag
 revalidation, no retry policy, no MCAP tooling beyond the journal the server
-writes, and no DDS dependency of any kind. The wire is HTTP and a WebSocket.
+writes, no client-side command helper, and no DDS dependency of any kind. The
+wire is HTTP and a WebSocket.
+
+0.4.0 added the N.6 command surface described above; 0.5.0 made it usable
+from an embedder with a live source, which is two releases for one capability
+and the honest shape of finding the second half by using the first.
 
-0.3.1 is this page: two code blocks on it had no gate behind them and both
+0.3.1 was this page: two code blocks on it had no gate behind them and both
 were broken, and a long description is baked into the artifact, so the page on
 PyPI only heals with a release. Every block here is executed by a gate now,
 and the gate also refuses a relative link, an empty table header and a serve

{spatialdds-0.3.1 → spatialdds-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spatialdds"
-version = "0.3.1"
+version = "0.5.0"
 description = "SpatialDDS over plain HTTPS and a WebSocket: a client for the web binding (Appendix N), and the reference registry behind one command."
 readme = "README.md"
 requires-python = ">=3.9"

{spatialdds-0.3.1 → spatialdds-0.5.0}/spatialdds/__init__.py

@@ -37,7 +37,7 @@ __all__ = [
     "content_manifest", "geo_anchor", "service_uri", "content_uri",
 ]
 
-__version__ = "0.3.1"
+__version__ = "0.5.0"
 #: The SpatialDDS-spec commit whose Appendix N and generated artifacts this
 #: package implements. Package versions and specification versions move
 #: independently; this is the one that says what the wire looks like.

{spatialdds-0.3.1 → spatialdds-0.5.0}/spatialdds/serve.py

@@ -42,10 +42,10 @@ def _server():
     """The server half, or one sentence saying how to get it."""
     try:
         from aiohttp import web
-        from .server import gateway, gw_http, pin, publish
+        from .server import commands, gateway, gw_http, pin, publish
     except ImportError as e:                                  # pragma: no cover
         raise SystemExit(f"spatialdds.serve: {MISSING_SERVER}\n\n({e})")
-    return web, gateway, gw_http, pin, publish
+    return web, commands, gateway, gw_http, pin, publish
 
 
 def build_parser(ap: argparse.ArgumentParser) -> argparse.ArgumentParser:
@@ -102,8 +102,33 @@ def build_parser(ap: argparse.ArgumentParser) -> argparse.ArgumentParser:
     return ap
 
 
+def _demo_command(record: dict):
+    """The `--demo` command handler: both of M.1's outcomes, no side effects.
+
+    A reference handler that pretended to act would be worse than none: it
+    would make the surface look wired to something. So this decides, says
+    why, and changes nothing --- which is all a demo registry can honestly do,
+    having no backend behind it.
+
+    `method == "DECLINE_ME"` is declined on purpose. Without a reachable
+    decline, the only exercised path would be acceptance, and M.1's whole
+    point is that a refusal is a first-class observable outcome; a surface
+    that can only say yes has not implemented it.
+    """
+    from .server.commands import Outcome      # the server half is optional
+    if record.get("method") == "DECLINE_ME":
+        return Outcome.decline(
+            "the demo handler declines this method by arrangement, so a "
+            "caller can see M.1's decline path without a backend: a refusal "
+            "carries a reason and is not an absence")
+    return Outcome.accept(
+        "accepted by the --demo handler, which records nothing: this registry "
+        "has no backend, and a handler that claimed to act would make the "
+        "surface look wired to something it is not")
+
+
 def main(argv: list[str] | None = None) -> int:
-    web, gateway, gw_http, pin, publish = _server()
+    web, commands, gateway, gw_http, pin, publish = _server()
     ap = build_parser(argparse.ArgumentParser(
         prog="python -m spatialdds.serve",
         description="Stand up a SpatialDDS registry."))
@@ -130,6 +155,21 @@ def main(argv: list[str] | None = None) -> int:
     if a.mcap is not None and not a.mcap.is_file():
         raise SystemExit(f"no such recording: {a.mcap}")
 
+    # The N.6 demo handler. `--demo` exists so the surface is exercisable
+    # without a backend, and a command surface nobody can POST to is a route
+    # with no evidence behind it -- the conformance suite's first clause had
+    # never been exercised by any run in this program precisely because there
+    # was nothing to exercise it against.
+    #
+    # It accepts a `GeoAnchor` command and declines one verb, so both of M.1's
+    # outcomes are reachable from a bare `--demo`: acceptance, and a decline
+    # carrying a reason. It does nothing to the registry, because `--demo` has
+    # no backend to do anything with -- which is the honest shape for a
+    # reference handler and the reason its reason string says so.
+    cmd_registry = commands.Registry()
+    if a.demo:
+        cmd_registry.register("spatial.core.GeoAnchor", _demo_command)
+
     token = a.token or secrets.token_urlsafe(24)
     st = gateway.build_state(
         a.mcap, a.manifests if a.manifests and a.manifests.is_dir() else None)
@@ -284,7 +324,8 @@ def main(argv: list[str] | None = None) -> int:
     try:
         web.run_app(gw_http.make_app(st, base, token, a.publish, jr,
                                      a.assets if a.assets
-                                     and a.assets.is_dir() else None),
+                                     and a.assets.is_dir() else None,
+                                     command_registry=cmd_registry),
                     host=a.host, port=a.port, print=None)
     except OSError as e:
         # An already-bound port is the one failure where everything downstream

spatialdds-0.5.0/spatialdds/server/commands.py

@@ -0,0 +1,131 @@
+"""N.6 commands: the gateway owns the HTTP leg, a backend supplies the verbs.
+
+Appendix N.6 is four sentences long and delegates its conventions to M.1, so
+most of this module is the reasoning that fills the gap between them. The
+ruling this implements: **N.6 is a gateway surface whose semantics a backend
+supplies.** The gateway owns the route, the auth, the validation and the
+response shape; a backend registers a handler per command type and decides
+what a verb means. An endpoint whose backend registers nothing stays
+northbound-only, and its POST stays exactly as conformant as it was before
+this module existed.
+
+**Why there is a seam at all.** The first consumer of this surface is
+`SpatialDDS-demo`'s web bridge, which embeds the gateway against a live DDS
+bus: a `goto` arriving as a POST has to leave as a keyed `ModelCommand` on a
+DDS topic, and nothing in this repository knows how to do that or should. So
+the deliverable is not only the route but the boundary — the narrowest thing
+an embedder can implement to own the verbs without owning the HTTP.
+
+**What N.6 fixes and what it leaves open.** It fixes that a command is a POST,
+that the response carries the outcome *including an explicit decline*, and
+that an endpoint without a command lane refuses with `405` or `404` and never
+accepts a command it cannot act on. It says nothing about status codes for the
+outcomes themselves, nothing about how a client discovers that commands are
+accepted, and nothing about completion tracking. Those are decided here and
+documented in `docs/WIRE.md`; none of them is invented where the text speaks.
+
+**M.1's vocabulary, which N.6 points at.** A decline is "a first-class,
+observable outcome, not an absence", carrying a terminal state and a
+human-readable reason. The value of the pattern is that an observer can
+distinguish *refused* from *not-yet-answered* from *not-for-me*. That is why
+`Outcome` carries a reason on the decline path and why a declined command is
+not reported with a success status: a caller that checks only the status must
+not read a refusal as an acceptance, which would turn M.1's first-class
+outcome back into the absence it exists to replace.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+#: The manifest member that advertises a lane as accepting commands.
+#:
+#: **Implementation-defined, and flagged as a specification gap.** N.7's
+#: topic-entry table is a MUST-carry list of six fields plus two optional
+#: ones, and none of them can say "this lane accepts commands" --- while N.6
+#: says "where an endpoint exposes a command surface" and gives a client no
+#: way to find out whether it does. A client would otherwise have to POST and
+#: read the refusal, which is discovery by trial.
+#:
+#: So this member exists, under this repository's own name, documented in
+#: `docs/WIRE.md`, and filed for 1.9 rather than treated as settled. N.7's
+#: list is a floor rather than a ceiling, so carrying an extra member is
+#: conformant; a *client* may not depend on it until the specification adopts
+#: one, and nothing in this repository reads it except the manifest's own
+#: reader and the conformance suite.
+ADVERTISEMENT = "accepts_commands"
+
+
+@dataclass(frozen=True)
+class Outcome:
+    """What a backend did with a command.
+
+    Two states and a reason, which is M.1's vocabulary and not a richer one:
+    there is no `PENDING` because N.6 requires no completion tracking and
+    inventing it would put this gateway ahead of the specification it
+    implements. A backend that needs asynchronous completion reports
+    acceptance here and publishes the completion on its own lane, which is
+    what the DDS side already does.
+    """
+
+    accepted: bool
+    #: Required on a decline, and M.1 is why: "a decline is a first-class,
+    #: observable outcome, not an absence." A refusal with no reason is an
+    #: absence with a status code.
+    reason: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.accepted and not self.reason:
+            raise ValueError(
+                "a declined command must carry a reason: M.1 makes a decline "
+                "a first-class outcome, and a refusal nobody can read is the "
+                "absence it exists to replace")
+
+    @classmethod
+    def accept(cls, reason: str = "") -> "Outcome":
+        return cls(True, reason)
+
+    @classmethod
+    def decline(cls, reason: str) -> "Outcome":
+        return cls(False, reason)
+
+
+#: A handler receives the validated, lifted record --- the same JSON shape a
+#: GET of that type would serve, after N.1 canonicalization and schema
+#: validation --- and returns an `Outcome`. It never sees the request, the
+#: token or the socket: an embedder owns verbs, not HTTP.
+Handler = Callable[[dict[str, Any]], Outcome]
+
+
+class Registry:
+    """The handlers an embedder has registered, keyed by type FQN.
+
+    Keyed by FQN rather than by topic so that a backend which accepts
+    `spatial.owm.ModelCommand` accepts it wherever a scene advertises that
+    type, which is how every other type-keyed table in this package works
+    (`DURABILITY`, `PUBLISHABLE`, the schema index).
+
+    Empty is the normal state. A gateway serving a recording has no verbs to
+    offer, and N.6 says a conformance suite MUST NOT require a command
+    surface to exist.
+    """
+
+    def __init__(self) -> None:
+        self._handlers: dict[str, Handler] = {}
+
+    def register(self, fqn: str, handler: Handler) -> None:
+        """Take commands of one type. Re-registering replaces, deliberately:
+        an embedder reconfiguring a lane should not have to tear down."""
+        self._handlers[fqn] = handler
+
+    def accepts(self, fqn: str) -> bool:
+        return fqn in self._handlers
+
+    def handler(self, fqn: str) -> Handler | None:
+        return self._handlers.get(fqn)
+
+    def types(self) -> list[str]:
+        return sorted(self._handlers)
+
+    def __bool__(self) -> bool:
+        return bool(self._handlers)

{spatialdds-0.3.1 → spatialdds-0.5.0}/spatialdds/server/gateway.py

@@ -31,11 +31,11 @@ import json
 import math
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Iterable
+from typing import Any, Callable, Iterable
 
 from mcap.reader import make_reader
 
-from . import idlmodel, pin, webjson, xcdr2
+from . import commands, idlmodel, pin, webjson, xcdr2
 
 PUBLIC = "public-cacheable"
 OPERATOR = "operator-scoped"
@@ -553,7 +553,9 @@ def declared_service(st: State, scene: str) -> dict | None:
 
 
 def service_manifest(st: State, scene: str, base: str,
-                     declared: dict | None = None) -> dict:
+                     declared: dict | None = None,
+                     accepts_commands: Callable[[str], bool] | None = None
+                     ) -> dict:
     """The §8.2.3 service manifest for one scene.
 
     `service.connection` is deliberately absent: it carries DDS connection
@@ -587,6 +589,21 @@ def service_manifest(st: State, scene: str, base: str,
             "access": res.access,
             "url": base + path,
         })
+        # N.6 asks a client to POST a command to the lane that accepts one,
+        # and N.7's topic entry has no member that says which lane that is:
+        # its table is six MUST-carry fields plus `qos_profile` and
+        # `liveliness`, none of which can carry "verbs welcome here". Without
+        # something, a client discovers the command surface by POSTing and
+        # reading the refusal, which is discovery by trial.
+        #
+        # So this member is added, under this repository's own name, and
+        # filed as a specification gap rather than treated as settled -- see
+        # docs/WIRE.md and the 1.9 candidates entry. N.7's list is a floor
+        # and not a ceiling, so an extra member is conformant; it is omitted
+        # entirely rather than written `false`, so a manifest from an endpoint
+        # with no verbs is byte-identical to one from before this existed.
+        if accepts_commands and accepts_commands(res.fqn):
+            topics_block[-1][commands.ADVERTISEMENT] = True
     man: dict[str, Any] = {
         "id": f"spatialdds://spatialdds-web.local/{scene}/service/gateway",
         "profile": "spatial.manifest/1.8",
@@ -659,7 +676,8 @@ def service_manifest(st: State, scene: str, base: str,
 
 def search(st: State, base: str, geohash: str | None = None,
            kinds: list[str] | None = None,
-           coverage: list[dict] | None = None) -> dict:
+           coverage: list[dict] | None = None,
+           accepts_commands: Callable[[str], bool] | None = None) -> dict:
     """The §3.3.0 search response: `{"results": [...], "next_page_token": ""}`."""
     wanted: list[tuple[float, float, float, float]] = []
     if geohash:
@@ -679,10 +697,12 @@ def search(st: State, base: str, geohash: str | None = None,
     for scene in st.scenes:
         declared = declared_services(st, scene)
         if declared:
-            manifests.extend(service_manifest(st, scene, base, d)
+            manifests.extend(service_manifest(st, scene, base, d,
+                                              accepts_commands)
                              for d in declared)
         else:
-            manifests.append(service_manifest(st, scene, base))
+            manifests.append(service_manifest(st, scene, base,
+                                              accepts_commands=accepts_commands))
     for man in manifests:
         if kinds and man["service"]["kind"] not in kinds:
             continue