spatialdds 0.3.0__tar.gz → 0.4.0__tar.gz

{spatialdds-0.3.0 → spatialdds-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatialdds
-Version: 0.3.0
+Version: 0.4.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
@@ -43,6 +43,10 @@ not have to assemble member by member.
 specification versions move independently; `spatialdds.SPEC_COMMIT` is the one
 that says what the wire looks like.
 
+The source, the reference gateway, the recordings and every gate behind the
+claims on this page are at [https://github.com/OpenArCloud/spatialdds-web](https://github.com/OpenArCloud/spatialdds-web). Every code block below is executed
+by one of those gates on every run, against an endpoint started for it.
+
 ## Your own registry, in one command
 
 ```sh
@@ -72,17 +76,26 @@ Appendix N's schemas make every member of a record required, so an `Announce`
 is eighteen members, a `ContentAnnounce` sixteen, a `GeoAnchor` nine. The
 builders take the arguments you actually have:
 
+<!-- bar: verbs -->
 ```python
 import spatialdds as sd
+ep = sd.connect("http://127.0.0.1:8787", token="not-a-secret", scene="mytown")
+a = ep.publish_service(service_id="mytown-vps", kind="VPS",
+                       coverage=sd.circle(30.2849, -97.7393, 500))
+b = ep.publish_content(
+    content_id="duck", title="A duck", position=(30.2849, -97.7393),
+    asset=sd.asset_ref("https://cdn.example/duck.gltf",
+                       media_type="model/gltf+json"))
+c = ep.publish_anchor("anchor/duck-perch", lat=30.2849, lon=-97.7393,
+                      method="VisualFix", sigma_enu_m=(0.25, 0.25, 0.5),
+                      content="duck")
+print("service", a.created, "| content", b.created, "| anchor", c.created)
+print("manifest", b.manifest.doc["id"])
+```
 
-ep = sd.connect("http://127.0.0.1:8787", token="tok", scene="mytown")
-ep.publish_service(service_id="mytown-vps", kind="VPS",
-                   coverage=sd.circle(30.2849, -97.7393, 500))
-ep.publish_content(content_id="duck", title="Duck", position=(30.2849, -97.7393),
-                   asset="https://cdn.example/duck.gltf", sha256=digest)
-ep.publish_anchor("anchor/duck-perch", lat=30.2849, lon=-97.7393,
-                  method="VisualFix", sigma_enu_m=(0.25, 0.25, 0.5),
-                  content="duck")
+```console
+service True | content True | anchor True
+manifest spatialdds://demo.spatialdds.org/mytown/content/duck
 ```
 
 `publish_service` and `publish_content` are two PUTs each -- the manifest
@@ -91,9 +104,12 @@ with the manifest's own result on `.manifest`.
 
 A full service contract is the same one call, with the claims stated:
 
+<!-- bar: contract -->
 ```python
+import spatialdds as sd
+ep = sd.connect("http://127.0.0.1:8787", token="not-a-secret", scene="mytown")
 area = sd.circle(30.2849, -97.7393, 500)
-ep.publish_service(
+w = ep.publish_service(
     service_id="mytown-vps", kind="VPS", coverage=area,
     caps=sd.capabilities(
         supported=[sd.profile("spatial.core", minor=8)],
@@ -101,19 +117,28 @@ ep.publish_service(
     manifest=sd.service_manifest(
         "mytown-vps", "VPS", authority=ep.authority, scene="mytown",
         profiles=["Core", "AR+Geo"],
-        request={{"features_topic": "feat.keyframe"}},
-        response={{"minimal": "geo.fix"}},
-        limits={{"max_fps": 10}},
-        auth={{"scheme": "bearer", "issuer": "https://registry.mytown.example"}},
+        request={"features_topic": "feat.keyframe"},
+        response={"minimal": "geo.fix"},
+        limits={"max_fps": 10},
+        auth={"scheme": "bearer",
+              "issuer": "https://registry.mytown.example"},
         coverage=area, cells=sd.cells(area)))
+print("profiles", w.manifest.doc["profiles"])
+print("limits  ", w.manifest.doc["limits"])
+```
+
+```console
+profiles ['Core', 'AR+Geo']
+limits   {'max_fps': 10}
 ```
 
 Every one of those is something a service operator knows and a library cannot
-guess. [docs/MYTOWN.md](../../docs/MYTOWN.md) publishes that and prints the
-whole served document; `gates/builders.py` rebuilds this repository's
-hand-authored `austin-vps` and duck records through these calls and compares
-them member by member, which is what makes "every member is reachable from an
-argument" a check rather than a claim.
+guess. [The mytown walkthrough](https://github.com/OpenArCloud/spatialdds-web/blob/main/docs/MYTOWN.md) publishes that
+and prints the whole served document;
+[`gates/builders.py`](https://github.com/OpenArCloud/spatialdds-web/blob/main/gates/builders.py) rebuilds that
+repository's hand-authored `austin-vps` and duck records through these calls
+and compares them member by member, which is what makes "every member is
+reachable from an argument" a check rather than a claim.
 
 **Two forms for an asset, because there are two situations.**
 `sd.asset(path_or_bytes, media_type=...)` reads the data and computes the hash
@@ -122,7 +147,8 @@ and the byte count itself: a hash nobody typed is a hash a reader can trust.
 else hosts, and the hash comes from whoever has the bytes. Pass no hash and
 the reference carries no integrity claim, which costs a reader one thing:
 `fetch_asset()` raises rather than reporting a check it could not perform
-(finding 31). `publish_content` takes either, or a path, or bytes, or a URL.
+([finding 31](https://github.com/OpenArCloud/spatialdds-web/blob/main/WEB-BINDING-FINDINGS.md)).
+`publish_content` takes either, or a path, or bytes, or a URL.
 
 The builders are also usable on their own: `sd.service_announce`,
 `sd.service_manifest`, `sd.content_announce`, `sd.content_manifest`,
@@ -258,7 +284,7 @@ call goes away and the bar is one line.
 
 ## The surface
 
-| | |
+| call | what it does |
 | --- | --- |
 | `sd.connect(base, token=None, verify_integrity=True, timeout=15.0, lifted=True, scene="default", authority=None)` | an `Endpoint`; nothing is fetched until you ask |
 | `ep.search(geohash=None, kinds=None)` | §3.3.0 search → a list of `Hit` |
@@ -309,7 +335,7 @@ One family, built from the endpoint's own N.8 problem documents — `status`,
 `type`, `detail` carried, not re-invented. Everything below derives from
 `SpatialDDSError`, so one `except` catches the lot.
 
-| | |
+| exception | raised when |
 | --- | --- |
 | `Unreachable` | the endpoint did not answer; names the URL and the serve line |
 | `Unauthorized` | 401; says to pass `token=` and where the token is printed |
@@ -330,13 +356,43 @@ 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.0
+## 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.
+
+## Not in 0.4.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.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
+line naming a flag that does not exist.
 
-`sd.asset` changed meaning in 0.3.0, which is why the version moved: it now
+`sd.asset` changed meaning in 0.3.0, which is why that version moved: it now
 reads bytes and computes a hash, where in 0.2.0 it took a URL and a hash you
 supplied. That second form is `sd.asset_ref`. A published release has to stay
 reproducible from a public commit, so the API could not change under the same

{spatialdds-0.3.0 → spatialdds-0.4.0}/README.md

@@ -19,6 +19,10 @@ not have to assemble member by member.
 specification versions move independently; `spatialdds.SPEC_COMMIT` is the one
 that says what the wire looks like.
 
+The source, the reference gateway, the recordings and every gate behind the
+claims on this page are at [https://github.com/OpenArCloud/spatialdds-web](https://github.com/OpenArCloud/spatialdds-web). Every code block below is executed
+by one of those gates on every run, against an endpoint started for it.
+
 ## Your own registry, in one command
 
 ```sh
@@ -48,17 +52,26 @@ Appendix N's schemas make every member of a record required, so an `Announce`
 is eighteen members, a `ContentAnnounce` sixteen, a `GeoAnchor` nine. The
 builders take the arguments you actually have:
 
+<!-- bar: verbs -->
 ```python
 import spatialdds as sd
+ep = sd.connect("http://127.0.0.1:8787", token="not-a-secret", scene="mytown")
+a = ep.publish_service(service_id="mytown-vps", kind="VPS",
+                       coverage=sd.circle(30.2849, -97.7393, 500))
+b = ep.publish_content(
+    content_id="duck", title="A duck", position=(30.2849, -97.7393),
+    asset=sd.asset_ref("https://cdn.example/duck.gltf",
+                       media_type="model/gltf+json"))
+c = ep.publish_anchor("anchor/duck-perch", lat=30.2849, lon=-97.7393,
+                      method="VisualFix", sigma_enu_m=(0.25, 0.25, 0.5),
+                      content="duck")
+print("service", a.created, "| content", b.created, "| anchor", c.created)
+print("manifest", b.manifest.doc["id"])
+```
 
-ep = sd.connect("http://127.0.0.1:8787", token="tok", scene="mytown")
-ep.publish_service(service_id="mytown-vps", kind="VPS",
-                   coverage=sd.circle(30.2849, -97.7393, 500))
-ep.publish_content(content_id="duck", title="Duck", position=(30.2849, -97.7393),
-                   asset="https://cdn.example/duck.gltf", sha256=digest)
-ep.publish_anchor("anchor/duck-perch", lat=30.2849, lon=-97.7393,
-                  method="VisualFix", sigma_enu_m=(0.25, 0.25, 0.5),
-                  content="duck")
+```console
+service True | content True | anchor True
+manifest spatialdds://demo.spatialdds.org/mytown/content/duck
 ```
 
 `publish_service` and `publish_content` are two PUTs each -- the manifest
@@ -67,9 +80,12 @@ with the manifest's own result on `.manifest`.
 
 A full service contract is the same one call, with the claims stated:
 
+<!-- bar: contract -->
 ```python
+import spatialdds as sd
+ep = sd.connect("http://127.0.0.1:8787", token="not-a-secret", scene="mytown")
 area = sd.circle(30.2849, -97.7393, 500)
-ep.publish_service(
+w = ep.publish_service(
     service_id="mytown-vps", kind="VPS", coverage=area,
     caps=sd.capabilities(
         supported=[sd.profile("spatial.core", minor=8)],
@@ -77,19 +93,28 @@ ep.publish_service(
     manifest=sd.service_manifest(
         "mytown-vps", "VPS", authority=ep.authority, scene="mytown",
         profiles=["Core", "AR+Geo"],
-        request={{"features_topic": "feat.keyframe"}},
-        response={{"minimal": "geo.fix"}},
-        limits={{"max_fps": 10}},
-        auth={{"scheme": "bearer", "issuer": "https://registry.mytown.example"}},
+        request={"features_topic": "feat.keyframe"},
+        response={"minimal": "geo.fix"},
+        limits={"max_fps": 10},
+        auth={"scheme": "bearer",
+              "issuer": "https://registry.mytown.example"},
         coverage=area, cells=sd.cells(area)))
+print("profiles", w.manifest.doc["profiles"])
+print("limits  ", w.manifest.doc["limits"])
+```
+
+```console
+profiles ['Core', 'AR+Geo']
+limits   {'max_fps': 10}
 ```
 
 Every one of those is something a service operator knows and a library cannot
-guess. [docs/MYTOWN.md](../../docs/MYTOWN.md) publishes that and prints the
-whole served document; `gates/builders.py` rebuilds this repository's
-hand-authored `austin-vps` and duck records through these calls and compares
-them member by member, which is what makes "every member is reachable from an
-argument" a check rather than a claim.
+guess. [The mytown walkthrough](https://github.com/OpenArCloud/spatialdds-web/blob/main/docs/MYTOWN.md) publishes that
+and prints the whole served document;
+[`gates/builders.py`](https://github.com/OpenArCloud/spatialdds-web/blob/main/gates/builders.py) rebuilds that
+repository's hand-authored `austin-vps` and duck records through these calls
+and compares them member by member, which is what makes "every member is
+reachable from an argument" a check rather than a claim.
 
 **Two forms for an asset, because there are two situations.**
 `sd.asset(path_or_bytes, media_type=...)` reads the data and computes the hash
@@ -98,7 +123,8 @@ and the byte count itself: a hash nobody typed is a hash a reader can trust.
 else hosts, and the hash comes from whoever has the bytes. Pass no hash and
 the reference carries no integrity claim, which costs a reader one thing:
 `fetch_asset()` raises rather than reporting a check it could not perform
-(finding 31). `publish_content` takes either, or a path, or bytes, or a URL.
+([finding 31](https://github.com/OpenArCloud/spatialdds-web/blob/main/WEB-BINDING-FINDINGS.md)).
+`publish_content` takes either, or a path, or bytes, or a URL.
 
 The builders are also usable on their own: `sd.service_announce`,
 `sd.service_manifest`, `sd.content_announce`, `sd.content_manifest`,
@@ -234,7 +260,7 @@ call goes away and the bar is one line.
 
 ## The surface
 
-| | |
+| call | what it does |
 | --- | --- |
 | `sd.connect(base, token=None, verify_integrity=True, timeout=15.0, lifted=True, scene="default", authority=None)` | an `Endpoint`; nothing is fetched until you ask |
 | `ep.search(geohash=None, kinds=None)` | §3.3.0 search → a list of `Hit` |
@@ -285,7 +311,7 @@ One family, built from the endpoint's own N.8 problem documents — `status`,
 `type`, `detail` carried, not re-invented. Everything below derives from
 `SpatialDDSError`, so one `except` catches the lot.
 
-| | |
+| exception | raised when |
 | --- | --- |
 | `Unreachable` | the endpoint did not answer; names the URL and the serve line |
 | `Unauthorized` | 401; says to pass `token=` and where the token is printed |
@@ -306,13 +332,43 @@ 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.0
+## 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.
+
+## Not in 0.4.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.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
+line naming a flag that does not exist.
 
-`sd.asset` changed meaning in 0.3.0, which is why the version moved: it now
+`sd.asset` changed meaning in 0.3.0, which is why that version moved: it now
 reads bytes and computes a hash, where in 0.2.0 it took a URL and a hash you
 supplied. That second form is `sd.asset_ref`. A published release has to stay
 reproducible from a public commit, so the API could not change under the same

{spatialdds-0.3.0 → spatialdds-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spatialdds"
-version = "0.3.0"
+version = "0.4.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.0 → spatialdds-0.4.0}/spatialdds/__init__.py

@@ -37,7 +37,7 @@ __all__ = [
     "content_manifest", "geo_anchor", "service_uri", "content_uri",
 ]
 
-__version__ = "0.3.0"
+__version__ = "0.4.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.0 → spatialdds-0.4.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.4.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.0 → spatialdds-0.4.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