spatialdds 0.7.1__tar.gz → 0.7.2__tar.gz

{spatialdds-0.7.1 → spatialdds-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatialdds
-Version: 0.7.1
+Version: 0.7.2
 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
@@ -152,6 +152,10 @@ scene:
   never speaks as the asserter.
 - **`sd.dds.class_for(name)`** is the generated class for a registered type
   name, a well-known message or a dotted identity.
+- **`sd.dds.extend(name, cls, idl)`** registers a deployment's own type, with
+  the IDL it was generated from. After that it converts, keys, records and
+  opens by name like a pinned type, and validation checks N.1
+  representability, since it has no published schema.
 
 `Sample.data` is the typed sample (`sd.dds.types` carries every type in the
 pinned IDL). `sd.dds.to_json(sample)` is its N.1 form, produced by the gateway's
@@ -594,6 +598,12 @@ explicitly was tried first and is what missed two paths.
 
 If your clients are not browsers, nothing here changes anything for you.
 
+## New in 0.7.2: a deployment's own types
+
+`sd.dds.extend(name, cls, idl)` brings a deployment's own documented type
+into the native layer: N.1 conversion, its key, `class_for`, the recording
+tap, and opening it by name. Additive, as 0.7.1 was.
+
 ## New in 0.7.1: for programs that own their loop
 
 Everything SpatialDDS-demo's adoption found missing, and nothing removed:
@@ -649,7 +659,7 @@ Two changes may need a line of yours:
 The security fixes, the limits table and the details are in the
 [changelog](https://github.com/OpenArCloud/spatialdds-py/blob/main/lib/spatialdds/CHANGELOG.md).
 
-## Not in 0.7.1
+## Not in 0.7.2
 
 Stated so nobody waits for them:
 

{spatialdds-0.7.1 → spatialdds-0.7.2}/README.md

@@ -124,6 +124,10 @@ scene:
   never speaks as the asserter.
 - **`sd.dds.class_for(name)`** is the generated class for a registered type
   name, a well-known message or a dotted identity.
+- **`sd.dds.extend(name, cls, idl)`** registers a deployment's own type, with
+  the IDL it was generated from. After that it converts, keys, records and
+  opens by name like a pinned type, and validation checks N.1
+  representability, since it has no published schema.
 
 `Sample.data` is the typed sample (`sd.dds.types` carries every type in the
 pinned IDL). `sd.dds.to_json(sample)` is its N.1 form, produced by the gateway's
@@ -566,6 +570,12 @@ explicitly was tried first and is what missed two paths.
 
 If your clients are not browsers, nothing here changes anything for you.
 
+## New in 0.7.2: a deployment's own types
+
+`sd.dds.extend(name, cls, idl)` brings a deployment's own documented type
+into the native layer: N.1 conversion, its key, `class_for`, the recording
+tap, and opening it by name. Additive, as 0.7.1 was.
+
 ## New in 0.7.1: for programs that own their loop
 
 Everything SpatialDDS-demo's adoption found missing, and nothing removed:
@@ -621,7 +631,7 @@ Two changes may need a line of yours:
 The security fixes, the limits table and the details are in the
 [changelog](https://github.com/OpenArCloud/spatialdds-py/blob/main/lib/spatialdds/CHANGELOG.md).
 
-## Not in 0.7.1
+## Not in 0.7.2
 
 Stated so nobody waits for them:
 

{spatialdds-0.7.1 → spatialdds-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spatialdds"
-version = "0.7.1"
+version = "0.7.2"
 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"

{spatialdds-0.7.1 → spatialdds-0.7.2}/spatialdds/__init__.py

@@ -41,7 +41,7 @@ __all__ = [
     "participant", "MissingExtra", "dds", "events", "frames", "Recency",
 ]
 
-__version__ = "0.7.1"
+__version__ = "0.7.2"
 #: 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.7.1 → spatialdds-0.7.2}/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.7.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.</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="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.Entity</code> latched bearer, <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.7.2 · 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.</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="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.Entity</code> latched bearer, <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.7.1 → spatialdds-0.7.2}/spatialdds/artifacts/openapi.yaml

@@ -2,7 +2,7 @@
 openapi: 3.1.0
 info:
   title: SpatialDDS web binding (spatialdds-py)
-  version: 0.7.1
+  version: 0.7.2
   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.
 servers:

{spatialdds-0.7.1 → spatialdds-0.7.2}/spatialdds/dds/__init__.py

@@ -29,7 +29,7 @@ __all__ = [
     "AnnounceRelay", "RELAYED_BY",
     "ON_EXIT", "DOMAIN_ENV",
     "to_json", "from_json", "validate", "SchemaInvalid", "fqn_of", "key_of",
-    "class_for",
+    "class_for", "extend", "Extension",
     "registry", "Profile", "RegistryError", "topic_name",
     "ANNOUNCE", "DEPART", "CONTENT", "QUERY", "COVERAGE_HINT",
     "Recorder", "chunk", "Reassembler", "CorruptChunk", "blob_ref",
@@ -51,7 +51,7 @@ _FROM = {
     "DOMAIN_ENV": "_participant",
     "to_json": "codec", "from_json": "codec", "validate": "codec",
     "SchemaInvalid": "codec", "fqn_of": "codec", "key_of": "codec",
-    "class_for": "codec",
+    "class_for": "codec", "extend": "codec", "Extension": "codec",
     "Profile": "registry", "RegistryError": "registry",
     "topic_name": "registry",
     "Recorder": "record",

{spatialdds-0.7.1 → spatialdds-0.7.2}/spatialdds/dds/_participant.py

@@ -131,10 +131,29 @@ class _Lane:
                             f"stream= would name a second one")
             return
         try:
+            if isinstance(type_, str) and type_ in codec.extensions():
+                # A deployment extension registered with `extend()`, by its
+                # name: the class is known, and the profile is still the
+                # caller's to give.
+                ext = codec.extensions()[type_]
+                if type_name not in (None, type_):
+                    problems.append(f"{type_} is registered as {type_}; "
+                                    f"type_name={type_name!r} would rename it")
+                    return
+                type_, type_name = ext.cls, type_
             if isinstance(type_, type):
                 # A deployment extension: its own generated class, a name per
                 # §3.3.2's pattern, and an explicit Profile.
                 self.cls, self.fqn = type_, codec.fqn_of(type_)
+                ext = codec.extension_of(self.fqn)
+                if ext is not None and ext.cls is not type_:
+                    ext = None
+                if ext is not None and type_name is None:
+                    type_name = ext.type_name
+                elif ext is not None and type_name != ext.type_name:
+                    problems.append(f"{type_.__name__} is registered as "
+                                    f"{ext.type_name}, not {type_name!r}")
+                    return
                 if not type_name:
                     problems.append(f"{type_.__name__} is an extension type: "
                                     f"pass type_name= (e.g. 'myorg.depth_frame')")

{spatialdds-0.7.1 → spatialdds-0.7.2}/spatialdds/dds/codec.py

@@ -23,12 +23,14 @@ from __future__ import annotations
 
 import re
 from functools import lru_cache
+from dataclasses import dataclass
 from typing import Any, Dict, Optional, Type, TypeVar
 
 from ..server import idlmodel, pin, webjson, xcdr2
 
 __all__ = ["to_json", "from_json", "fqn_of", "key_member", "key_of",
-           "validate", "SchemaInvalid", "model", "idl_order"]
+           "validate", "SchemaInvalid", "model", "idl_order", "class_for",
+           "extend", "Extension", "extensions", "extension_of"]
 
 T = TypeVar("T")
 
@@ -61,9 +63,146 @@ def model() -> idlmodel.Model:
     """The whole vendored IDL, through the gateway's parser."""
     m = idlmodel.parse(pin.flatten(pin.IDL_DIR, idl_order()))
     m._leaves = None
+    #: The pin's own types, before any `extend()` adds to this model. One
+    #: extension's IDL can define several types, so "in the model" is not
+    #: "pinned" once the first is registered.
+    m.pinned = frozenset(m.aggregates)
     return m
 
 
+@dataclass(frozen=True)
+class Extension:
+    """A deployment's own type, registered with `extend()`."""
+    type_name: str      # its §3.3.2-style name, namespaced: "oarc.fusion_coverage"
+    cls: type           # the generated class
+    fqn: str            # its dotted identity, "oarc_demo.FusionCoverage"
+    record: bytes       # the flattened IDL a recording embeds for it
+
+
+_EXT: Dict[str, Extension] = {}
+_EXT_FQN: Dict[str, Extension] = {}
+_EXT_NAME = re.compile(r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$")
+
+
+def extensions() -> Dict[str, Extension]:
+    """Every type registered with `extend()`, by name."""
+    return dict(_EXT)
+
+
+def extension_of(fqn: str) -> Optional[Extension]:
+    """The registered extension with this dotted identity, if there is one."""
+    return _EXT_FQN.get(fqn)
+
+
+def extend(type_name: str, cls: type, idl: Any) -> Extension:
+    """Teach this layer a deployment's own type, beside the pinned IDL.
+
+    A deployment's extension (§3.3.2 allows one, documented) is a type the
+    pinned IDL does not define. Until it is registered here, the native
+    layer can write it but cannot convert it to N.1 or back, find its key,
+    name its class, or record its schema. Registering it gives it all four:
+
+    * `to_json` / `from_json`, through the same gateway codec as every
+      pinned type;
+    * `key_of` from its own `@key`, so instances are tracked and `on_exit`
+      applies;
+    * `class_for(type_name)`, for a bridge that learns the type from an
+      announce;
+    * the recording tap embeds its IDL.
+
+    `idl` is the IDL text, or a path to it. It may `#include` only pinned
+    files, and its schema record is their closure, then its own body. It must
+    define the class's own type.
+
+    `validate()` cannot check an extension against a published schema,
+    because none exists. It checks that the sample is representable in N.1,
+    and says so.
+
+    Refused:
+
+    * a name without a namespace, which could collide with a future
+      registration;
+    * a registered name, or a well-known message;
+    * a pinned type;
+    * IDL that includes an unpinned file, or does not define the class;
+    * the same name again with different IDL or class.
+
+    Registering again with identical arguments is a no-op.
+    """
+    from pathlib import Path
+    from . import registry
+    problems = []
+    if type_name in registry.registrations() \
+            or type_name in registry.well_known():
+        problems.append(f"{type_name!r} is the spec's (§3.3.2 or a well-known "
+                        f"message): it needs no extension")
+    elif not isinstance(type_name, str) or not _EXT_NAME.match(type_name):
+        problems.append(f"extension name {type_name!r} must be namespaced, "
+                        f"lower-case segments joined by '.' (e.g. "
+                        f"'oarc.fusion_coverage'), so it cannot collide with a "
+                        f"name §3.3.2 registers later")
+    try:
+        fqn = fqn_of(cls)
+    except TypeError as e:
+        problems.append(str(e))
+        fqn = ""
+    if fqn and fqn in model().pinned:
+        problems.append(f"{fqn} is in the pinned IDL: use its registered name")
+    text = idl
+    if isinstance(idl, Path) or (isinstance(idl, str) and "\n" not in idl
+                                 and Path(idl).is_file()):
+        text = Path(idl).read_text()
+    if not isinstance(text, str) or not text.strip():
+        problems.append("idl= must be IDL text or a path to it")
+        text = ""
+    files: list = []
+    for inc in re.findall(r'^\s*#include\s+"([^"]+)"', text, re.M):
+        if not (pin.IDL_DIR / inc).is_file():
+            problems.append(f"the extension's IDL includes {inc!r}, which the "
+                            f"pinned IDL does not have")
+            continue
+        for f in pin.file_closure(inc):
+            if f not in files:
+                files.append(f)
+    if problems:
+        raise registry.RegistryError("; ".join(problems))
+    body = "\n".join(l for l in text.splitlines()
+                     if not l.lstrip().startswith("#"))
+    record = (pin.flatten(pin.IDL_DIR, files)
+              + f"\n// ---- extension {type_name} ----\n{body}").encode()
+    parsed = idlmodel.parse(record.decode())
+    if fqn not in parsed.aggregates:
+        raise registry.RegistryError(
+            f"the extension's IDL does not define {fqn}, the type "
+            f"{cls.__name__} says it is")
+    prior = _EXT.get(type_name) or _EXT_FQN.get(fqn)
+    if prior is not None:
+        if (prior.type_name, prior.cls, prior.record) == (type_name, cls, record):
+            return prior
+        raise registry.RegistryError(
+            f"{prior.type_name} ({prior.fqn}) is already registered, "
+            f"differently: one name, one type, one IDL")
+    m = model()
+    for k, v in parsed.aggregates.items():
+        m.aggregates.setdefault(k, v)
+    for k, v in parsed.typedefs.items():
+        m.typedefs.setdefault(k, v)
+    m._leaves = None
+    _codec.cache_clear()
+    key_member.cache_clear()
+    ext = Extension(type_name, cls, fqn, record)
+    _EXT[type_name] = _EXT_FQN[fqn] = ext
+    return ext
+
+
+def _known(fqn: str) -> None:
+    if fqn not in model().aggregates:
+        from . import registry
+        raise registry.RegistryError(
+            f"{fqn} is not in the pinned IDL: register a deployment's own type "
+            f"with sd.dds.extend(name, cls, idl) first")
+
+
 @lru_cache(maxsize=1)
 def _codec():
     m, tables = model(), webjson.tables()
@@ -94,6 +233,9 @@ def class_for(name: str) -> type:
     """
     import importlib
     from . import registry
+    ext = _EXT.get(name) or _EXT_FQN.get(name)
+    if ext is not None:
+        return ext.cls
     reg = registry.registrations().get(name)
     wk = registry.well_known() if name in registry.well_known() else None
     fqn = reg.fqn if reg else wk[name].fqn if wk else name
@@ -105,8 +247,9 @@ def class_for(name: str) -> type:
         except (ImportError, AttributeError):
             pass
     raise registry.RegistryError(
-        f"{name!r} is not a registered type name, a well-known message, or a "
-        f"dotted type identity in the pinned IDL")
+        f"{name!r} is not a registered type name, a well-known message, a "
+        f"dotted type identity in the pinned IDL, or an extension registered "
+        f"with extend()")
 
 
 def to_json(sample: Any) -> Dict[str, Any]:
@@ -118,8 +261,9 @@ def to_json(sample: Any) -> Dict[str, Any]:
     gateway's own canonical form, the one its ETags are computed from, so
     the refusal and a served document's digest are the same rule.
     """
-    dec, _w, proj, _l = _codec()
     fqn = fqn_of(sample)
+    _known(fqn)
+    dec, _w, proj, _l = _codec()
     doc = proj.project(fqn, dec.decode(fqn, sample.serialize()))
     try:
         webjson.canon(doc)
@@ -130,8 +274,9 @@ def to_json(sample: Any) -> Dict[str, Any]:
 
 def from_json(cls: Type[T], doc: Dict[str, Any]) -> T:
     """A typed sample from its N.1 document: the gateway's lift, encoded, decoded."""
-    _d, writer, _p, lifter = _codec()
     fqn = fqn_of(cls)
+    _known(fqn)
+    _d, writer, _p, lifter = _codec()
     return cls.deserialize(writer.encode(fqn, lifter.lift(fqn, doc)))
 
 
@@ -162,6 +307,9 @@ def validate(sample: Any) -> Dict[str, Any]:
     to serialize. One whose wire form N.1 cannot carry (a non-finite double)
     is `SchemaInvalid` from `to_json`. One whose N.1 form breaks its published
     schema is `SchemaInvalid` here.
+
+    An extension registered with `extend()` has no published schema, so its
+    check stops at the second: representable in N.1.
     """
     try:
         import jsonschema
@@ -170,6 +318,8 @@ def validate(sample: Any) -> Dict[str, Any]:
         raise MissingExtra(f"validation needs jsonschema: {EXTRA}") from e
     doc = to_json(sample)
     fqn = fqn_of(sample)
+    if fqn in _EXT_FQN:
+        return doc
     schema = webjson.schemas().get(fqn)
     if schema is None:
         raise SchemaInvalid(f"no published schema for {fqn}, so a sample "

{spatialdds-0.7.1 → spatialdds-0.7.2}/spatialdds/dds/record.py

@@ -39,6 +39,7 @@ except ImportError as e:                                      # pragma: no cover
     raise MissingExtra(f"the recording tap needs mcap: {EXTRA}") from e
 
 from ..server import mcapmeta, pin  # noqa: E402
+from . import codec  # noqa: E402
 
 __all__ = ["Recorder"]
 
@@ -73,7 +74,9 @@ class Recorder:
             if self._closed:
                 return
             if fqn not in self._schemas:
-                name, data = pin.schema_record(fqn.replace(".", "::"))
+                ext = codec.extension_of(fqn)
+                name, data = ((fqn.replace(".", "::"), ext.record) if ext
+                              else pin.schema_record(fqn.replace(".", "::")))
                 self._schemas[fqn] = self._w.register_schema(
                     name=name, encoding="omgidl", data=data)
             if topic not in self._channels:

{spatialdds-0.7.1 → spatialdds-0.7.2}/spatialdds.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatialdds
-Version: 0.7.1
+Version: 0.7.2
 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
@@ -152,6 +152,10 @@ scene:
   never speaks as the asserter.
 - **`sd.dds.class_for(name)`** is the generated class for a registered type
   name, a well-known message or a dotted identity.
+- **`sd.dds.extend(name, cls, idl)`** registers a deployment's own type, with
+  the IDL it was generated from. After that it converts, keys, records and
+  opens by name like a pinned type, and validation checks N.1
+  representability, since it has no published schema.
 
 `Sample.data` is the typed sample (`sd.dds.types` carries every type in the
 pinned IDL). `sd.dds.to_json(sample)` is its N.1 form, produced by the gateway's
@@ -594,6 +598,12 @@ explicitly was tried first and is what missed two paths.
 
 If your clients are not browsers, nothing here changes anything for you.
 
+## New in 0.7.2: a deployment's own types
+
+`sd.dds.extend(name, cls, idl)` brings a deployment's own documented type
+into the native layer: N.1 conversion, its key, `class_for`, the recording
+tap, and opening it by name. Additive, as 0.7.1 was.
+
 ## New in 0.7.1: for programs that own their loop
 
 Everything SpatialDDS-demo's adoption found missing, and nothing removed:
@@ -649,7 +659,7 @@ Two changes may need a line of yours:
 The security fixes, the limits table and the details are in the
 [changelog](https://github.com/OpenArCloud/spatialdds-py/blob/main/lib/spatialdds/CHANGELOG.md).
 
-## Not in 0.7.1
+## Not in 0.7.2
 
 Stated so nobody waits for them: