spatialdds 0.0.1__tar.gz → 0.2.0__tar.gz

spatialdds-0.2.0/PKG-INFO

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: spatialdds
+Version: 0.2.0
+Summary: SpatialDDS over plain HTTPS and a WebSocket: a client for the web binding (Appendix N), and the reference registry behind one command.
+Author: Open AR Cloud
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/OpenArCloud/spatialdds-web
+Project-URL: Specification, https://github.com/OpenArCloud/SpatialDDS-spec
+Keywords: spatialdds,spatial,geopose,anchors,registry,openarcloud
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25
+Requires-Dist: websockets>=12
+Provides-Extra: server
+Requires-Dist: aiohttp>=3.8; extra == "server"
+Requires-Dist: mcap>=1.1; extra == "server"
+Requires-Dist: jsonschema>=4.0; extra == "server"
+
+# spatialdds
+
+SpatialDDS over plain HTTPS and a WebSocket: a client for programs, and the
+reference registry behind one command.
+
+```sh
+pip install spatialdds                       # the client: two dependencies
+pip install "spatialdds[server]"             # and the registry
+pip install "./lib/spatialdds[server]"       # from a checkout of this repo
+```
+
+`fetch` and a WebSocket really are the whole client -- the endpoint's own
+README shows that in three lines of `curl`, and nothing here replaces it. This
+package is the step after that, when a program wants native values instead of
+canonical JSON, bytes it can trust, refusals it can act on, and records it did
+not have to assemble member by member.
+
+**Implements Appendix N as of SpatialDDS-spec `9c3e1f2`.** Package versions and
+specification versions move independently; `spatialdds.SPEC_COMMIT` is the one
+that says what the wire looks like.
+
+## Your own registry, in one command
+
+```sh
+python -m spatialdds.serve --authority registry.mytown.example --publish
+```
+
+That is a conformant SpatialDDS endpoint: empty, typed, and ready to be
+published into. Its types come from the IDL pinned inside this package at
+`SPEC_COMMIT`, so there is no base recording to find first -- the specification
+is the type source, and `spatialdds.server.pin` is where it lives. State goes
+to a journal (`./spatialdds-registry.mcap` by default, named in the banner)
+which is an ordinary SpatialDDS recording: restart replays it, and any tool
+that reads a recording can read your registry's state.
+
+`python -m spatialdds.serve --demo` serves the packaged fountain set instead --
+five surveyed anchors, two content manifests, the assets they name -- with
+publishing on and a token printed. Same boot path, seed data on top.
+
+The server half is an extra because being an endpoint is the part you opt
+into: `aiohttp` serves it, `mcap` is the journal, `jsonschema` validates every
+published body before it reaches the wire. Reading somebody else's registry
+needs none of them.
+
+## Publishing without writing out eighteen members
+
+Appendix N's schemas make every member of a record required, so an `Announce`
+is eighteen members, a `ContentAnnounce` sixteen, a `GeoAnchor` nine. The
+builders take the arguments you actually have:
+
+```python
+import spatialdds as sd
+
+ep = sd.connect("http://127.0.0.1:8787", token="tok", scene="mytown")
+ep.publish_service(service_id="mytown-vps", kind="VPS",
+                   coverage=sd.circle(30.2849, -97.7393, 500))
+ep.publish_content(content_id="duck", title="Duck", position=(30.2849, -97.7393),
+                   asset="https://cdn.example/duck.gltf", sha256=digest)
+ep.publish_anchor("anchor/duck-perch", lat=30.2849, lon=-97.7393,
+                  method="VisualFix", sigma_enu_m=(0.25, 0.25, 0.5),
+                  content="duck")
+```
+
+`publish_service` and `publish_content` are two PUTs each -- the manifest
+first, then the record that points at it -- and return what `publish` returns,
+with the manifest's own result on `.manifest`.
+
+The builders are also usable on their own: `sd.service_announce`,
+`sd.content_announce`, `sd.content_manifest`, `sd.geo_anchor`, with
+`sd.circle`, `sd.bbox`, `sd.geopose`, `sd.cov_pos3`, `sd.cov_none`,
+`sd.frame`,
+`sd.earth_fixed`, `sd.stamp`, `sd.topic`, `sd.asset`, `sd.cells`,
+`sd.service_uri` and `sd.content_uri`. Each returns a plain dict in canonical
+form, publishable as it stands and dumpable as the authoring JSON this
+repository's tools read. `spatialdds.records` is the module they live in.
+
+**What they fill in, and what they refuse to.** Three conventions, each
+documented where it is applied: a stamp of now unless you pass `when=`, an
+earth-fixed frame unless you pass one, and URIs assembled under a stated
+authority -- never a guessed one. `ep.publish_*` gets the authority from the
+endpoint itself (`ep.authority`, which asks the resolver metadata, then the
+endpoint's own 404 document at `/`, then the address you connected to). What
+they never fill is **identity**: `provider_id` and `org` are yours to state,
+because a library that invented a provider id would be inventing provenance.
+
+`GeoAnchor.checksum` is required by 1.8 and specified by nobody
+(spatialdds-web finding 31). The builder fills it with the SHA-256 of the
+record's own canonical JSON with `checksum` emptied -- a convention, chosen
+because a reader can recompute it from what was served. If the specification
+settles the semantics, this changes.
+
+The full map of builder argument to IDL member, including every member filled
+by convention, is printed by `python3 gates/builders.py --census` in the
+repository.
+
+## What it is for: the lift
+
+An endpoint serves Appendix N.1 canonical JSON, and three rules separate that
+from the values a program wants. All three are easy to get subtly wrong:
+
+* `int64` and `uint64` are **unconditional decimal strings**. A client that
+  treats `stamp.sec` as a string gets surprising comparisons; one that calls
+  `int()` on every string corrupts identifiers.
+* An octet run is **base64**.
+* A union is tagged on `"type"`, and carries `_discriminator` once lifted.
+
+These are not this library's rules -- they are the reference gateway's, and
+the repository gates that the two agree by lifting every record in both
+committed recordings with each implementation and comparing. Same rules, same
+results, different source of the type information: the server reads the IDL,
+and a client reading a remote endpoint has none, so this reads the generated
+serializer tables that travel with the package. That gate earned its keep on
+2026-10-15, when the disagreement it found turned out to be in the server.
+
+A lifted union keeps `_discriminator` rather than `"type"`, because that is
+what the lift produces and inventing a fourth shape would be a fourth rule.
+Pass `lifted=False` to `connect()` to get the canonical JSON untouched.
+
+## The three bars
+
+Each one runs on its own, pasted into a fresh shell with nothing else run
+first, which is why the serve line all three need is printed here rather than
+assumed. `gates/library.py` executes each bar against its own fresh endpoint
+and compares its output to what is printed below it.
+
+```sh
+python3 tools/run_gateway.py --mcap samples/fountain-anchors.mcap \
+  --manifests samples/manifests --assets samples/assets \
+  --publish --token not-a-secret --public-url https://demo.spatialdds.org
+```
+
+**Hello spatial, six lines.** Discover, subscribe, and read typed samples until
+the latched set is complete.
+
+<!-- bar: read -->
+```python
+import spatialdds as sd
+ep = sd.connect("http://127.0.0.1:8787")
+svc = ep.search(geohash="9v6krc")[0]
+for ev in svc.topic("geo_anchor").subscribe(timeout=10):
+    if isinstance(ev, sd.EndOfReplay): print("latched set complete:", ev.replayed); break
+    print(" ", ev.key, ev.data["method"], ev.data["geopose"]["stamp"]["sec"])
+```
+
+```console
+  anchor/fountain-north-rim Surveyed 1791559800
+  anchor/fountain-south-rim VisualFix 1791559800
+  anchor/fountain-east-rim VisualFix 1791559800
+  anchor/fountain-west-rim VisualFix 1791559800
+  anchor/fountain-plaque GNSS 1791559800
+latched set complete: 5
+```
+
+`geopose.stamp.sec` arrives as an `int` there, not as `"1791559800"`. That is
+the whole lift, in the one place a reader will notice it.
+
+**Publish the duck, four lines.** The content manifest, and the announce that
+places it.
+
+<!-- bar: publish -->
+```python
+import json, spatialdds as sd
+ep = sd.connect("http://127.0.0.1:8787", token="not-a-secret")
+d = json.load(open("samples/duck.input.json"))
+print("manifest", ep.publish_manifest(d["manifest"]).created, "| announce", ep.publish(topic=d["announce"]["path"], key=d["announce"]["key"], record=d["announce"]["record"]).created)
+```
+
+```console
+manifest True | announce True
+```
+
+**Resolve and verify, two lines.** The URI resolved per the endpoint's own
+§7.5.2 metadata, and the asset's bytes checked against the hash the manifest
+declared.
+
+<!-- bar: resolve -->
+```python
+import json, spatialdds as sd
+ep = sd.connect("http://127.0.0.1:8787", token="not-a-secret"); ep.publish_manifest(json.load(open("samples/duck.input.json"))["manifest"]); print(len(ep.resolve("spatialdds://demo.spatialdds.org/south-mall/content/duck").fetch_asset()), "bytes verified")
+```
+
+```console
+1432 bytes verified
+```
+
+The duck's manifest is published on the first line because these two lines
+have to stand alone. Against an endpoint that already holds the manifest, that
+call goes away and the bar is one line.
+
+## The surface
+
+| | |
+| --- | --- |
+| `sd.connect(base, token=None, verify_integrity=True, timeout=15.0, lifted=True, scene="default", authority=None)` | an `Endpoint`; nothing is fetched until you ask |
+| `ep.search(geohash=None, kinds=None)` | §3.3.0 search → a list of `Hit` |
+| `ep.near(lat, lon, radius_m)` | a helper over `search`, never a second protocol |
+| `ep.resolve(uri)` | §7.5.2 resolution → `Resolved` |
+| `ep.authority` | the DNS name the endpoint says it answers as |
+| `ep.publish(topic=, key=, record=, if_match=None)` | PUT one instance → `Written` |
+| `ep.publish_manifest(record)` | PUT a manifest, keyed by its own `id` |
+| `ep.publish_service(service_id=, kind=, coverage=, manifest=None, ...)` | build and PUT an announce, and its manifest if given |
+| `ep.publish_content(content_id=, position=, asset=, ...)` | build and PUT a content manifest and its announce |
+| `ep.publish_anchor(anchor_id, lat=, lon=, method=, content=None, ...)` | build and PUT an anchor, optionally naming content |
+| `ep.withdraw(topic=, key=)` | DELETE: leaves the latched set and disposes |
+| `hit.service_id`, `.kind`, `.coverage`, `.topics` | the typed service manifest |
+| `hit.topic(type_name)` | a `Topic`, URL taken from the manifest, never built |
+| `hit.reaches(lat, lon, radius_m)` | does the declared coverage reach a point |
+| `topic.type`, `.url`, `.name`, `.durability`, `.access`, `.fqn` | what the manifest said |
+| `topic.latched()` | every live instance, lifted |
+| `topic.instance(key)` | one instance, key percent-encoded per N.3 |
+| `topic.subscribe(timeout=None)` | a generator of `Sample` / `Dispose` / `EndOfReplay` / `Liveliness` |
+| `resolved.doc`, `.uri`, `.etag`, `.assets` | the resolved manifest |
+| `resolved.asset_url(i)`, `.fetch_asset(i)` | the URL it would fetch, and the verified bytes |
+| `written.doc`, `.etag`, `.created`, `.manifest` | what a publish returned |
+| `sd.records` | the builders, listed above |
+| `sd.lift(fqn, doc)` | the lift on its own, for JSON you already have |
+| `sd.SPEC_COMMIT`, `sd.APPENDIX_N`, `sd.__version__` | what this speaks |
+
+`ep.near()` picks a geohash precision whose cell covers the radius, encodes the
+centre and eight points around the query circle so the covering cells are found
+without neighbour arithmetic, searches each distinct cell, and filters the hits
+by their own declared coverage. Everything it sends is an ordinary §3.3.0
+geohash query.
+
+`topic.url` and `assets[].uri` are followed by different rules, deliberately. A
+topic URL comes out of a service manifest this endpoint served, so its path is
+this endpoint's and the library follows it by path -- which is what makes a
+registry advertising a DNS name usable from a laptop. An asset URI is an
+ordinary web URL that usually points somewhere else entirely, so it is fetched
+exactly as written; the one exception is an asset on the endpoint's own
+advertised authority, which is rebased onto the endpoint you are talking to.
+
+## Errors
+
+One family, built from the endpoint's own N.8 problem documents — `status`,
+`type`, `detail` carried, not re-invented. Everything below derives from
+`SpatialDDSError`, so one `except` catches the lot.
+
+| | |
+| --- | --- |
+| `Unreachable` | the endpoint did not answer; names the URL and the serve line |
+| `Unauthorized` | 401; says to pass `token=` and where the token is printed |
+| `SurfaceOff` | 405 from a write verb; says to start with `--publish` |
+| `Problem` | any other refusal, with `.status`, `.type`, `.slug`, `.detail` |
+| `IntegrityError` | fetched bytes do not match the declared hash |
+| `UnverifiableIntegrity` | the declared value is not a hash this library can check |
+
+That last one is the unusual one and it is deliberate. SpatialDDS counts "a
+checksum field in the body" as a §7.5.2 integrity signal, but nothing specifies
+what such a field digests or in what form (spatialdds-web 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.
+
+## Integrity by default
+
+Latched reads revalidate with the ETag the endpoint gave; `fetch_asset` checks
+the bytes. Opting out exists and is loud: `verify_integrity=False`, at the call
+site, nowhere else.
+
+## Not in 0.2.0
+
+Stated so nobody waits for them: no async API, no caching beyond ETag
+revalidation, no retry policy, no MCAP tooling beyond the journal the server
+writes, and no DDS dependency of any kind. The wire is HTTP and a WebSocket.
+
+On the registry, four things are deferred rather than missing, and the same
+four are on the 1.9 candidates list: **leases** (nothing expires; `ttl_sec` is
+advice to caches), **per-provider scopes** (one token, one operator),
+**server-set identity** (`provider_id` is whatever the publisher says), and
+**upstream subscriptions** (a registry does not follow another registry).

spatialdds-0.2.0/README.md

@@ -0,0 +1,270 @@
+# spatialdds
+
+SpatialDDS over plain HTTPS and a WebSocket: a client for programs, and the
+reference registry behind one command.
+
+```sh
+pip install spatialdds                       # the client: two dependencies
+pip install "spatialdds[server]"             # and the registry
+pip install "./lib/spatialdds[server]"       # from a checkout of this repo
+```
+
+`fetch` and a WebSocket really are the whole client -- the endpoint's own
+README shows that in three lines of `curl`, and nothing here replaces it. This
+package is the step after that, when a program wants native values instead of
+canonical JSON, bytes it can trust, refusals it can act on, and records it did
+not have to assemble member by member.
+
+**Implements Appendix N as of SpatialDDS-spec `9c3e1f2`.** Package versions and
+specification versions move independently; `spatialdds.SPEC_COMMIT` is the one
+that says what the wire looks like.
+
+## Your own registry, in one command
+
+```sh
+python -m spatialdds.serve --authority registry.mytown.example --publish
+```
+
+That is a conformant SpatialDDS endpoint: empty, typed, and ready to be
+published into. Its types come from the IDL pinned inside this package at
+`SPEC_COMMIT`, so there is no base recording to find first -- the specification
+is the type source, and `spatialdds.server.pin` is where it lives. State goes
+to a journal (`./spatialdds-registry.mcap` by default, named in the banner)
+which is an ordinary SpatialDDS recording: restart replays it, and any tool
+that reads a recording can read your registry's state.
+
+`python -m spatialdds.serve --demo` serves the packaged fountain set instead --
+five surveyed anchors, two content manifests, the assets they name -- with
+publishing on and a token printed. Same boot path, seed data on top.
+
+The server half is an extra because being an endpoint is the part you opt
+into: `aiohttp` serves it, `mcap` is the journal, `jsonschema` validates every
+published body before it reaches the wire. Reading somebody else's registry
+needs none of them.
+
+## Publishing without writing out eighteen members
+
+Appendix N's schemas make every member of a record required, so an `Announce`
+is eighteen members, a `ContentAnnounce` sixteen, a `GeoAnchor` nine. The
+builders take the arguments you actually have:
+
+```python
+import spatialdds as sd
+
+ep = sd.connect("http://127.0.0.1:8787", token="tok", scene="mytown")
+ep.publish_service(service_id="mytown-vps", kind="VPS",
+                   coverage=sd.circle(30.2849, -97.7393, 500))
+ep.publish_content(content_id="duck", title="Duck", position=(30.2849, -97.7393),
+                   asset="https://cdn.example/duck.gltf", sha256=digest)
+ep.publish_anchor("anchor/duck-perch", lat=30.2849, lon=-97.7393,
+                  method="VisualFix", sigma_enu_m=(0.25, 0.25, 0.5),
+                  content="duck")
+```
+
+`publish_service` and `publish_content` are two PUTs each -- the manifest
+first, then the record that points at it -- and return what `publish` returns,
+with the manifest's own result on `.manifest`.
+
+The builders are also usable on their own: `sd.service_announce`,
+`sd.content_announce`, `sd.content_manifest`, `sd.geo_anchor`, with
+`sd.circle`, `sd.bbox`, `sd.geopose`, `sd.cov_pos3`, `sd.cov_none`,
+`sd.frame`,
+`sd.earth_fixed`, `sd.stamp`, `sd.topic`, `sd.asset`, `sd.cells`,
+`sd.service_uri` and `sd.content_uri`. Each returns a plain dict in canonical
+form, publishable as it stands and dumpable as the authoring JSON this
+repository's tools read. `spatialdds.records` is the module they live in.
+
+**What they fill in, and what they refuse to.** Three conventions, each
+documented where it is applied: a stamp of now unless you pass `when=`, an
+earth-fixed frame unless you pass one, and URIs assembled under a stated
+authority -- never a guessed one. `ep.publish_*` gets the authority from the
+endpoint itself (`ep.authority`, which asks the resolver metadata, then the
+endpoint's own 404 document at `/`, then the address you connected to). What
+they never fill is **identity**: `provider_id` and `org` are yours to state,
+because a library that invented a provider id would be inventing provenance.
+
+`GeoAnchor.checksum` is required by 1.8 and specified by nobody
+(spatialdds-web finding 31). The builder fills it with the SHA-256 of the
+record's own canonical JSON with `checksum` emptied -- a convention, chosen
+because a reader can recompute it from what was served. If the specification
+settles the semantics, this changes.
+
+The full map of builder argument to IDL member, including every member filled
+by convention, is printed by `python3 gates/builders.py --census` in the
+repository.
+
+## What it is for: the lift
+
+An endpoint serves Appendix N.1 canonical JSON, and three rules separate that
+from the values a program wants. All three are easy to get subtly wrong:
+
+* `int64` and `uint64` are **unconditional decimal strings**. A client that
+  treats `stamp.sec` as a string gets surprising comparisons; one that calls
+  `int()` on every string corrupts identifiers.
+* An octet run is **base64**.
+* A union is tagged on `"type"`, and carries `_discriminator` once lifted.
+
+These are not this library's rules -- they are the reference gateway's, and
+the repository gates that the two agree by lifting every record in both
+committed recordings with each implementation and comparing. Same rules, same
+results, different source of the type information: the server reads the IDL,
+and a client reading a remote endpoint has none, so this reads the generated
+serializer tables that travel with the package. That gate earned its keep on
+2026-10-15, when the disagreement it found turned out to be in the server.
+
+A lifted union keeps `_discriminator` rather than `"type"`, because that is
+what the lift produces and inventing a fourth shape would be a fourth rule.
+Pass `lifted=False` to `connect()` to get the canonical JSON untouched.
+
+## The three bars
+
+Each one runs on its own, pasted into a fresh shell with nothing else run
+first, which is why the serve line all three need is printed here rather than
+assumed. `gates/library.py` executes each bar against its own fresh endpoint
+and compares its output to what is printed below it.
+
+```sh
+python3 tools/run_gateway.py --mcap samples/fountain-anchors.mcap \
+  --manifests samples/manifests --assets samples/assets \
+  --publish --token not-a-secret --public-url https://demo.spatialdds.org
+```
+
+**Hello spatial, six lines.** Discover, subscribe, and read typed samples until
+the latched set is complete.
+
+<!-- bar: read -->
+```python
+import spatialdds as sd
+ep = sd.connect("http://127.0.0.1:8787")
+svc = ep.search(geohash="9v6krc")[0]
+for ev in svc.topic("geo_anchor").subscribe(timeout=10):
+    if isinstance(ev, sd.EndOfReplay): print("latched set complete:", ev.replayed); break
+    print(" ", ev.key, ev.data["method"], ev.data["geopose"]["stamp"]["sec"])
+```
+
+```console
+  anchor/fountain-north-rim Surveyed 1791559800
+  anchor/fountain-south-rim VisualFix 1791559800
+  anchor/fountain-east-rim VisualFix 1791559800
+  anchor/fountain-west-rim VisualFix 1791559800
+  anchor/fountain-plaque GNSS 1791559800
+latched set complete: 5
+```
+
+`geopose.stamp.sec` arrives as an `int` there, not as `"1791559800"`. That is
+the whole lift, in the one place a reader will notice it.
+
+**Publish the duck, four lines.** The content manifest, and the announce that
+places it.
+
+<!-- bar: publish -->
+```python
+import json, spatialdds as sd
+ep = sd.connect("http://127.0.0.1:8787", token="not-a-secret")
+d = json.load(open("samples/duck.input.json"))
+print("manifest", ep.publish_manifest(d["manifest"]).created, "| announce", ep.publish(topic=d["announce"]["path"], key=d["announce"]["key"], record=d["announce"]["record"]).created)
+```
+
+```console
+manifest True | announce True
+```
+
+**Resolve and verify, two lines.** The URI resolved per the endpoint's own
+§7.5.2 metadata, and the asset's bytes checked against the hash the manifest
+declared.
+
+<!-- bar: resolve -->
+```python
+import json, spatialdds as sd
+ep = sd.connect("http://127.0.0.1:8787", token="not-a-secret"); ep.publish_manifest(json.load(open("samples/duck.input.json"))["manifest"]); print(len(ep.resolve("spatialdds://demo.spatialdds.org/south-mall/content/duck").fetch_asset()), "bytes verified")
+```
+
+```console
+1432 bytes verified
+```
+
+The duck's manifest is published on the first line because these two lines
+have to stand alone. Against an endpoint that already holds the manifest, that
+call goes away and the bar is one line.
+
+## The surface
+
+| | |
+| --- | --- |
+| `sd.connect(base, token=None, verify_integrity=True, timeout=15.0, lifted=True, scene="default", authority=None)` | an `Endpoint`; nothing is fetched until you ask |
+| `ep.search(geohash=None, kinds=None)` | §3.3.0 search → a list of `Hit` |
+| `ep.near(lat, lon, radius_m)` | a helper over `search`, never a second protocol |
+| `ep.resolve(uri)` | §7.5.2 resolution → `Resolved` |
+| `ep.authority` | the DNS name the endpoint says it answers as |
+| `ep.publish(topic=, key=, record=, if_match=None)` | PUT one instance → `Written` |
+| `ep.publish_manifest(record)` | PUT a manifest, keyed by its own `id` |
+| `ep.publish_service(service_id=, kind=, coverage=, manifest=None, ...)` | build and PUT an announce, and its manifest if given |
+| `ep.publish_content(content_id=, position=, asset=, ...)` | build and PUT a content manifest and its announce |
+| `ep.publish_anchor(anchor_id, lat=, lon=, method=, content=None, ...)` | build and PUT an anchor, optionally naming content |
+| `ep.withdraw(topic=, key=)` | DELETE: leaves the latched set and disposes |
+| `hit.service_id`, `.kind`, `.coverage`, `.topics` | the typed service manifest |
+| `hit.topic(type_name)` | a `Topic`, URL taken from the manifest, never built |
+| `hit.reaches(lat, lon, radius_m)` | does the declared coverage reach a point |
+| `topic.type`, `.url`, `.name`, `.durability`, `.access`, `.fqn` | what the manifest said |
+| `topic.latched()` | every live instance, lifted |
+| `topic.instance(key)` | one instance, key percent-encoded per N.3 |
+| `topic.subscribe(timeout=None)` | a generator of `Sample` / `Dispose` / `EndOfReplay` / `Liveliness` |
+| `resolved.doc`, `.uri`, `.etag`, `.assets` | the resolved manifest |
+| `resolved.asset_url(i)`, `.fetch_asset(i)` | the URL it would fetch, and the verified bytes |
+| `written.doc`, `.etag`, `.created`, `.manifest` | what a publish returned |
+| `sd.records` | the builders, listed above |
+| `sd.lift(fqn, doc)` | the lift on its own, for JSON you already have |
+| `sd.SPEC_COMMIT`, `sd.APPENDIX_N`, `sd.__version__` | what this speaks |
+
+`ep.near()` picks a geohash precision whose cell covers the radius, encodes the
+centre and eight points around the query circle so the covering cells are found
+without neighbour arithmetic, searches each distinct cell, and filters the hits
+by their own declared coverage. Everything it sends is an ordinary §3.3.0
+geohash query.
+
+`topic.url` and `assets[].uri` are followed by different rules, deliberately. A
+topic URL comes out of a service manifest this endpoint served, so its path is
+this endpoint's and the library follows it by path -- which is what makes a
+registry advertising a DNS name usable from a laptop. An asset URI is an
+ordinary web URL that usually points somewhere else entirely, so it is fetched
+exactly as written; the one exception is an asset on the endpoint's own
+advertised authority, which is rebased onto the endpoint you are talking to.
+
+## Errors
+
+One family, built from the endpoint's own N.8 problem documents — `status`,
+`type`, `detail` carried, not re-invented. Everything below derives from
+`SpatialDDSError`, so one `except` catches the lot.
+
+| | |
+| --- | --- |
+| `Unreachable` | the endpoint did not answer; names the URL and the serve line |
+| `Unauthorized` | 401; says to pass `token=` and where the token is printed |
+| `SurfaceOff` | 405 from a write verb; says to start with `--publish` |
+| `Problem` | any other refusal, with `.status`, `.type`, `.slug`, `.detail` |
+| `IntegrityError` | fetched bytes do not match the declared hash |
+| `UnverifiableIntegrity` | the declared value is not a hash this library can check |
+
+That last one is the unusual one and it is deliberate. SpatialDDS counts "a
+checksum field in the body" as a §7.5.2 integrity signal, but nothing specifies
+what such a field digests or in what form (spatialdds-web 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.
+
+## Integrity by default
+
+Latched reads revalidate with the ETag the endpoint gave; `fetch_asset` checks
+the bytes. Opting out exists and is loud: `verify_integrity=False`, at the call
+site, nowhere else.
+
+## Not in 0.2.0
+
+Stated so nobody waits for them: no async API, no caching beyond ETag
+revalidation, no retry policy, no MCAP tooling beyond the journal the server
+writes, and no DDS dependency of any kind. The wire is HTTP and a WebSocket.
+
+On the registry, four things are deferred rather than missing, and the same
+four are on the 1.9 candidates list: **leases** (nothing expires; `ttl_sec` is
+advice to caches), **per-provider scopes** (one token, one operator),
+**server-set identity** (`provider_id` is whatever the publisher says), and
+**upstream subscriptions** (a registry does not follow another registry).

spatialdds-0.2.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spatialdds"
+version = "0.2.0"
+description = "SpatialDDS over plain HTTPS and a WebSocket: a client for the web binding (Appendix N), and the reference registry behind one command."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Open AR Cloud" }]
+keywords = ["spatialdds", "spatial", "geopose", "anchors", "registry", "openarcloud"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Scientific/Engineering :: GIS",
+]
+# Two, and no more, for reading and publishing. The wire is HTTP and a
+# WebSocket; anything else would be this library's opinion rather than the
+# binding's requirement.
+dependencies = ["requests>=2.25", "websockets>=12"]
+
+[project.optional-dependencies]
+# Being an endpoint is the part you opt into. aiohttp serves it, mcap is the
+# format a registry's state lives in, and jsonschema validates every published
+# body against the vendored schemas before it reaches the wire. That last one
+# is not optional in any useful sense: without it the write surface refuses
+# every publish with a 500 rather than accept something unvalidated, so
+# leaving it out of this group would ship a registry nobody can publish into.
+server = ["aiohttp>=3.8", "mcap>=1.1", "jsonschema>=4.0"]
+
+[project.scripts]
+spatialdds-serve = "spatialdds.serve:main"
+
+[project.urls]
+Homepage = "https://github.com/OpenArCloud/spatialdds-web"
+Specification = "https://github.com/OpenArCloud/SpatialDDS-spec"
+
+[tool.setuptools]
+packages = ["spatialdds", "spatialdds.server"]
+
+[tool.setuptools.package-data]
+# Everything vendored travels with the package, because the point of 0.2.0 is
+# that `pip install` is enough:
+#
+# * `artifacts/serializer_tables.json` -- what the lift reads, in both
+#   directions. A client has no recording to learn the types from.
+# * `artifacts/schemas/*.json` -- the 112 generated JSON Schemas. The endpoint
+#   publishes them and validates against them, and §8.4's third-party reader
+#   has nothing else to go on.
+# * `artifacts/idl/*.idl` -- the pinned IDL. A registry that starts empty
+#   boots its types from this; the tables cannot stand in because they carry
+#   no `@key`, so a keyed resource would have no instance names.
+# * `demo/**` -- the fountain set `--demo` serves. Byte-identical to the
+#   repository's `samples/` copy, which `tools/pack_demo.py` maintains and
+#   `gates/serve_demo.py` checks.
+spatialdds = [
+  "artifacts/serializer_tables.json",
+  "artifacts/schemas/*.json",
+  "artifacts/idl/*.idl",
+  "demo/*.mcap",
+  "demo/manifests/*.json",
+  "demo/assets/*",
+]