spatialdds 0.4.0__tar.gz → 0.5.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatialdds
-Version: 0.4.0
+Version: 0.5.1
 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
@@ -379,13 +379,57 @@ 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
+## 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.
+
+0.5.1 fixes a defect in 0.4.0's seam that only its first real consumer could
+find: `make_app(command_registry=...)` silently replaced a registry that was
+empty at the time, because `Registry` was falsy when empty and the assignment
+used `or`. Since an embedder must have the app before it can build the backend
+that supplies the handlers, passing an empty registry and filling it a few
+lines later is the normal shape — and every one of those registrations went to
+an object the app had already discarded. If you called `register()` before
+`make_app()`, 0.4.0 and 0.5.0 worked; if you called it after, the command lane
+advertised nothing and refused every POST.
+
+## Not in 0.5.1
 
 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, 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 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,

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

@@ -355,13 +355,57 @@ 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
+## 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.
+
+0.5.1 fixes a defect in 0.4.0's seam that only its first real consumer could
+find: `make_app(command_registry=...)` silently replaced a registry that was
+empty at the time, because `Registry` was falsy when empty and the assignment
+used `or`. Since an embedder must have the app before it can build the backend
+that supplies the handlers, passing an empty registry and filling it a few
+lines later is the normal shape — and every one of those registrations went to
+an object the app had already discarded. If you called `register()` before
+`make_app()`, 0.4.0 and 0.5.0 worked; if you called it after, the command lane
+advertised nothing and refused every POST.
+
+## Not in 0.5.1
 
 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, 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 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,

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

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

@@ -37,7 +37,7 @@ __all__ = [
     "content_manifest", "geo_anchor", "service_uri", "content_uri",
 ]
 
-__version__ = "0.4.0"
+__version__ = "0.5.1"
 #: 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.4.0 → spatialdds-0.5.1}/spatialdds/server/commands.py

@@ -127,5 +127,11 @@ class Registry:
     def types(self) -> list[str]:
         return sorted(self._handlers)
 
-    def __bool__(self) -> bool:
-        return bool(self._handlers)
+    # No `__bool__`. It returned `bool(self._handlers)`, which reads as a
+    # convenience and was a trap: `make_app` had `command_registry or
+    # Registry()`, so an empty registry -- the normal thing to pass, since an
+    # embedder needs the app before it can build the handlers -- was silently
+    # replaced by a fresh one, and every later `register()` was lost. Nothing
+    # else ever used the truthiness. A class whose emptiness is a legitimate
+    # state should not make `or` mean something surprising, so the method is
+    # gone rather than documented around.

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

@@ -476,12 +476,49 @@ def _written(request: web.Request, doc: Any, created: bool,
                      **_cache_headers(gateway.OPERATOR), **extra})
 
 
-async def _broadcast(request: web.Request, topic: str, event: dict) -> None:
-    """Hand an event to every subscriber currently on that topic."""
-    for q in list(request.app["subs"].get(topic, ())):
+def notify(app: web.Application, topic: str, event: dict) -> None:
+    """Hand an event to every subscriber currently on that topic.
+
+    **The second half of `publish.apply_sample`, and the reason this is
+    public.** `apply_sample` says what a *new* subscriber will replay;
+    this wakes the ones already connected. Until 0.5.0 only the first half
+    was public, so an embedder with a live backend could update the latched
+    set --- new subscribers and the collection GET saw it --- and had no way
+    to reach an open socket except to reimplement the two lines below against
+    `app["subs"]`, which is the one `make_app` key that is not a parameter.
+
+    Measured on 2026-10-17 while embedding this gateway against a live DDS
+    bus: `apply_sample` alone, with a subscriber connected and drained quiet,
+    delivered nothing for three seconds; the same event written into
+    `app["subs"]` by hand arrived immediately. One missing function, and the
+    workaround was vendoring a private one.
+
+    So the pair is the contract for a live backend:
+
+        publish.apply_sample(st, topic, res, key, data)   # what replays
+        gw_http.notify(app, topic, {"event": "sample",    # who hears it now
+                                    "topic": topic,
+                                    "key": key, "data": data})
+
+    Synchronous on purpose: it only puts onto unbounded queues, so there is
+    nothing to await, and a backend reading a DDS bus from a thread can call
+    it without arranging a loop.
+
+    Subscriptions only stay open to be woken when `live_subscriptions` is on
+    --- see `make_app`. Calling this against an endpoint serving a finished
+    recording is harmless and reaches nobody.
+    """
+    for q in list(app["subs"].get(topic, ())):
         q.put_nowait(event)
 
 
+async def _broadcast(request: web.Request, topic: str, event: dict) -> None:
+    """`notify` for a request handler. Kept so its two call sites read as
+    they did; the seam is `notify`, which takes the app rather than a
+    request because a live backend has one and not the other."""
+    notify(request.app, topic, event)
+
+
 async def post_command(request: web.Request) -> web.Response:
     """N.6: a command is a POST to the resource it acts on.
 
@@ -733,13 +770,17 @@ async def subscribe(request: web.Request) -> web.StreamResponse:
             break
         await ws.send_str(json.dumps(ev, sort_keys=True))
 
-    # With the publish surface on, the recording is one producer among
-    # others and the stream is not finished: the socket stays open and
-    # carries published samples and disposes as they are accepted. This is
-    # the only read-side behaviour the flag changes, and it changes it in the
-    # one direction a subscriber can already handle -- more events, same
-    # envelope. With the flag off, everything below runs exactly as before.
-    if request.app["publish"] and not ws.closed:
+    # The stream is not finished: the socket stays open and carries whatever
+    # arrives next -- samples and disposes a publisher sends, or anything an
+    # embedded live backend hands to `notify`. It changes the lane in the one
+    # direction a subscriber can already handle: more events, same envelope.
+    # With it off, everything below runs exactly as before.
+    #
+    # This was `app["publish"]` until 0.5.0, which meant a live backend had
+    # to expose a write surface to keep its subscribers connected. The two
+    # switches are separate now and `publish_enabled` still implies this one,
+    # so a caller that only ever passed the old flag is unaffected.
+    if request.app["live"] and not ws.closed:
         q: asyncio.Queue = asyncio.Queue()
         request.app["subs"].setdefault(topic, set()).add(q)
         try:
@@ -799,8 +840,28 @@ def make_app(state: gateway.State, base: str, token: str | None,
              publish_enabled: bool = False,
              journal: "publish.Journal | None" = None,
              assets: Path | None = None,
-             command_registry: "commands.Registry | None" = None
-             ) -> web.Application:
+             command_registry: "commands.Registry | None" = None,
+             live_subscriptions: bool | None = None) -> web.Application:
+    """The app, with two switches that used to be one.
+
+    `publish_enabled` means what its name says and nothing else: the
+    PUT/DELETE write surface. `live_subscriptions` controls socket lifetime
+    --- whether an N.5 subscription stays open after the recorded stream ends,
+    waiting for `notify`, instead of sending liveliness-false per key and
+    closing.
+
+    They were one flag until 0.5.0, which was a defect found by embedding:
+    a backend with its own live source had to switch publishing *on* to keep
+    its subscribers connected, which exposed a write surface it did not want.
+    Two behaviours under one flag named for the second.
+
+    `live_subscriptions` defaults to `None`, meaning "follow
+    `publish_enabled`", so every existing caller behaves exactly as it did ---
+    with publishing on, the recording is one producer among others and the
+    socket stays open, which is the sentence that was already true. An
+    embedder passes `publish_enabled=False, live_subscriptions=True` and gets
+    the live lane with no write surface at all.
+    """
     app = web.Application()
     app["state"] = state
     app["base"] = base.rstrip("/")
@@ -810,10 +871,21 @@ 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
+    app["live"] = publish_enabled if live_subscriptions is None \
+        else live_subscriptions
     # 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()
+    # `is not None`, not `or`. An empty registry is the normal thing to pass:
+    # an embedder needs the app before it can build the backend that supplies
+    # the handlers, so it passes a registry and populates it a few lines
+    # later. With `or` that registry was silently replaced -- `Registry` used
+    # to be falsy when empty -- and every later `register()` went to an object
+    # the app had already thrown away. Found by the web bridge, whose command
+    # lane advertised nothing and refused every POST while its own registry
+    # held the handler.
+    app["commands"] = (command_registry if command_registry is not None
+                       else commands.Registry())
     app["journal"] = journal
     app["subs"] = {}
     app["assets"] = assets

{spatialdds-0.4.0 → spatialdds-0.5.1}/spatialdds/server/publish.py

@@ -207,7 +207,15 @@ def resource_for_put(st: gateway.State, scene: str, stream: str,
 
 def apply_sample(st: gateway.State, topic: str, res: gateway.Resource,
                  key: str, data: dict) -> bool:
-    """Put an instance into the latched set. True if it is new."""
+    """Put an instance into the latched set. True if it is new.
+
+    This is half of what a live backend needs, and the half that is easy to
+    mistake for all of it: it decides what a *new* subscriber replays and what
+    the collection GET returns, and it reaches nobody already on a socket.
+    `gw_http.notify(app, topic, event)` is the other half. An embedder that
+    calls only this one has a registry that is correct for every client except
+    the ones currently watching.
+    """
     created = key not in st.latched.get(topic, {})
     st.latched.setdefault(topic, {})[key] = gateway.Instance(
         key, data, webjson.digest(data))

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatialdds
-Version: 0.4.0
+Version: 0.5.1
 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
@@ -379,13 +379,57 @@ 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
+## 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.
+
+0.5.1 fixes a defect in 0.4.0's seam that only its first real consumer could
+find: `make_app(command_registry=...)` silently replaced a registry that was
+empty at the time, because `Registry` was falsy when empty and the assignment
+used `or`. Since an embedder must have the app before it can build the backend
+that supplies the handlers, passing an empty registry and filling it a few
+lines later is the normal shape — and every one of those registrations went to
+an object the app had already discarded. If you called `register()` before
+`make_app()`, 0.4.0 and 0.5.0 worked; if you called it after, the command lane
+advertised nothing and refused every POST.
+
+## Not in 0.5.1
 
 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, 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 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,