spatialdds 0.3.1__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatialdds
-Version: 0.3.1
+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
@@ -356,13 +356,37 @@ 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.
+
+## 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 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.4.0}/README.md

@@ -332,13 +332,37 @@ 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.
+
+## 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 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.4.0}/pyproject.toml

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

@@ -37,7 +37,7 @@ __all__ = [
     "content_manifest", "geo_anchor", "service_uri", "content_uri",
 ]
 
-__version__ = "0.3.1"
+__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.1 → 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.1 → 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

{spatialdds-0.3.1 → spatialdds-0.4.0}/spatialdds/server/gw_http.py

@@ -36,7 +36,7 @@ from typing import Any
 
 from aiohttp import WSMsgType, web
 
-from . import gateway, publish, webjson
+from . import commands, gateway, publish, webjson
 
 WELL_KNOWN = "/.well-known/spatialdds"
 
@@ -211,7 +211,8 @@ async def search(request: web.Request) -> web.Response:
         kinds = [k] if k else []
     try:
         doc = gateway.search(st, base, geohash=geohash, kinds=kinds,
-                             coverage=coverage)
+                             coverage=coverage,
+                             accepts_commands=request.app["commands"].accepts)
     except ValueError as e:
         raise web.HTTPBadRequest(
             body=_body({"type": PROBLEM_NS + "bad-query",
@@ -481,6 +482,98 @@ async def _broadcast(request: web.Request, topic: str, event: dict) -> None:
         q.put_nowait(event)
 
 
+async def post_command(request: web.Request) -> web.Response:
+    """N.6: a command is a POST to the resource it acts on.
+
+    The resource is the lane, not the instance, and the addressee rides in the
+    body. That is M.1's shape -- "a shared keyed command topic, keyed by the
+    addressee" -- and it is also the URL the manifest advertises, which is the
+    URL a client holding a manifest already has. Posting to an instance path
+    would make a client build a URL by string surgery on a key, which is the
+    thing N.7's `url` member exists to abolish.
+
+    Four outcomes, and the status carries which:
+
+    * **202** the backend accepted it. Acceptance, not completion: N.6
+      requires no completion tracking, so this gateway invents none.
+    * **409** the backend declined, with M.1's reason in the problem document.
+      Not a 200: 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.
+    * **405** no handler for this type, or this lane is not a command lane.
+      N.6 names 405 or 404 for an endpoint with nothing to accept a verb for,
+      and the body is still an N.8 problem document so the absence is stated
+      rather than left to a framework's default page.
+    * **400/401** the body is not valid for the type, or no bearer credential.
+      Commands are writes, so N.4's operator-scoped path applies.
+    """
+    st: gateway.State = request.app["state"]
+    reg: commands.Registry = request.app["commands"]
+    m = request.match_info
+    path = f"/{m['scene']}/{m['stream']}/{m['type']}/{m['version']}"
+    res = st.resources.get(path)
+
+    # Refuse before authenticating when there is nothing here to command: a
+    # 401 would tell an anonymous caller that a lane exists, and the lane's
+    # existence is public information that this endpoint simply does not have.
+    if res is None:
+        return _rejected(publish.Rejected(
+            405, "no-command-lane", "No command lane here",
+            f"This endpoint serves no resource at {path}, so there is no verb "
+            f"to accept. N.6: an endpoint with no command lane refuses "
+            f"cleanly and never accepts a command it cannot act on."), request)
+    if not reg.accepts(res.fqn):
+        return _rejected(publish.Rejected(
+            405, "no-command-lane", "No command lane here",
+            f"This endpoint serves {res.fqn} read-only: no backend has "
+            f"registered a handler for it, so there is nothing that could act "
+            f"on a verb. N.6 makes that a clean refusal rather than a silent "
+            f"acceptance.",
+            accepts=reg.types()), request)
+
+    if not _authorized(request, request.app["token"]):
+        return _unauthorized(str(request.rel_url))
+
+    try:
+        body = await request.json()
+    except Exception as e:
+        return _rejected(publish.Rejected(
+            400, "not-json", "Body is not JSON",
+            f"The body must be N.1 canonical JSON: {e}"), request)
+    try:
+        publish.validate_schema(res.fqn, body)
+        data, _raw = publish.canonicalize(st, res.fqn, body)
+    except publish.Rejected as r:
+        return _rejected(r, request)
+
+    handler = reg.handler(res.fqn)
+    assert handler is not None          # reg.accepts() was true above
+    try:
+        outcome = handler(data)
+    except Exception as e:
+        # A backend that raises is a backend that did not decide. Reporting
+        # 500 is honest; reporting a decline would put words in its mouth.
+        return _problem(500, "handler-failed", "The command handler failed",
+                        f"The backend registered for {res.fqn} raised "
+                        f"{type(e).__name__}: {e}",
+                        instance=str(request.rel_url))
+
+    if outcome.accepted:
+        doc: dict[str, Any] = {"outcome": "accepted", "type": res.fqn}
+        if outcome.reason:
+            doc["reason"] = outcome.reason
+        # Built directly rather than through `_json_response`, which is for
+        # resources: it answers 200 and honours If-None-Match, and a command
+        # outcome is neither cacheable nor re-fetchable. `no-store` because
+        # N.4 forbids any lifetime on an operator-scoped surface.
+        return web.Response(body=_body(doc), status=202,
+                            content_type="application/json",
+                            headers={"Cache-Control": "no-store"})
+    return _rejected(publish.Rejected(
+        409, "command-declined", "The command was declined",
+        outcome.reason, outcome="declined", type=res.fqn), request)
+
+
 async def put_instance(request: web.Request) -> web.Response:
     """PUT on the same instance URL a GET already serves."""
     if not request.app["publish"]:
@@ -705,7 +798,9 @@ async def root(request: web.Request) -> web.Response:
 def make_app(state: gateway.State, base: str, token: str | None,
              publish_enabled: bool = False,
              journal: "publish.Journal | None" = None,
-             assets: Path | None = None) -> web.Application:
+             assets: Path | None = None,
+             command_registry: "commands.Registry | None" = None
+             ) -> web.Application:
     app = web.Application()
     app["state"] = state
     app["base"] = base.rstrip("/")
@@ -715,6 +810,10 @@ def make_app(state: gateway.State, base: str, token: str | None,
     # default page, and so that the surface's absence is something the
     # endpoint states rather than something a caller infers from a 405.
     app["publish"] = publish_enabled
+    # The N.6 seam. Empty is the normal state: a gateway serving a recording
+    # has no verbs, and N.6 says a suite MUST NOT require a command surface
+    # to exist. An embedder registers handlers on this.
+    app["commands"] = command_registry or commands.Registry()
     app["journal"] = journal
     app["subs"] = {}
     app["assets"] = assets
@@ -732,6 +831,12 @@ def make_app(state: gateway.State, base: str, token: str | None,
         # `spatialdds/` removed, collection then instance.
         web.get("/{scene}/{stream}/{type}/{version}", collection),
         web.get("/{scene}/{stream}/{type}/{version}/{key}", instance),
+        # N.6: a command POST on the lane's own collection URL -- the one
+        # the manifest advertises, so a client follows a link rather than
+        # building a path. Registered unconditionally, like the write
+        # surface below and for the same reason: a refusal should be a stated
+        # N.8 problem document, not a framework's default 405 page.
+        web.post("/{scene}/{stream}/{type}/{version}", post_command),
         # The write surface, on the same URLs the GETs serve.
         web.put("/{scene}/{stream}/{type}/{version}/{key}", put_instance),
         web.delete("/{scene}/{stream}/{type}/{version}/{key}",

{spatialdds-0.3.1 → spatialdds-0.4.0}/spatialdds.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatialdds
-Version: 0.3.1
+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
@@ -356,13 +356,37 @@ 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.
+
+## 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 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.4.0}/spatialdds.egg-info/SOURCES.txt

@@ -136,6 +136,7 @@ spatialdds/demo/assets/fountain-marker.gltf
 spatialdds/demo/manifests/content-fountain-label.json
 spatialdds/demo/manifests/content-fountain-marker.json
 spatialdds/server/__init__.py
+spatialdds/server/commands.py
 spatialdds/server/gateway.py
 spatialdds/server/gw_http.py
 spatialdds/server/idlmodel.py