spatialdds 0.2.0__tar.gz → 0.3.0__tar.gz

{spatialdds-0.2.0 → spatialdds-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatialdds
-Version: 0.2.0
+Version: 0.3.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
@@ -89,17 +89,62 @@ ep.publish_anchor("anchor/duck-perch", lat=30.2849, lon=-97.7393,
 first, then the record that points at it -- and return what `publish` returns,
 with the manifest's own result on `.manifest`.
 
+A full service contract is the same one call, with the claims stated:
+
+```python
+area = sd.circle(30.2849, -97.7393, 500)
+ep.publish_service(
+    service_id="mytown-vps", kind="VPS", coverage=area,
+    caps=sd.capabilities(
+        supported=[sd.profile("spatial.core", minor=8)],
+        features=["web-binding/json"]),
+    manifest=sd.service_manifest(
+        "mytown-vps", "VPS", authority=ep.authority, scene="mytown",
+        profiles=["Core", "AR+Geo"],
+        request={{"features_topic": "feat.keyframe"}},
+        response={{"minimal": "geo.fix"}},
+        limits={{"max_fps": 10}},
+        auth={{"scheme": "bearer", "issuer": "https://registry.mytown.example"}},
+        coverage=area, cells=sd.cells(area)))
+```
+
+Every one of those is something a service operator knows and a library cannot
+guess. [docs/MYTOWN.md](../../docs/MYTOWN.md) publishes that and prints the
+whole served document; `gates/builders.py` rebuilds this repository's
+hand-authored `austin-vps` and duck records through these calls and compares
+them member by member, which is what makes "every member is reachable from an
+argument" a check rather than a claim.
+
+**Two forms for an asset, because there are two situations.**
+`sd.asset(path_or_bytes, media_type=...)` reads the data and computes the hash
+and the byte count itself: a hash nobody typed is a hash a reader can trust.
+`sd.asset_ref(url, hash=..., media_type=...)` points at something somebody
+else hosts, and the hash comes from whoever has the bytes. Pass no hash and
+the reference carries no integrity claim, which costs a reader one thing:
+`fetch_asset()` raises rather than reporting a check it could not perform
+(finding 31). `publish_content` takes either, or a path, or bytes, or a URL.
+
 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.service_manifest`, `sd.content_announce`, `sd.content_manifest`,
+`sd.geo_anchor`, with `sd.circle`, `sd.bbox`, `sd.geopose`, `sd.cov_pos3`,
+`sd.cov_none`, `sd.profile`, `sd.capabilities`, `sd.asset_ref`,
 `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
+**Conventions fill plumbing. They never fill claims.** A stamp of now, an
+earth-fixed frame, a checksum computed from the record itself: plumbing, with
+one sensible value each, and filling them saves you writing out what you had
+no choice about. A profile list, a rate limit, a request topic, an auth
+scheme, a title: claims, and no default for any of them is honest. State
+nothing and you publish a minimal record, which is *correct*; state a
+contract and you publish it in one call. There is nothing in between for a
+library to invent.
+
+**What they fill in, and what they refuse to.** The conventions above are
+documented where they are 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
@@ -160,7 +205,7 @@ the latched set is complete.
 ```python
 import spatialdds as sd
 ep = sd.connect("http://127.0.0.1:8787")
-svc = ep.search(geohash="9v6krc")[0]
+svc = next(h for h in ep.search(geohash="9v6krc") if h.serves("geo_anchor"))
 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"])
@@ -227,6 +272,7 @@ call goes away and the bar is one line.
 | `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.serves(type_name)` | does this service offer a topic of that type? for picking one out of a search result |
 | `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 |
@@ -236,6 +282,9 @@ call goes away and the bar is one line.
 | `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.service_manifest(service_id, kind, authority=, scene=, profiles=, request=, response=, limits=, auth=, coverage=, cells=)` | the contract behind an announce; every member a claim, so every member an argument |
+| `sd.capabilities(supported=, preferred=, features=)`, `sd.profile(name, minor=)` | what a service supports, for `service_announce(caps=)` |
+| `sd.asset(path_or_bytes, media_type=)` / `sd.asset_ref(url, hash=, media_type=)` | an asset hashed from its bytes, or a reference to one hosted elsewhere |
 | `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 |
@@ -281,12 +330,18 @@ 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
+## Not in 0.3.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.
 
+`sd.asset` changed meaning in 0.3.0, which is why the version moved: it now
+reads bytes and computes a hash, where in 0.2.0 it took a URL and a hash you
+supplied. That second form is `sd.asset_ref`. A published release has to stay
+reproducible from a public commit, so the API could not change under the same
+number.
+
 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),

{spatialdds-0.2.0 → spatialdds-0.3.0}/README.md

@@ -65,17 +65,62 @@ ep.publish_anchor("anchor/duck-perch", lat=30.2849, lon=-97.7393,
 first, then the record that points at it -- and return what `publish` returns,
 with the manifest's own result on `.manifest`.
 
+A full service contract is the same one call, with the claims stated:
+
+```python
+area = sd.circle(30.2849, -97.7393, 500)
+ep.publish_service(
+    service_id="mytown-vps", kind="VPS", coverage=area,
+    caps=sd.capabilities(
+        supported=[sd.profile("spatial.core", minor=8)],
+        features=["web-binding/json"]),
+    manifest=sd.service_manifest(
+        "mytown-vps", "VPS", authority=ep.authority, scene="mytown",
+        profiles=["Core", "AR+Geo"],
+        request={{"features_topic": "feat.keyframe"}},
+        response={{"minimal": "geo.fix"}},
+        limits={{"max_fps": 10}},
+        auth={{"scheme": "bearer", "issuer": "https://registry.mytown.example"}},
+        coverage=area, cells=sd.cells(area)))
+```
+
+Every one of those is something a service operator knows and a library cannot
+guess. [docs/MYTOWN.md](../../docs/MYTOWN.md) publishes that and prints the
+whole served document; `gates/builders.py` rebuilds this repository's
+hand-authored `austin-vps` and duck records through these calls and compares
+them member by member, which is what makes "every member is reachable from an
+argument" a check rather than a claim.
+
+**Two forms for an asset, because there are two situations.**
+`sd.asset(path_or_bytes, media_type=...)` reads the data and computes the hash
+and the byte count itself: a hash nobody typed is a hash a reader can trust.
+`sd.asset_ref(url, hash=..., media_type=...)` points at something somebody
+else hosts, and the hash comes from whoever has the bytes. Pass no hash and
+the reference carries no integrity claim, which costs a reader one thing:
+`fetch_asset()` raises rather than reporting a check it could not perform
+(finding 31). `publish_content` takes either, or a path, or bytes, or a URL.
+
 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.service_manifest`, `sd.content_announce`, `sd.content_manifest`,
+`sd.geo_anchor`, with `sd.circle`, `sd.bbox`, `sd.geopose`, `sd.cov_pos3`,
+`sd.cov_none`, `sd.profile`, `sd.capabilities`, `sd.asset_ref`,
 `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
+**Conventions fill plumbing. They never fill claims.** A stamp of now, an
+earth-fixed frame, a checksum computed from the record itself: plumbing, with
+one sensible value each, and filling them saves you writing out what you had
+no choice about. A profile list, a rate limit, a request topic, an auth
+scheme, a title: claims, and no default for any of them is honest. State
+nothing and you publish a minimal record, which is *correct*; state a
+contract and you publish it in one call. There is nothing in between for a
+library to invent.
+
+**What they fill in, and what they refuse to.** The conventions above are
+documented where they are 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
@@ -136,7 +181,7 @@ the latched set is complete.
 ```python
 import spatialdds as sd
 ep = sd.connect("http://127.0.0.1:8787")
-svc = ep.search(geohash="9v6krc")[0]
+svc = next(h for h in ep.search(geohash="9v6krc") if h.serves("geo_anchor"))
 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"])
@@ -203,6 +248,7 @@ call goes away and the bar is one line.
 | `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.serves(type_name)` | does this service offer a topic of that type? for picking one out of a search result |
 | `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 |
@@ -212,6 +258,9 @@ call goes away and the bar is one line.
 | `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.service_manifest(service_id, kind, authority=, scene=, profiles=, request=, response=, limits=, auth=, coverage=, cells=)` | the contract behind an announce; every member a claim, so every member an argument |
+| `sd.capabilities(supported=, preferred=, features=)`, `sd.profile(name, minor=)` | what a service supports, for `service_announce(caps=)` |
+| `sd.asset(path_or_bytes, media_type=)` / `sd.asset_ref(url, hash=, media_type=)` | an asset hashed from its bytes, or a reference to one hosted elsewhere |
 | `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 |
@@ -257,12 +306,18 @@ 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
+## Not in 0.3.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.
 
+`sd.asset` changed meaning in 0.3.0, which is why the version moved: it now
+reads bytes and computes a hash, where in 0.2.0 it took a URL and a hash you
+supplied. That second form is `sd.asset_ref`. A published release has to stay
+reproducible from a public commit, so the API could not change under the same
+number.
+
 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),

{spatialdds-0.2.0 → spatialdds-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spatialdds"
-version = "0.2.0"
+version = "0.3.0"
 description = "SpatialDDS over plain HTTPS and a WebSocket: a client for the web binding (Appendix N), and the reference registry behind one command."
 readme = "README.md"
 requires-python = ">=3.9"

{spatialdds-0.2.0 → spatialdds-0.3.0}/spatialdds/__init__.py

@@ -8,7 +8,8 @@ can act on.
     import spatialdds as sd
 
     ep = sd.connect("https://demo.spatialdds.org")
-    svc = ep.search(geohash="9v6krc")[0]
+    svc = next(h for h in ep.search(geohash="9v6krc")
+               if h.serves("geo_anchor"))
     for a in svc.topic("geo_anchor").latched():
         print(a["anchor_id"], a["geopose"]["stamp"]["sec"])   # an int, not "17…"
 
@@ -30,12 +31,13 @@ __all__ = [
     # The record builders, re-exported so that `sd.circle(...)` reads the way
     # it does in the documentation. They live in `spatialdds.records`.
     "records", "circle", "bbox", "earth_fixed", "frame", "stamp", "geopose",
-    "cov_pos3", "cov_none", "topic", "asset", "cells",
-    "service_announce", "content_announce", "content_manifest", "geo_anchor",
-    "service_uri", "content_uri",
+    "cov_pos3", "cov_none", "topic", "asset", "asset_ref", "cells",
+    "profile", "capabilities",
+    "service_announce", "service_manifest", "content_announce",
+    "content_manifest", "geo_anchor", "service_uri", "content_uri",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 #: The SpatialDDS-spec commit whose Appendix N and generated artifacts this
 #: package implements. Package versions and specification versions move
 #: independently; this is the one that says what the wire looks like.

{spatialdds-0.2.0 → spatialdds-0.3.0}/spatialdds/client.py

@@ -329,9 +329,10 @@ class Endpoint:
     def publish_content(self, content_id: str, *,
                         position: Optional[Any] = None,
                         coverage: Any = None, radius_m: float = 10.0,
-                        asset: Optional[str] = None,
+                        asset: Any = None,
                         media_type: str = "application/octet-stream",
-                        sha256: str = "", assets: Any = None,
+                        sha256: str = "", asset_uri: str = "",
+                        assets: Any = None,
                         scene: Optional[str] = None,
                         stream: str = "content",
                         title: str = "", summary: str = "",
@@ -361,7 +362,8 @@ class Endpoint:
                 "position=(lat, lon) or coverage=sd.circle(...).")
         items = list(assets) if assets else []
         if asset is not None:
-            items.append(records.asset(asset, media_type, sha256=sha256))
+            items.append(self._asset_entry(asset, media_type, sha256,
+                                           asset_uri))
         man = records.content_manifest(
             content_id, authority=self.authority, scene=sc, assets=items,
             title=title, summary=summary, tags=tags, class_id=class_id,
@@ -377,6 +379,30 @@ class Endpoint:
         w.manifest = mw
         return w
 
+    def _asset_entry(self, asset: Any, media_type: str, sha256: str,
+                     asset_uri: str) -> Dict[str, Any]:
+        """Either asset form, from whatever the caller actually had.
+
+        A dict is used as it stands -- `sd.asset()` and `sd.asset_ref()`
+        return those. A URL becomes a reference, with whatever hash was
+        supplied. Bytes, or a path to a file that exists, are hashed from the
+        data: `sd.asset()` does that, and the URI defaults to this endpoint's
+        own asset route under the authority it advertises, which is where the
+        bytes will be if you put them there. Pass `asset_uri=` for anywhere
+        else.
+        """
+        if isinstance(asset, dict):
+            return asset
+        if isinstance(asset, str) and asset.startswith(("http://", "https://")):
+            return records.asset_ref(asset, media_type=media_type,
+                                     hash=sha256)
+        name = ""
+        if not isinstance(asset, (bytes, bytearray)):
+            name = str(asset).rsplit("/", 1)[-1]
+        uri = asset_uri or (f"https://{self.authority}/assets/{name}"
+                            if name else "")
+        return records.asset(asset, media_type=media_type, uri=uri)
+
     def publish_anchor(self, anchor_id: str, *, lat: float, lon: float,
                        method: str, alt_m: float = 0.0,
                        content: Optional[str] = None,
@@ -444,6 +470,18 @@ class Hit:
             f"{self.service_id or 'this service'} serves no {type_name!r} "
             f"topic; it offers: {have}")
 
+    def serves(self, type_name: str) -> bool:
+        """Does this service offer a topic of that type?
+
+        For picking a service out of a search result, which is what `search`
+        returns and what nobody should be indexing by position: the order is
+        the endpoint's, and it changes the moment somebody publishes another
+        service into the same cell. `search(...)[0]` on the front page read
+        the fountain's anchors until the page's own publish block ran, and
+        then read a VPS that serves none.
+        """
+        return any(t.get("type") == type_name for t in self.topics)
+
     def reaches(self, lat: float, lon: float, radius_m: float) -> bool:
         """Does the declared coverage come within `radius_m` of the point?"""
         return _coverage_reaches(self.coverage, lat, lon, radius_m)