spatialdds 0.8.1__tar.gz → 0.8.3__tar.gz

{spatialdds-0.8.1 → spatialdds-0.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatialdds
-Version: 0.8.1
+Version: 0.8.3
 Summary: SpatialDDS for programs: a client for the web binding (Appendix N), a native DDS participant, and the reference registry behind one command.
 Author: Open AR Cloud
 License: Apache-2.0
@@ -25,12 +25,21 @@ Provides-Extra: dds
 Requires-Dist: cyclonedds<12,>=11.0.1; extra == "dds"
 Requires-Dist: mcap>=1.1; extra == "dds"
 Requires-Dist: jsonschema>=4.0; extra == "dds"
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.3; extra == "mcp"
 
 # spatialdds
 
 SpatialDDS for programs: a client over plain HTTPS and a WebSocket, a native
 DDS participant, and the reference registry behind one command.
 
+**Integrating with a registry, or with the public sandbox at
+demo.spatialdds.org?** Start with the
+[integrator guide](https://github.com/OpenArCloud/spatialdds-py/blob/main/docs/integrator-guide.md):
+read, watch, and publish content, live entities and claims, and every
+refusal you can meet. Every command in it is run by a gate, in order,
+against the code in the repository.
+
 ```sh
 pip install spatialdds                       # the client: two dependencies
 pip install "spatialdds[server]"             # and the registry
@@ -481,6 +490,13 @@ what such a field digests or in what form (spatialdds-py finding 31). Where a
 declared value does not parse as a SHA-256 of the asset's bytes, this library
 raises rather than reporting a check it did not perform.
 
+One warning, not an error: **`AdvertisedOriginWarning`** (a `UserWarning`),
+once per endpoint, when its search results or resolver metadata advertise
+URLs on another origin than the one you connected to. The library reads
+through your origin either way, so it keeps working; a client that follows
+the advertised URLs reaches the other one, which usually means the endpoint
+was started without `--public-url`. The message names both origins.
+
 ## Integrity by default
 
 Latched reads revalidate with the ETag the endpoint gave; `fetch_asset` checks

{spatialdds-0.8.1 → spatialdds-0.8.3}/README.md

@@ -3,6 +3,13 @@
 SpatialDDS for programs: a client over plain HTTPS and a WebSocket, a native
 DDS participant, and the reference registry behind one command.
 
+**Integrating with a registry, or with the public sandbox at
+demo.spatialdds.org?** Start with the
+[integrator guide](https://github.com/OpenArCloud/spatialdds-py/blob/main/docs/integrator-guide.md):
+read, watch, and publish content, live entities and claims, and every
+refusal you can meet. Every command in it is run by a gate, in order,
+against the code in the repository.
+
 ```sh
 pip install spatialdds                       # the client: two dependencies
 pip install "spatialdds[server]"             # and the registry
@@ -453,6 +460,13 @@ what such a field digests or in what form (spatialdds-py finding 31). Where a
 declared value does not parse as a SHA-256 of the asset's bytes, this library
 raises rather than reporting a check it did not perform.
 
+One warning, not an error: **`AdvertisedOriginWarning`** (a `UserWarning`),
+once per endpoint, when its search results or resolver metadata advertise
+URLs on another origin than the one you connected to. The library reads
+through your origin either way, so it keeps working; a client that follows
+the advertised URLs reaches the other one, which usually means the endpoint
+was started without `--public-url`. The message names both origins.
+
 ## Integrity by default
 
 Latched reads revalidate with the ETag the endpoint gave; `fetch_asset` checks

{spatialdds-0.8.1 → spatialdds-0.8.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spatialdds"
-version = "0.8.1"
+version = "0.8.3"
 description = "SpatialDDS for programs: a client for the web binding (Appendix N), a native DDS participant, and the reference registry behind one command."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -40,9 +40,17 @@ server = ["aiohttp>=3.8", "mcap>=1.1", "jsonschema>=4.0"]
 # Without this extra `import spatialdds` is unchanged, and `sd.participant`
 # raises `sd.MissingExtra` naming it.
 dds = ["cyclonedds>=11.0.1,<12", "mcap>=1.1", "jsonschema>=4.0"]
+# Being an MCP server over the web binding: `spatialdds-mcp`. The official
+# SDK, and nothing else: the server reads with this package's own client,
+# so it needs no aiohttp, no mcap and no cyclonedds. 2.x because its API is
+# the one written against (1.x's FastMCP is 2.x's MCPServer), which needs
+# Python 3.10 or newer; without this extra the base install is unchanged and
+# `spatialdds-mcp` exits saying which line to run.
+mcp = ["mcp>=2.3,<3"]
 
 [project.scripts]
 spatialdds-serve = "spatialdds.serve:main"
+spatialdds-mcp = "spatialdds.mcp_server:main"
 
 [project.urls]
 Homepage = "https://github.com/OpenArCloud/spatialdds-py"

{spatialdds-0.8.1 → spatialdds-0.8.3}/spatialdds/__init__.py

@@ -26,7 +26,7 @@ __all__ = [
     "connect", "Endpoint", "Hit", "Topic", "Resolved", "Written",
     "Sample", "Dispose", "EndOfReplay", "Liveliness",
     "SpatialDDSError", "Unreachable", "Problem", "Unauthorized", "SurfaceOff",
-    "IntegrityError", "UnverifiableIntegrity",
+    "IntegrityError", "UnverifiableIntegrity", "AdvertisedOriginWarning",
     "lift", "SPEC_TAG", "SPEC_COMMIT", "APPENDIX_N", "__version__",
     # The record builders, re-exported so that `sd.circle(...)` reads the way
     # it does in the documentation. They live in `spatialdds.records`.
@@ -41,7 +41,7 @@ __all__ = [
     "participant", "MissingExtra", "dds", "events", "frames", "Recency",
 ]
 
-__version__ = "0.8.1"
+__version__ = "0.8.3"
 #: 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.8.1 → spatialdds-0.8.3}/spatialdds/artifacts/openapi.html

@@ -14,4 +14,4 @@ border-bottom:1px solid var(--line)}p{margin:.35rem 0}.mut,.sum .auth{color:
 var(--mut)}.auth{font-size:.85rem;margin-left:.4rem}.v{display:inline-block;
 min-width:4.2rem;font:600 12px ui-monospace,monospace;letter-spacing:.04em;
 color:var(--acc)}.codes{font:12px ui-monospace,monospace;color:var(--mut)}
-.s{margin-right:.5rem}.s4,.s5{color:#b5482c}a{color:var(--acc)}</style></head><body><main><h1>SpatialDDS web binding (spatialdds-py)</h1><p class=mut>Version 0.8.1 · OpenAPI 3.1.0 · generated, never hand-written · <a href='openapi'>openapi.yaml</a></p><p>Generated by <code>tools/gen_openapi.py</code> from the gateway&#x27;s own tables and the published JSON Schemas; never edited by hand. Reads are open; writes take a bearer token scoped to scenes. The WebSocket streams (N.5) are described on each collection path, not modelled. A deployment&#x27;s own keyed types (<code>serve --extension</code>) are publishable on their own collection paths, under the same rules as the entity lane when they carry <code>basis</code>, <code>state</code>, <code>state_reason</code> and <code>stamp</code>; a type that names an <code>asserter</code> has it stamped or verified as the bearer token&#x27;s principal (<code>asserter-not-principal</code>, <code>asserter-ungrounded</code>). Their paths are not listed here, because the deployment chooses them.</p><h2>Operations</h2><section id="search"><h3><span class="v get">GET</span> <code>/.well-known/spatialdds/search</code></h3><p class="sum">Services near a geohash (§8.2.3 manifests) <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s4">429</span></p></section><section id="searchPost"><h3><span class="v post">POST</span> <code>/.well-known/spatialdds/search</code></h3><p class="sum">The same search, as a POST body <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s4">429</span> <span class="s s4">413</span> <span class="s s4">415</span></p></section><section id="listSchemas"><h3><span class="v get">GET</span> <code>/.well-known/spatialdds/schemas</code></h3><p class="sum">The published JSON Schemas, by type <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s4">429</span></p></section><section id="getSchema"><h3><span class="v get">GET</span> <code>/.well-known/spatialdds/schemas/{type}</code></h3><p class="sum"> <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s4">404</span> <span class="s s4">429</span></p></section><section id="bootstrap"><h3><span class="v get">GET</span> <code>/.well-known/spatialdds/bootstrap</code></h3><p class="sum">DDS-join material (N.2); optional <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s4">404</span> <span class="s s4">429</span></p></section><section id="resolverMetadata"><h3><span class="v get">GET</span> <code>/.well-known/spatialdds/resolver</code></h3><p class="sum">§7.5.2 resolver metadata <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s4">404</span> <span class="s s4">429</span></p></section><section id="openapi"><h3><span class="v get">GET</span> <code>/.well-known/spatialdds/openapi</code></h3><p class="sum">This document <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s4">429</span></p></section><section id="openapiPage"><h3><span class="v get">GET</span> <code>/.well-known/spatialdds/openapi.html</code></h3><p class="sum">This document as a static reference page <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s4">429</span></p></section><section id="resolve"><h3><span class="v get">GET</span> <code>/spatialdds/resolve</code></h3><p class="sum">Resolve a URI to its manifest (§7.5.2) <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s4">400</span> <span class="s s4">404</span> <span class="s s4">429</span></p></section><section id="putManifest"><h3><span class="v put">PUT</span> <code>/spatialdds/resolve</code></h3><p class="sum">Publish a manifest, keyed by its own <code>id</code> <span class="auth">token</span></p><p>The <code>uri</code> parameter is not used; the body&#x27;s <code>id</code> is the key. Its scene segment is the lane. **Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>).</p><p class="codes"><span class="s s2">200</span> <span class="s s2">201</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">405</span> <span class="s s4">429</span> <span class="s s4">413</span> <span class="s s4">415</span> <span class="s s5">503</span></p></section><section id="withdrawManifest"><h3><span class="v delete">DELETE</span> <code>/spatialdds/resolve</code></h3><p class="sum">Withdraw a manifest; <code>resolve</code> then answers 404 <span class="auth">token</span></p><p>Owner-checked by the URI&#x27;s scene segment. **Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>).</p><p class="codes"><span class="s s2">204</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">404</span> <span class="s s4">405</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="getAsset"><h3><span class="v get">GET</span> <code>/assets/{name}</code></h3><p class="sum">Asset bytes this endpoint hosts (implementation-defined) <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s4">404</span> <span class="s s4">429</span></p></section><section id="listAnnounce"><h3><span class="v get">GET</span> <code>/{scene}/{stream}/announce/v1</code></h3><p class="sum">Every spatial.disco.Announce instance in the latched set <span class="auth">open</span></p><p>**The same URL is also a WebSocket** (N.5): connect with <code>wss://</code> and receive the latched set as <code>sample</code> events, exactly one <code>end_of_replay</code> carrying the replay count, then live <code>sample</code> and <code>dispose</code> events (<code>{event, topic, key, data | reason}</code>). Not modelled here; see [Appendix N.5](https://spatialdds.org/v1.8/appendix-n/).</p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">404</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="commandAnnounce"><h3><span class="v post">POST</span> <code>/{scene}/{stream}/announce/v1</code></h3><p class="sum">An N.6 command addressed through the announce lane <span class="auth">token</span></p><p>Accepted only on a lane whose topic advertises <code>accepts_commands</code>; otherwise <code>405</code>. **Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). Every member of the record is required: a body is a whole record, never a patch.</p><p class="codes"><span class="s s2">202</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">405</span> <span class="s s4">409</span> <span class="s s4">429</span> <span class="s s4">413</span> <span class="s s4">415</span></p></section><section id="getAnnounce"><h3><span class="v get">GET</span> <code>/{scene}/{stream}/announce/v1/{key}</code></h3><p class="sum">One spatial.disco.Announce instance <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">404</span> <span class="s s4">429</span></p></section><section id="putAnnounce"><h3><span class="v put">PUT</span> <code>/{scene}/{stream}/announce/v1/{key}</code></h3><p class="sum">Publish or replace a spatial.disco.Announce <span class="auth">token</span></p><p>**Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). Every member of the record is required: a body is a whole record, never a patch. The body&#x27;s key must equal the URL&#x27;s. <code>If-Match</code> is honoured when present.</p><p class="codes"><span class="s s2">200</span> <span class="s s2">201</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">405</span> <span class="s s4">412</span> <span class="s s4">429</span> <span class="s s4">413</span> <span class="s s4">415</span> <span class="s s5">503</span></p></section><section id="withdrawAnnounce"><h3><span class="v delete">DELETE</span> <code>/{scene}/{stream}/announce/v1/{key}</code></h3><p class="sum">Withdraw (dispose) a spatial.disco.Announce <span class="auth">token</span></p><p>**Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). The dispose streams on the collection&#x27;s WebSocket with its <code>reason</code>.</p><p class="codes"><span class="s s2">204</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">404</span> <span class="s s4">405</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="listContentAnnounce"><h3><span class="v get">GET</span> <code>/{scene}/{stream}/content_announce/v1</code></h3><p class="sum">Every spatial.disco.ContentAnnounce instance in the latched set <span class="auth">open</span></p><p>**The same URL is also a WebSocket** (N.5): connect with <code>wss://</code> and receive the latched set as <code>sample</code> events, exactly one <code>end_of_replay</code> carrying the replay count, then live <code>sample</code> and <code>dispose</code> events (<code>{event, topic, key, data | reason}</code>). Not modelled here; see [Appendix N.5](https://spatialdds.org/v1.8/appendix-n/).</p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">404</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="commandContentAnnounce"><h3><span class="v post">POST</span> <code>/{scene}/{stream}/content_announce/v1</code></h3><p class="sum">An N.6 command addressed through the content_announce lane <span class="auth">token</span></p><p>Accepted only on a lane whose topic advertises <code>accepts_commands</code>; otherwise <code>405</code>. **Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). Every member of the record is required: a body is a whole record, never a patch.</p><p class="codes"><span class="s s2">202</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">405</span> <span class="s s4">409</span> <span class="s s4">429</span> <span class="s s4">413</span> <span class="s s4">415</span></p></section><section id="getContentAnnounce"><h3><span class="v get">GET</span> <code>/{scene}/{stream}/content_announce/v1/{key}</code></h3><p class="sum">One spatial.disco.ContentAnnounce instance <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">404</span> <span class="s s4">429</span></p></section><section id="putContentAnnounce"><h3><span class="v put">PUT</span> <code>/{scene}/{stream}/content_announce/v1/{key}</code></h3><p class="sum">Publish or replace a spatial.disco.ContentAnnounce <span class="auth">token</span></p><p>**Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). Every member of the record is required: a body is a whole record, never a patch. The body&#x27;s key must equal the URL&#x27;s. <code>If-Match</code> is honoured when present.</p><p class="codes"><span class="s s2">200</span> <span class="s s2">201</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">405</span> <span class="s s4">412</span> <span class="s s4">429</span> <span class="s s4">413</span> <span class="s s4">415</span> <span class="s s5">503</span></p></section><section id="withdrawContentAnnounce"><h3><span class="v delete">DELETE</span> <code>/{scene}/{stream}/content_announce/v1/{key}</code></h3><p class="sum">Withdraw (dispose) a spatial.disco.ContentAnnounce <span class="auth">token</span></p><p>**Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). The dispose streams on the collection&#x27;s WebSocket with its <code>reason</code>.</p><p class="codes"><span class="s s2">204</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">404</span> <span class="s s4">405</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="listEntity"><h3><span class="v get">GET</span> <code>/{scene}/{stream}/entity/v1</code></h3><p class="sum">Every spatial.owm.Entity instance in the latched set <span class="auth">token</span></p><p>**The same URL is also a WebSocket** (N.5): connect with <code>wss://</code> and receive the latched set as <code>sample</code> events, exactly one <code>end_of_replay</code> carrying the replay count, then live <code>sample</code> and <code>dispose</code> events (<code>{event, topic, key, data | reason}</code>). Not modelled here; see [Appendix N.5](https://spatialdds.org/v1.8/appendix-n/).</p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">404</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="commandEntity"><h3><span class="v post">POST</span> <code>/{scene}/{stream}/entity/v1</code></h3><p class="sum">An N.6 command addressed through the entity lane <span class="auth">token</span></p><p>Accepted only on a lane whose topic advertises <code>accepts_commands</code>; otherwise <code>405</code>. **Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). Every member of the record is required: a body is a whole record, never a patch.</p><p class="codes"><span class="s s2">202</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">405</span> <span class="s s4">409</span> <span class="s s4">429</span> <span class="s s4">413</span> <span class="s s4">415</span></p></section><section id="getEntity"><h3><span class="v get">GET</span> <code>/{scene}/{stream}/entity/v1/{key}</code></h3><p class="sum">One spatial.owm.Entity instance <span class="auth">token</span></p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">404</span> <span class="s s4">429</span></p></section><section id="putEntity"><h3><span class="v put">PUT</span> <code>/{scene}/{stream}/entity/v1/{key}</code></h3><p class="sum">Publish or replace a spatial.owm.Entity <span class="auth">token</span></p><p>**Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). Every member of the record is required: a body is a whole record, never a patch. The body&#x27;s key must equal the URL&#x27;s. <code>If-Match</code> is honoured when present. **Basis gates liveliness.** A DECLARED or AUTHORED body is a declaration and holds until withdrawn; it takes no <code>refresh</code>. An DERIVED or OBSERVED body must declare <code>refresh</code>, and be PUT again within it; when it lapses the gateway withdraws the instance itself, a terminal sample (RETIRED) then the dispose, both with the reason <code>refresh lapsed</code>. On a gateway with a DDS domain the instance is written there too, from the gateway&#x27;s own participant.</p><p class="codes"><span class="s s2">200</span> <span class="s s2">201</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">405</span> <span class="s s4">412</span> <span class="s s5">503</span> <span class="s s4">429</span> <span class="s s4">413</span> <span class="s s4">415</span></p></section><section id="withdrawEntity"><h3><span class="v delete">DELETE</span> <code>/{scene}/{stream}/entity/v1/{key}</code></h3><p class="sum">Withdraw (dispose) a spatial.owm.Entity <span class="auth">token</span></p><p>**Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). A terminal sample (RETIRED, with the reason) streams first, then the dispose with its <code>reason</code>, on the collection&#x27;s WebSocket and, on a gateway with a DDS domain, on the bus.</p><p class="codes"><span class="s s2">204</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">404</span> <span class="s s4">405</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="listGeoAnchor"><h3><span class="v get">GET</span> <code>/{scene}/{stream}/geo_anchor/v1</code></h3><p class="sum">Every spatial.core.GeoAnchor instance in the latched set <span class="auth">open</span></p><p>**The same URL is also a WebSocket** (N.5): connect with <code>wss://</code> and receive the latched set as <code>sample</code> events, exactly one <code>end_of_replay</code> carrying the replay count, then live <code>sample</code> and <code>dispose</code> events (<code>{event, topic, key, data | reason}</code>). Not modelled here; see [Appendix N.5](https://spatialdds.org/v1.8/appendix-n/).</p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">404</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="commandGeoAnchor"><h3><span class="v post">POST</span> <code>/{scene}/{stream}/geo_anchor/v1</code></h3><p class="sum">An N.6 command addressed through the geo_anchor lane <span class="auth">token</span></p><p>Accepted only on a lane whose topic advertises <code>accepts_commands</code>; otherwise <code>405</code>. **Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). Every member of the record is required: a body is a whole record, never a patch.</p><p class="codes"><span class="s s2">202</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">405</span> <span class="s s4">409</span> <span class="s s4">429</span> <span class="s s4">413</span> <span class="s s4">415</span></p></section><section id="getGeoAnchor"><h3><span class="v get">GET</span> <code>/{scene}/{stream}/geo_anchor/v1/{key}</code></h3><p class="sum">One spatial.core.GeoAnchor instance <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">404</span> <span class="s s4">429</span></p></section><section id="putGeoAnchor"><h3><span class="v put">PUT</span> <code>/{scene}/{stream}/geo_anchor/v1/{key}</code></h3><p class="sum">Publish or replace a spatial.core.GeoAnchor <span class="auth">token</span></p><p>**Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). Every member of the record is required: a body is a whole record, never a patch. The body&#x27;s key must equal the URL&#x27;s. <code>If-Match</code> is honoured when present.</p><p class="codes"><span class="s s2">200</span> <span class="s s2">201</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">405</span> <span class="s s4">412</span> <span class="s s4">429</span> <span class="s s4">413</span> <span class="s s4">415</span> <span class="s s5">503</span></p></section><section id="withdrawGeoAnchor"><h3><span class="v delete">DELETE</span> <code>/{scene}/{stream}/geo_anchor/v1/{key}</code></h3><p class="sum">Withdraw (dispose) a spatial.core.GeoAnchor <span class="auth">token</span></p><p>**Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). The dispose streams on the collection&#x27;s WebSocket with its <code>reason</code>.</p><p class="codes"><span class="s s2">204</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">404</span> <span class="s s4">405</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="listInstances"><h3><span class="v get">GET</span> <code>/{scene}/{stream}/{type}/{version}</code></h3><p class="sum">Any other served topic, read-only <span class="auth">token for operator-scoped</span></p><p>Latched types answer with the latched set; streamed types with the replayed window. Public or operator-scoped per the type: <code>spatial.core.FrameTransform</code> latched public, <code>spatial.events.CrossingLine</code> latched public, <code>spatial.events.SpatialEvent</code> stream bearer, <code>spatial.events.SpatialZone</code> latched public, <code>spatial.owm.ModelPose</code> stream bearer, <code>spatial.semantics.Detection2DSet</code> stream bearer, <code>spatial.semantics.Detection3DSet</code> stream bearer, <code>spatial.semantics.FusedTrackSet</code> stream bearer. **The same URL is also a WebSocket** (N.5): connect with <code>wss://</code> and receive the latched set as <code>sample</code> events, exactly one <code>end_of_replay</code> carrying the replay count, then live <code>sample</code> and <code>dispose</code> events (<code>{event, topic, key, data | reason}</code>). Not modelled here; see [Appendix N.5](https://spatialdds.org/v1.8/appendix-n/).</p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">401</span> <span class="s s4">404</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="listWellKnownInstances"><h3><span class="v get">GET</span> <code>/.well-known/spatialdds/{stream}/{type}/{version}</code></h3><p class="sum">A four-segment topic&#x27;s collection <span class="auth">token for operator-scoped</span></p><p>A four-segment topic (<code>spatialdds/&lt;stream&gt;/&lt;type&gt;/&lt;version&gt;</code>, no scene), such as the discovery announce lane, served exactly as a scene-scoped collection is: latched set, <code>ETag</code>, <code>304</code>, the same access classes, and the N.5 stream by upgrading the same path. Read-only: a topic with no scene is in no lane. **The same URL is also a WebSocket** (N.5): connect with <code>wss://</code> and receive the latched set as <code>sample</code> events, exactly one <code>end_of_replay</code> carrying the replay count, then live <code>sample</code> and <code>dispose</code> events (<code>{event, topic, key, data | reason}</code>). Not modelled here; see [Appendix N.5](https://spatialdds.org/v1.8/appendix-n/).</p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">401</span> <span class="s s4">404</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="getWellKnownInstance"><h3><span class="v get">GET</span> <code>/.well-known/spatialdds/{stream}/{type}/{version}/{key}</code></h3><p class="sum">One instance of a four-segment topic <span class="auth">token for operator-scoped</span></p><p>A four-segment topic (<code>spatialdds/&lt;stream&gt;/&lt;type&gt;/&lt;version&gt;</code>, no scene), such as the discovery announce lane, served exactly as a scene-scoped collection is: latched set, <code>ETag</code>, <code>304</code>, the same access classes, and the N.5 stream by upgrading the same path. Read-only: a topic with no scene is in no lane. </p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">401</span> <span class="s s4">404</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><h2>Schemas</h2><p class=mut>115 components, from the published JSON Schemas at <code>/.well-known/spatialdds/schemas</code>.</p></main></body></html>
+.s{margin-right:.5rem}.s4,.s5{color:#b5482c}a{color:var(--acc)}</style></head><body><main><h1>SpatialDDS web binding (spatialdds-py)</h1><p class=mut>Version 0.8.3 · OpenAPI 3.1.0 · generated, never hand-written · <a href='openapi'>openapi.yaml</a></p><p>Generated by <code>tools/gen_openapi.py</code> from the gateway&#x27;s own tables and the published JSON Schemas; never edited by hand. Reads are open; writes take a bearer token scoped to scenes. The WebSocket streams (N.5) are described on each collection path, not modelled. A deployment&#x27;s own keyed types (<code>serve --extension</code>) are publishable on their own collection paths, under the same rules as the entity lane when they carry <code>basis</code>, <code>state</code>, <code>state_reason</code> and <code>stamp</code>; a type that names an <code>asserter</code> has it stamped or verified as the bearer token&#x27;s principal (<code>asserter-not-principal</code>, <code>asserter-ungrounded</code>). Their paths are not listed here, because the deployment chooses them.</p><h2>Operations</h2><section id="search"><h3><span class="v get">GET</span> <code>/.well-known/spatialdds/search</code></h3><p class="sum">Services near a geohash (§8.2.3 manifests) <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s4">429</span></p></section><section id="searchPost"><h3><span class="v post">POST</span> <code>/.well-known/spatialdds/search</code></h3><p class="sum">The same search, as a POST body <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s4">429</span> <span class="s s4">413</span> <span class="s s4">415</span></p></section><section id="listSchemas"><h3><span class="v get">GET</span> <code>/.well-known/spatialdds/schemas</code></h3><p class="sum">The published JSON Schemas, by type <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s4">429</span></p></section><section id="getSchema"><h3><span class="v get">GET</span> <code>/.well-known/spatialdds/schemas/{type}</code></h3><p class="sum"> <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s4">404</span> <span class="s s4">429</span></p></section><section id="bootstrap"><h3><span class="v get">GET</span> <code>/.well-known/spatialdds/bootstrap</code></h3><p class="sum">DDS-join material (N.2); optional <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s4">404</span> <span class="s s4">429</span></p></section><section id="resolverMetadata"><h3><span class="v get">GET</span> <code>/.well-known/spatialdds/resolver</code></h3><p class="sum">§7.5.2 resolver metadata <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s4">404</span> <span class="s s4">429</span></p></section><section id="openapi"><h3><span class="v get">GET</span> <code>/.well-known/spatialdds/openapi</code></h3><p class="sum">This document <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s4">429</span></p></section><section id="openapiPage"><h3><span class="v get">GET</span> <code>/.well-known/spatialdds/openapi.html</code></h3><p class="sum">This document as a static reference page <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s4">429</span></p></section><section id="resolve"><h3><span class="v get">GET</span> <code>/spatialdds/resolve</code></h3><p class="sum">Resolve a URI to its manifest (§7.5.2) <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s4">400</span> <span class="s s4">404</span> <span class="s s4">429</span></p></section><section id="putManifest"><h3><span class="v put">PUT</span> <code>/spatialdds/resolve</code></h3><p class="sum">Publish a manifest, keyed by its own <code>id</code> <span class="auth">token</span></p><p>The <code>uri</code> parameter is not used; the body&#x27;s <code>id</code> is the key. Its scene segment is the lane. **Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>).</p><p class="codes"><span class="s s2">200</span> <span class="s s2">201</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">405</span> <span class="s s4">429</span> <span class="s s4">413</span> <span class="s s4">415</span> <span class="s s5">503</span></p></section><section id="withdrawManifest"><h3><span class="v delete">DELETE</span> <code>/spatialdds/resolve</code></h3><p class="sum">Withdraw a manifest; <code>resolve</code> then answers 404 <span class="auth">token</span></p><p>Owner-checked by the URI&#x27;s scene segment. **Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>).</p><p class="codes"><span class="s s2">204</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">404</span> <span class="s s4">405</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="getAsset"><h3><span class="v get">GET</span> <code>/assets/{name}</code></h3><p class="sum">Asset bytes this endpoint hosts (implementation-defined) <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s4">404</span> <span class="s s4">429</span></p></section><section id="listAnnounce"><h3><span class="v get">GET</span> <code>/{scene}/{stream}/announce/v1</code></h3><p class="sum">Every spatial.disco.Announce instance in the latched set <span class="auth">open</span></p><p>**The same URL is also a WebSocket** (N.5): connect with <code>wss://</code> and receive the latched set as <code>sample</code> events, exactly one <code>end_of_replay</code> carrying the replay count, then live <code>sample</code> and <code>dispose</code> events (<code>{event, topic, key, data | reason}</code>). Not modelled here; see [Appendix N.5](https://spatialdds.org/v1.8/appendix-n/).</p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">404</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="commandAnnounce"><h3><span class="v post">POST</span> <code>/{scene}/{stream}/announce/v1</code></h3><p class="sum">An N.6 command addressed through the announce lane <span class="auth">token</span></p><p>Accepted only on a lane whose topic advertises <code>accepts_commands</code>; otherwise <code>405</code>. **Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). Every member of the record is required: a body is a whole record, never a patch.</p><p class="codes"><span class="s s2">202</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">405</span> <span class="s s4">409</span> <span class="s s4">429</span> <span class="s s4">413</span> <span class="s s4">415</span></p></section><section id="getAnnounce"><h3><span class="v get">GET</span> <code>/{scene}/{stream}/announce/v1/{key}</code></h3><p class="sum">One spatial.disco.Announce instance <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">404</span> <span class="s s4">429</span></p></section><section id="putAnnounce"><h3><span class="v put">PUT</span> <code>/{scene}/{stream}/announce/v1/{key}</code></h3><p class="sum">Publish or replace a spatial.disco.Announce <span class="auth">token</span></p><p>**Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). Every member of the record is required: a body is a whole record, never a patch. The body&#x27;s key must equal the URL&#x27;s. <code>If-Match</code> is honoured when present.</p><p class="codes"><span class="s s2">200</span> <span class="s s2">201</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">405</span> <span class="s s4">412</span> <span class="s s4">429</span> <span class="s s4">413</span> <span class="s s4">415</span> <span class="s s5">503</span></p></section><section id="withdrawAnnounce"><h3><span class="v delete">DELETE</span> <code>/{scene}/{stream}/announce/v1/{key}</code></h3><p class="sum">Withdraw (dispose) a spatial.disco.Announce <span class="auth">token</span></p><p>**Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). The dispose streams on the collection&#x27;s WebSocket with its <code>reason</code>.</p><p class="codes"><span class="s s2">204</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">404</span> <span class="s s4">405</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="listContentAnnounce"><h3><span class="v get">GET</span> <code>/{scene}/{stream}/content_announce/v1</code></h3><p class="sum">Every spatial.disco.ContentAnnounce instance in the latched set <span class="auth">open</span></p><p>**The same URL is also a WebSocket** (N.5): connect with <code>wss://</code> and receive the latched set as <code>sample</code> events, exactly one <code>end_of_replay</code> carrying the replay count, then live <code>sample</code> and <code>dispose</code> events (<code>{event, topic, key, data | reason}</code>). Not modelled here; see [Appendix N.5](https://spatialdds.org/v1.8/appendix-n/).</p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">404</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="commandContentAnnounce"><h3><span class="v post">POST</span> <code>/{scene}/{stream}/content_announce/v1</code></h3><p class="sum">An N.6 command addressed through the content_announce lane <span class="auth">token</span></p><p>Accepted only on a lane whose topic advertises <code>accepts_commands</code>; otherwise <code>405</code>. **Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). Every member of the record is required: a body is a whole record, never a patch.</p><p class="codes"><span class="s s2">202</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">405</span> <span class="s s4">409</span> <span class="s s4">429</span> <span class="s s4">413</span> <span class="s s4">415</span></p></section><section id="getContentAnnounce"><h3><span class="v get">GET</span> <code>/{scene}/{stream}/content_announce/v1/{key}</code></h3><p class="sum">One spatial.disco.ContentAnnounce instance <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">404</span> <span class="s s4">429</span></p></section><section id="putContentAnnounce"><h3><span class="v put">PUT</span> <code>/{scene}/{stream}/content_announce/v1/{key}</code></h3><p class="sum">Publish or replace a spatial.disco.ContentAnnounce <span class="auth">token</span></p><p>**Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). Every member of the record is required: a body is a whole record, never a patch. The body&#x27;s key must equal the URL&#x27;s. <code>If-Match</code> is honoured when present.</p><p class="codes"><span class="s s2">200</span> <span class="s s2">201</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">405</span> <span class="s s4">412</span> <span class="s s4">429</span> <span class="s s4">413</span> <span class="s s4">415</span> <span class="s s5">503</span></p></section><section id="withdrawContentAnnounce"><h3><span class="v delete">DELETE</span> <code>/{scene}/{stream}/content_announce/v1/{key}</code></h3><p class="sum">Withdraw (dispose) a spatial.disco.ContentAnnounce <span class="auth">token</span></p><p>**Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). The dispose streams on the collection&#x27;s WebSocket with its <code>reason</code>.</p><p class="codes"><span class="s s2">204</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">404</span> <span class="s s4">405</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="listEntity"><h3><span class="v get">GET</span> <code>/{scene}/{stream}/entity/v1</code></h3><p class="sum">Every spatial.owm.Entity instance in the latched set <span class="auth">token</span></p><p>**The same URL is also a WebSocket** (N.5): connect with <code>wss://</code> and receive the latched set as <code>sample</code> events, exactly one <code>end_of_replay</code> carrying the replay count, then live <code>sample</code> and <code>dispose</code> events (<code>{event, topic, key, data | reason}</code>). Not modelled here; see [Appendix N.5](https://spatialdds.org/v1.8/appendix-n/).</p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">404</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="commandEntity"><h3><span class="v post">POST</span> <code>/{scene}/{stream}/entity/v1</code></h3><p class="sum">An N.6 command addressed through the entity lane <span class="auth">token</span></p><p>Accepted only on a lane whose topic advertises <code>accepts_commands</code>; otherwise <code>405</code>. **Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). Every member of the record is required: a body is a whole record, never a patch.</p><p class="codes"><span class="s s2">202</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">405</span> <span class="s s4">409</span> <span class="s s4">429</span> <span class="s s4">413</span> <span class="s s4">415</span></p></section><section id="getEntity"><h3><span class="v get">GET</span> <code>/{scene}/{stream}/entity/v1/{key}</code></h3><p class="sum">One spatial.owm.Entity instance <span class="auth">token</span></p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">404</span> <span class="s s4">429</span></p></section><section id="putEntity"><h3><span class="v put">PUT</span> <code>/{scene}/{stream}/entity/v1/{key}</code></h3><p class="sum">Publish or replace a spatial.owm.Entity <span class="auth">token</span></p><p>**Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). Every member of the record is required: a body is a whole record, never a patch. The body&#x27;s key must equal the URL&#x27;s. <code>If-Match</code> is honoured when present. **Basis gates liveliness.** A DECLARED or AUTHORED body is a declaration and holds until withdrawn; it takes no <code>refresh</code>. An DERIVED or OBSERVED body must declare <code>refresh</code>, and be PUT again within it; when it lapses the gateway withdraws the instance itself, a terminal sample (RETIRED) then the dispose, both with the reason <code>refresh lapsed</code>. On a gateway with a DDS domain the instance is written there too, from the gateway&#x27;s own participant.</p><p class="codes"><span class="s s2">200</span> <span class="s s2">201</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">405</span> <span class="s s4">412</span> <span class="s s5">503</span> <span class="s s4">429</span> <span class="s s4">413</span> <span class="s s4">415</span></p></section><section id="withdrawEntity"><h3><span class="v delete">DELETE</span> <code>/{scene}/{stream}/entity/v1/{key}</code></h3><p class="sum">Withdraw (dispose) a spatial.owm.Entity <span class="auth">token</span></p><p>**Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). A terminal sample (RETIRED, with the reason) streams first, then the dispose with its <code>reason</code>, on the collection&#x27;s WebSocket and, on a gateway with a DDS domain, on the bus.</p><p class="codes"><span class="s s2">204</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">404</span> <span class="s s4">405</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="listGeoAnchor"><h3><span class="v get">GET</span> <code>/{scene}/{stream}/geo_anchor/v1</code></h3><p class="sum">Every spatial.core.GeoAnchor instance in the latched set <span class="auth">open</span></p><p>**The same URL is also a WebSocket** (N.5): connect with <code>wss://</code> and receive the latched set as <code>sample</code> events, exactly one <code>end_of_replay</code> carrying the replay count, then live <code>sample</code> and <code>dispose</code> events (<code>{event, topic, key, data | reason}</code>). Not modelled here; see [Appendix N.5](https://spatialdds.org/v1.8/appendix-n/).</p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">404</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="commandGeoAnchor"><h3><span class="v post">POST</span> <code>/{scene}/{stream}/geo_anchor/v1</code></h3><p class="sum">An N.6 command addressed through the geo_anchor lane <span class="auth">token</span></p><p>Accepted only on a lane whose topic advertises <code>accepts_commands</code>; otherwise <code>405</code>. **Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). Every member of the record is required: a body is a whole record, never a patch.</p><p class="codes"><span class="s s2">202</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">405</span> <span class="s s4">409</span> <span class="s s4">429</span> <span class="s s4">413</span> <span class="s s4">415</span></p></section><section id="getGeoAnchor"><h3><span class="v get">GET</span> <code>/{scene}/{stream}/geo_anchor/v1/{key}</code></h3><p class="sum">One spatial.core.GeoAnchor instance <span class="auth">open</span></p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">404</span> <span class="s s4">429</span></p></section><section id="putGeoAnchor"><h3><span class="v put">PUT</span> <code>/{scene}/{stream}/geo_anchor/v1/{key}</code></h3><p class="sum">Publish or replace a spatial.core.GeoAnchor <span class="auth">token</span></p><p>**Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). Every member of the record is required: a body is a whole record, never a patch. The body&#x27;s key must equal the URL&#x27;s. <code>If-Match</code> is honoured when present.</p><p class="codes"><span class="s s2">200</span> <span class="s s2">201</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">405</span> <span class="s s4">412</span> <span class="s s4">429</span> <span class="s s4">413</span> <span class="s s4">415</span> <span class="s s5">503</span></p></section><section id="withdrawGeoAnchor"><h3><span class="v delete">DELETE</span> <code>/{scene}/{stream}/geo_anchor/v1/{key}</code></h3><p class="sum">Withdraw (dispose) a spatial.core.GeoAnchor <span class="auth">token</span></p><p>**Writes are per lane.** The path&#x27;s first segment is the scene; the bearer token must be granted it (<code>tenancy.WRITE_REFUSALS</code>). The dispose streams on the collection&#x27;s WebSocket with its <code>reason</code>.</p><p class="codes"><span class="s s2">204</span> <span class="s s4">400</span> <span class="s s4">401</span> <span class="s s4">403</span> <span class="s s4">404</span> <span class="s s4">405</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="listInstances"><h3><span class="v get">GET</span> <code>/{scene}/{stream}/{type}/{version}</code></h3><p class="sum">Any other served topic, read-only <span class="auth">token for operator-scoped</span></p><p>Latched types answer with the latched set; streamed types with the replayed window. Public or operator-scoped per the type: <code>spatial.core.FrameTransform</code> latched public, <code>spatial.events.CrossingLine</code> latched public, <code>spatial.events.SpatialEvent</code> stream bearer, <code>spatial.events.SpatialZone</code> latched public, <code>spatial.owm.ModelPose</code> stream bearer, <code>spatial.semantics.Detection2DSet</code> stream bearer, <code>spatial.semantics.Detection3DSet</code> stream bearer, <code>spatial.semantics.FusedTrackSet</code> stream bearer. **The same URL is also a WebSocket** (N.5): connect with <code>wss://</code> and receive the latched set as <code>sample</code> events, exactly one <code>end_of_replay</code> carrying the replay count, then live <code>sample</code> and <code>dispose</code> events (<code>{event, topic, key, data | reason}</code>). Not modelled here; see [Appendix N.5](https://spatialdds.org/v1.8/appendix-n/).</p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">401</span> <span class="s s4">404</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="listWellKnownInstances"><h3><span class="v get">GET</span> <code>/.well-known/spatialdds/{stream}/{type}/{version}</code></h3><p class="sum">A four-segment topic&#x27;s collection <span class="auth">token for operator-scoped</span></p><p>A four-segment topic (<code>spatialdds/&lt;stream&gt;/&lt;type&gt;/&lt;version&gt;</code>, no scene), such as the discovery announce lane, served exactly as a scene-scoped collection is: latched set, <code>ETag</code>, <code>304</code>, the same access classes, and the N.5 stream by upgrading the same path. Read-only: a topic with no scene is in no lane. **The same URL is also a WebSocket** (N.5): connect with <code>wss://</code> and receive the latched set as <code>sample</code> events, exactly one <code>end_of_replay</code> carrying the replay count, then live <code>sample</code> and <code>dispose</code> events (<code>{event, topic, key, data | reason}</code>). Not modelled here; see [Appendix N.5](https://spatialdds.org/v1.8/appendix-n/).</p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">401</span> <span class="s s4">404</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><section id="getWellKnownInstance"><h3><span class="v get">GET</span> <code>/.well-known/spatialdds/{stream}/{type}/{version}/{key}</code></h3><p class="sum">One instance of a four-segment topic <span class="auth">token for operator-scoped</span></p><p>A four-segment topic (<code>spatialdds/&lt;stream&gt;/&lt;type&gt;/&lt;version&gt;</code>, no scene), such as the discovery announce lane, served exactly as a scene-scoped collection is: latched set, <code>ETag</code>, <code>304</code>, the same access classes, and the N.5 stream by upgrading the same path. Read-only: a topic with no scene is in no lane. </p><p class="codes"><span class="s s2">200</span> <span class="s s3">304</span> <span class="s s4">401</span> <span class="s s4">404</span> <span class="s s4">429</span> <span class="s s5">503</span></p></section><h2>Schemas</h2><p class=mut>115 components, from the published JSON Schemas at <code>/.well-known/spatialdds/schemas</code>.</p></main></body></html>

{spatialdds-0.8.1 → spatialdds-0.8.3}/spatialdds/artifacts/openapi.yaml

@@ -2,7 +2,7 @@
 openapi: 3.1.0
 info:
   title: SpatialDDS web binding (spatialdds-py)
-  version: 0.8.1
+  version: 0.8.3
   summary: SpatialDDS 1.8 Appendix N over HTTPS, plus this endpoint's write surface.
   description: Generated by `tools/gen_openapi.py` from the gateway's own tables and the published JSON Schemas; never edited by hand. Reads are open; writes take a bearer token scoped to scenes. The WebSocket streams (N.5) are described on each collection path, not modelled. A deployment's own keyed types (`serve --extension`) are publishable on their own collection paths, under the same rules as the entity lane when they carry `basis`, `state`, `state_reason` and `stamp`; a type that names an `asserter` has it stamped or verified as the bearer token's principal (`asserter-not-principal`, `asserter-ungrounded`). Their paths are not listed here, because the deployment chooses them.
 servers:

{spatialdds-0.8.1 → spatialdds-0.8.3}/spatialdds/client.py

@@ -11,6 +11,7 @@ import hashlib
 import json
 import math
 import re
+import warnings
 from dataclasses import dataclass
 from typing import Any, Dict, Iterator, List, Optional
 
@@ -19,7 +20,7 @@ import requests
 from . import canonical, records
 from .errors import (IntegrityError, Problem, SpatialDDSError, Unreachable,
                      UnverifiableIntegrity, problem_for)
-from .errors import SurfaceOff, Unauthorized
+from .errors import AdvertisedOriginWarning, SurfaceOff, Unauthorized
 
 #: What the package's facade resolves through this module. The two exception
 #: subclasses are here because this is the module `spatialdds.Unauthorized`
@@ -29,11 +30,15 @@ __all__ = [
     "connect", "Endpoint", "Hit", "Topic", "Resolved", "Written",
     "Sample", "Dispose", "EndOfReplay", "Liveliness",
     "SpatialDDSError", "Unreachable", "Problem", "Unauthorized", "SurfaceOff",
-    "IntegrityError", "UnverifiableIntegrity", "lift",
+    "IntegrityError", "UnverifiableIntegrity", "AdvertisedOriginWarning",
+    "lift",
 ]
 
 
 WELL_KNOWN = "/.well-known/spatialdds"
+#: How many search pages `Endpoint.search` follows before it gives up
+#: rather than answer with part of the list.
+SEARCH_PAGES = 100
 _SHA256 = re.compile(r"^(?:sha256:)?([0-9a-f]{64})$", re.I)
 lift = canonical.lift
 
@@ -112,6 +117,7 @@ class Endpoint:
         self._cache: Dict[str, Any] = {}
         self._authority: Optional[str] = authority
         self._s = requests.Session()
+        self._origin_warned = False
 
     # -- plumbing --
     def _url(self, path_or_url: str) -> str:
@@ -124,6 +130,28 @@ class Endpoint:
         scheme, _, rest = url.partition("://")
         return f"{scheme.lower()}://{rest.split('/', 1)[0].lower()}"
 
+    def _advertised(self, url: str, where: str) -> None:
+        """Warn, once for this endpoint, if `url` is on another origin.
+
+        The URLs a service manifest or the resolver metadata advertise are
+        this endpoint's own, so their origin should be the one they were
+        read from. The library reads through `base` regardless (`_path_of`),
+        which is why a misadvertised endpoint read fine through it and
+        nowhere else (finding 83); this says so instead of hiding it.
+        """
+        if self._origin_warned or not url.startswith(("http://", "https://")):
+            return
+        here, there = _norm_origin(self.base), _norm_origin(url)
+        if here == there:
+            return
+        self._origin_warned = True
+        warnings.warn(AdvertisedOriginWarning(
+            f"{here} advertises {there} in its {where}, not the origin it "
+            f"was read from. This client reads through {here}; a client "
+            f"that follows the advertised URL reaches {there}. The endpoint "
+            f"is likely missing --public-url (or --authority)."),
+            stacklevel=3)
+
     def _headers(self, extra: Optional[Dict[str, str]] = None,
                  url: Optional[str] = None) -> Dict[str, str]:
         """Request headers; the token only for this endpoint's own origin.
@@ -245,16 +273,39 @@ class Endpoint:
 
     # -- discovery --
     def search(self, geohash: Optional[str] = None,
-               kinds: Optional[List[str]] = None) -> List["Hit"]:
-        """§3.3.0 search. One cell in, service manifests out."""
+               kinds: Optional[List[str]] = None,
+               max_pages: int = SEARCH_PAGES) -> List["Hit"]:
+        """§3.3.0 search. One cell in, service manifests out.
+
+        Every page: a response carrying a `next_page_token` is followed with
+        `page_token`, the same query each time, until one carries none. 0.8.2
+        and earlier read only the first page, so a paging endpoint's later
+        services were silently missing (finding 82). An endpoint still paging
+        after `max_pages` pages raises rather than answering with part of
+        the list.
+        """
         params: Dict[str, Any] = {}
         if geohash:
             params["geohash"] = geohash
         if kinds:
             params["kind"] = ",".join(kinds)
-        doc = self.get_json(f"{WELL_KNOWN}/search", params=params or None,
-                            revalidate=False)
-        return [Hit(self, m) for m in doc.get("results", [])]
+        hits: List["Hit"] = []
+        token = ""
+        for _ in range(max_pages):
+            page = dict(params, page_token=token) if token else params
+            doc = self.get_json(f"{WELL_KNOWN}/search", params=page or None,
+                                revalidate=False)
+            for m in doc.get("results", []):
+                for t in (m.get("service") or {}).get("topics") or []:
+                    if isinstance(t, dict) and t.get("url"):
+                        self._advertised(str(t["url"]), "search results")
+                hits.append(Hit(self, m))
+            token = doc.get("next_page_token") or ""
+            if not token:
+                return hits
+        raise SpatialDDSError(
+            f"{self.base}: search was still paging after {max_pages} pages "
+            f"({len(hits)} services read); pass max_pages= to read further")
 
     def near(self, lat: float, lon: float, radius_m: float) -> List["Hit"]:
         """Services whose declared coverage reaches a point.
@@ -287,6 +338,7 @@ class Endpoint:
             raise SpatialDDSError(
                 f"{self.base} publishes no resolver metadata, so it resolves "
                 f"nothing. It is not an authority for any spatialdds:// URI.")
+        self._advertised(str(hb), "resolver metadata")
         path = hb if hb.startswith(self.base) else self.base + _path_of(hb)
         r = self._request("GET", path, params={"uri": uri}, raw=True)
         return Resolved(self, uri, r.json(), r.headers.get("ETag", ""))
@@ -735,6 +787,16 @@ def _elements(cov: Any) -> List[Dict[str, Any]]:
 
 # ---- small helpers --------------------------------------------------------
 
+def _norm_origin(url: str) -> str:
+    """scheme://host[:port], lowercased, with a scheme's default port dropped."""
+    scheme, _, rest = url.partition("://")
+    scheme, host = scheme.lower(), rest.split("/", 1)[0].lower()
+    default = {"http": ":80", "https": ":443"}.get(scheme)
+    if default and host.endswith(default):
+        host = host[:-len(default)]
+    return f"{scheme}://{host}"
+
+
 def _path_of(url: str) -> str:
     if url.startswith(("http://", "https://")):
         rest = url.split("//", 1)[1]

{spatialdds-0.8.1 → spatialdds-0.8.3}/spatialdds/dds/_participant.py

@@ -75,6 +75,9 @@ DOMAIN_ENV = "SPATIALDDS_DDS_DOMAIN"
 #: program can make: a robot still exists after its bridge stops; a
 #: withdrawn catalogue item does not.
 ON_EXIT = ("keep", "withdraw")
+#: The most samples one `Reader.take()` takes from its DataReader; the rest
+#: wait for the next call (finding 76).
+TAKE_LIMIT = 256
 #: Message types whose well-known writers the participant owns: it announces
 #: and departs on a program's behalf, so a second writer would be a second
 #: claim about the same presence.
@@ -228,10 +231,10 @@ class Writer:
     """One lane's writer. Created by `Participant.writer`, never directly."""
 
     def __init__(self, p: "Participant", lane: _Lane, on_exit: Optional[str],
-                 floor_hz: Optional[float], validate: bool,
+                 floor_hz: Optional[float],
                  lifespan_sec: Optional[float]) -> None:
         self._p, self._lane = p, lane
-        self.on_exit, self.floor_hz, self.validate = on_exit, floor_hz, validate
+        self.on_exit, self.floor_hz = on_exit, floor_hz
         self._dw = DataWriter(p._dp, p._topic(lane),
                               qos=writer_qos(lane.profile, lifespan_sec))
         self._last: Dict[str, Any] = {}
@@ -286,13 +289,15 @@ class Writer:
     def write(self, sample: Any) -> Any:
         """Write a typed sample, or its N.1 document. Returns the typed sample.
 
-        Validated against the published schema first unless the writer was
-        made with `validate=False`; an invalid sample raises `SchemaInvalid`
-        and nothing reaches the bus.
+        Validated against the published schema first, always: an invalid
+        sample raises `SchemaInvalid` and nothing reaches the bus. There is
+        no unvalidated mode. 0.8.2 and earlier had one, `validate=False`,
+        because validation compiled the schema per sample (finding 75); it
+        is compiled once a type now, and an unvalidated write is a hole in
+        the write contract, not a fast path.
         """
         sample = self._coerce(sample)
-        if self.validate:
-            codec.validate(sample)
+        codec.validate(sample)
         key = codec.key_of(sample)
         with self._lock:
             self._dw.write(sample)
@@ -336,6 +341,12 @@ class Writer:
         its terminal state itself, and this wrote it again (S18). The members
         this method sets (`state`, `state_reason`, `stamp`) and the key are
         not changes a caller can make.
+
+        The terminal sample's `stamp` is this host's wall clock at the moment
+        of withdrawal, whatever clock the instance's other samples carried;
+        `on_exit="withdraw"` stamps the same way. A writer on another clock (a
+        simulator, a replay, a device with its own time base) cannot set it,
+        so its withdrawals read as happening at host time (finding 74).
         """
         if not isinstance(reason, str) or not reason.strip():
             raise ValueError("withdraw() needs a non-empty reason=: a removal "
@@ -343,8 +354,12 @@ class Writer:
         fixed = {"state", "state_reason", "stamp", codec.key_member(self._lane.fqn)}
         refused = sorted(set(changes) & fixed)
         if refused:
-            raise ValueError(f"withdraw() sets {', '.join(refused)} itself; "
-                             f"pass reason=, and the other members to change")
+            clock = (" (the terminal stamp is this host's wall clock at "
+                     "withdrawal, and a caller cannot set it)"
+                     if "stamp" in refused else "")
+            raise ValueError(f"withdraw() sets {', '.join(refused)} itself"
+                             f"{clock}; pass reason=, and the other members "
+                             f"to change")
         with self._lock:
             if key not in self._last:
                 raise KeyError(f"{self.topic} holds no instance keyed {key!r} "
@@ -357,7 +372,7 @@ class Writer:
                                  f"{', '.join(unknown)}")
             terminal = self._terminal(dataclasses.replace(last, **changes),
                                       reason)
-            if changes and self.validate:
+            if changes:
                 codec.validate(terminal)
             del self._last[key]
             # Immediately: nothing of this writer's may come between the
@@ -514,7 +529,7 @@ class Reader:
 
     def _events(self) -> List[Any]:
         out: List[Any] = []
-        for s in self._dr.take(N=256) or []:
+        for s in self._dr.take(N=TAKE_LIMIT) or []:
             info = getattr(s, "sample_info", None)
             if info is None:
                 continue
@@ -534,7 +549,14 @@ class Reader:
         return out
 
     def take(self) -> List[Any]:
-        """Every event that has arrived, now, without blocking.
+        """What has arrived, now, without blocking: up to 256 samples' events.
+
+        A call takes at most `TAKE_LIMIT` samples from the reader, and any
+        beyond that wait for the next call. Nothing in what it returns says
+        more are waiting, so a program whose lanes can deliver more than 256
+        samples between two calls should call `take()` again until it
+        returns no events (finding 76). `events()` keeps calling it and has
+        no such bound.
 
         For a program that already owns its loop: a tick, a framework's
         timer, a request handler. The events are the ones `events()` yields,
@@ -742,7 +764,7 @@ class Participant:
     def writer(self, type_: Union[str, type], *, stream: Optional[str] = None,
                qos_profile: Union[str, Profile, None] = None,
                on_exit: Optional[str] = None,
-               floor_hz: Optional[float] = None, validate: bool = True,
+               floor_hz: Optional[float] = None,
                version: str = "v1", type_name: Optional[str] = None,
                lifespan_sec: Optional[float] = None,
                topic: Optional[str] = None) -> Writer:
@@ -790,7 +812,7 @@ class Participant:
                         f"a writer does not offer a contract it will not meet")
         if problems:
             raise ParticipantRefused(problems)
-        w = Writer(self, lane, on_exit, floor_hz, validate, lifespan_sec)
+        w = Writer(self, lane, on_exit, floor_hz, lifespan_sec)
         self._writers.append(w)
         for sid, svc in self._services.items():
             if svc["spec"]["topics"] is None:

{spatialdds-0.8.1 → spatialdds-0.8.3}/spatialdds/dds/codec.py

@@ -363,7 +363,7 @@ def validate(sample: Any) -> Dict[str, Any]:
     check stops at the second: representable in N.1.
     """
     try:
-        import jsonschema
+        import jsonschema  # noqa: F401
     except ImportError as e:
         from ._extra import EXTRA, MissingExtra
         raise MissingExtra(f"validation needs jsonschema: {EXTRA}") from e
@@ -371,14 +371,16 @@ def validate(sample: Any) -> Dict[str, Any]:
     fqn = fqn_of(sample)
     if fqn in _EXT_FQN:
         return doc
-    schema = webjson.schemas().get(fqn)
-    if schema is None:
+    # Compiled once a type, a process (finding 75): a validated pose write
+    # cost 5-7 ms when this compiled the schema, and read every vendored
+    # schema from disk, per sample.
+    v = webjson.vendored_validator(fqn)
+    if v is None:
         raise SchemaInvalid(f"no published schema for {fqn}, so a sample "
-                            f"cannot be validated; pass validate=False to "
-                            f"write it unchecked")
-    try:
-        jsonschema.validate(doc, schema)
-    except jsonschema.ValidationError as e:
+                            f"cannot be validated, and nothing is written "
+                            f"unvalidated")
+    e = webjson.first_error(v, doc)
+    if e is not None:
         where = "/".join(str(p) for p in e.absolute_path) or "(root)"
         raise SchemaInvalid(f"{fqn} at {where}: {e.message}") from e
     return doc

{spatialdds-0.8.1 → spatialdds-0.8.3}/spatialdds/errors.py

@@ -85,3 +85,13 @@ def problem_for(status: int, doc: Dict[str, Any], url: str,
     if status == 405 and slug == "publish-disabled":
         return SurfaceOff(status, doc, url)
     return Problem(status, doc, url)
+
+
+class AdvertisedOriginWarning(UserWarning):
+    """An endpoint advertises URLs on an origin other than the one it was
+    read from (finding 83).
+
+    The library reads through the origin it connected to, so it works either
+    way; a client that follows the advertised URL, as N.3's hypermedia
+    intends, reaches the other origin. Warned once per endpoint, naming both.
+    """