fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/identity/linked/compartment.py

@@ -0,0 +1,270 @@
+"""The schema.org face of a node: what it publishes for strangers, projected
+as JSON-LD and served read-only over the relay face's HTTP fallthrough.
+
+Three documents, each a projection of a signed event (fleetmesh_core
+.linked_data) and never a second source of truth:
+
+  GET /.well-known/fleetmesh/service.jsonld   the node's kind 11801 as a
+                                              schema:Service, floor from
+                                              its kind 10050
+  GET /.well-known/fleetmesh/blob/<sha256>.jsonld
+                                              one stored blob as a
+                                              schema:MediaObject
+  GET /.well-known/fleetmesh/standing.jsonld  the node's own tier, as this
+                                              node's accounts have it - an
+                                              Organization with one
+                                              PropertyValue, not a Review
+
+Nothing here is signed and nothing here goes on a relay: the signed thing
+is the event, this is a reading of it. A consumer that wants proof fetches
+the event. That is why JSON-LD does not ride inside events (see
+CONTRIBUTING, "linked data").
+
+Every answer carries `Cache-Control: no-store` and the id of the event it
+was read from in `X-Fleetmesh-Source`, so a reader can go and check. No
+POST, no query strings, unknown paths fall through to the rest of the face.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Callable, Mapping, Optional, cast
+
+from fleetmesh_core.storage import linked_data
+from fleetmesh_core.wire.interfaces import NostrEvent
+
+from node.compartment import stores as st
+from node.compartment import Command, Compartment, Need
+from node.transport import ws
+
+
+from .types import (
+    LinkedTotals,
+    LinkedState,
+    BlobFacts,
+)
+
+PREFIX = '/.well-known/fleetmesh/'
+CTYPE = 'application/ld+json'
+_SHA = re.compile(r'^[0-9a-f]{64}$')
+
+
+import dataclasses
+from node.channels import Channel, INFO
+from node.metrics import COUNTER, Metric
+from node.config.parameter import Parameter, ParamBlock
+
+
+@dataclasses.dataclass(frozen=True)
+class LinkedConfig(ParamBlock):
+    key = 'linked'
+    name = 'linked'
+    DERIVED: bool = False
+    PARAMS = (
+        Parameter(key='enabled', name='Linked Data Enabled', description='Whether JSON-LD schema.org projections are served', type=bool, default=True, tags=('linked', 'schema')),
+    )
+    enabled: bool = True
+
+
+class LinkedFace(Compartment):
+    """Mounted on the relay face's HTTP fallthrough, before nsite."""
+
+    name: str = 'linked'
+    optional: bool = False
+    requires: tuple[str, ...] = ('presence',)   # the kind 10050 it last published is the floor
+    uses: tuple[str, ...] = ()
+    reads: tuple[str, ...] = ()
+    live: tuple[str, ...] = ()
+    config_cls = LinkedConfig
+    CHANNELS = (
+        Channel('doc_served', 'JSON-LD document served', level=INFO, say='served JSON-LD {path}', tags=('linked', 'schema')),
+    )
+    METRICS = (
+        Metric(name='linked_docs_served', description='Times JSON-LD projections were served.', kind=COUNTER, counts='doc_served', tags=('linked', 'schema')),
+    )
+    NEEDS = (
+        Need('face'),
+        Need('blobs', 'stores.blobs'),
+        Need('descriptor'),
+        Need('presence'),
+        Need('ledger'),
+        Need('ks'),
+    )
+    COMMANDS = (
+        Command(
+            key='show',
+            name='Linked Data Status',
+            description='the projections this node serves and how often each was read',
+            tags=('linked', 'status'),
+            permission='linked/show',
+            run='state',
+            reply='paths and counts',
+        ),
+        Command(
+            key='service',
+            name='Service Document',
+            description="this node's descriptor as a schema:Service (JSON-LD)",
+            tags=('linked', 'service'),
+            permission='linked/service',
+            run='service_cmd',
+            reply='the document, or refused when no descriptor yet',
+        ),
+        Command(
+            key='standing',
+            name='Standing Document',
+            description="this node's own tier as a schema:Organization (JSON-LD)",
+            tags=('linked', 'standing'),
+            permission='linked/standing',
+            run='standing_cmd',
+            reply='the document, or refused when the ledger has nothing to say',
+        ),
+        Command(
+            key='blob',
+            name='Blob Document',
+            description='one stored blob as a schema:MediaObject (JSON-LD)',
+            tags=('linked', 'blob'),
+            parameters=(
+                Parameter(key='sha256', name='sha256', description='sha256 hex digest of blob', type=str, default='', required=True),
+            ),
+            permission='linked/blob',
+            run='blob_cmd',
+            reply='the document, or refused when the blob is not here',
+        ),
+    )
+    STORES = (
+        st.Store(key='served', description='linked data requests served by category',
+                 kind=st.COUNTERS, shape=LinkedTotals),
+    )
+
+    def __init__(self, node: Optional[Any] = None, face: Optional[Any] = None,
+                 blobs: Optional[Any] = None,
+                 descriptor: Optional[Callable[[], Optional[NostrEvent]]] = None,
+                 inbox: Optional[Callable[[], Optional[NostrEvent]]] = None,
+                 standing: Optional[Callable[[], Optional[Mapping[str, Any]]]] = None,
+                 clock: Optional[Callable[[], int]] = None,
+                 blossom_url: Optional[str] = None,
+                 presence: Optional[Any] = None,
+                 ledger: Optional[Any] = None,
+                 ks: Optional[Any] = None) -> None:
+        super().__init__(node, clock)
+        self.face = face
+        self.blobs = blobs
+        self._descriptor = descriptor or (lambda: None)
+        self._inbox: Optional[Callable[[], Optional[NostrEvent]]]
+        if inbox is not None:
+            self._inbox = inbox
+        elif presence is not None:
+            self._inbox = lambda: getattr(presence, 'last_inbox', None)
+        else:
+            self._inbox = None
+
+        self._standing: Optional[Callable[[], Optional[Mapping[str, Any]]]]
+        if standing is not None:
+            self._standing = standing
+        elif ledger is not None and ks is not None:
+            me = getattr(ks, 'node_pk', '')
+            self._standing = (lambda: cast(Optional[Mapping[str, Any]], ledger.tell(me))) if me else None
+        else:
+            self._standing = None
+
+        self.blossom_url = blossom_url if blossom_url is not None else getattr(node, 'blossom_url', None)
+        self.served: st.Counters
+
+    # ---- lifecycle ----------------------------------------------------------
+    def start(self) -> None:
+        if self.face is not None and hasattr(self.face, 'http_handlers'):
+            # First in line: fixed paths, cheap, never host-routed.
+            self.face.http_handlers.insert(0, self.handle_request)
+
+    def tick(self, now: int) -> list[tuple[Any, ...]]:
+        return []
+
+    def state(self) -> LinkedState:
+        return {'served': dict(self.served), 'paths': self.paths()}
+
+    def service_cmd(self) -> Mapping[str, Any]:
+        got = self.service()
+        if got is None:
+            return {'refused': 'nothing to say'}
+        doc, source = got
+        return {'source': source, 'document': doc}
+
+    def standing_cmd(self) -> Mapping[str, Any]:
+        got = self.standing()
+        if got is None:
+            return {'refused': 'nothing to say'}
+        doc, source = got
+        return {'source': source, 'document': doc}
+
+    def blob_cmd(self, args: Mapping[str, Any]) -> Mapping[str, Any]:
+        got = self.blob(str(args.get('sha256', '')).lower())
+        if got is None:
+            return {'refused': 'nothing to say'}
+        doc, source = got
+        return {'source': source, 'document': doc}
+
+    @staticmethod
+    def paths() -> list[str]:
+        return [PREFIX + 'service.jsonld', PREFIX + 'blob/<sha256>.jsonld', PREFIX + 'standing.jsonld']
+
+    # ---- the documents --------------------------------------------------------
+    def service(self) -> Optional[tuple[linked_data.LinkedData, str]]:
+        desc = self._descriptor()
+        if not desc:
+            return None
+        inbox = self._inbox() if self._inbox is not None else None
+        return linked_data.service(desc, inbox), desc['id']
+
+    def blob(self, sha: str) -> Optional[tuple[linked_data.LinkedData, str]]:
+        if self.blobs is None or not _SHA.match(sha):
+            return None
+        st = self.blobs.stat(sha)
+        if not st:
+            return None
+        url = self.blossom_url
+        d: BlobFacts = {'sha256': sha, 'size': st.get('size'), 'type': st.get('type')}
+        if st.get('uploaded') is not None:
+            d['uploaded'] = st['uploaded']
+        if url:
+            d['url'] = '%s/%s' % (url.rstrip('/'), sha)
+        return linked_data.media_object(d), sha
+
+    def standing(self) -> Optional[tuple[linked_data.LinkedData, str]]:
+        desc = self._descriptor()
+        tell = self._standing() if self._standing is not None else None
+        if not desc or not tell:
+            return None
+        return linked_data.standing(desc['pubkey'], tell), desc['id']
+
+    # ---- the hook ---------------------------------------------------------------
+    def handle_request(self, conn: Any, req: Any) -> bool:
+        path = getattr(req, 'path', '/') or '/'
+        if not path.startswith(PREFIX):
+            return False
+        method = (getattr(req, 'method', 'GET') or 'GET').upper()
+        if method not in ('GET', 'HEAD'):
+            ws.http_response(conn, '405 Method Not Allowed', b'', 'text/plain', {'Allow': 'GET, HEAD'})
+            return True
+        rest = path[len(PREFIX):].split('?', 1)[0]
+        got: Optional[tuple[linked_data.LinkedData, str]] = None
+        which = ''
+        if rest == 'service.jsonld':
+            which, got = 'service', self.service()
+        elif rest == 'standing.jsonld':
+            which, got = 'standing', self.standing()
+        elif rest.startswith('blob/') and rest.endswith('.jsonld'):
+            which, got = 'blob', self.blob(rest[5:-7].lower())
+        else:
+            ws.http_response(conn, '404 Not Found', b'no such projection\n', 'text/plain')
+            return True
+        if got is None:
+            ws.http_response(conn, '404 Not Found', b'nothing to say\n', 'text/plain',
+                             {'Cache-Control': 'no-store'})
+            return True
+        doc, source = got
+        body = json.dumps(doc, sort_keys=True, separators=(',', ':')).encode()
+        self.served[which] += 1
+        ws.http_response(conn, '200 OK', b'' if method == 'HEAD' else body, CTYPE,
+                         {'Cache-Control': 'no-store', 'X-Fleetmesh-Source': source})
+        return True

node/planes/identity/linked/types.py

@@ -0,0 +1,25 @@
+"""Types and records for the Linked Data compartment."""
+from __future__ import annotations
+
+from typing import Optional, TypedDict
+
+
+class LinkedTotals(TypedDict):
+    service: int
+    blob: int
+    standing: int
+
+
+class LinkedState(TypedDict):
+    served: dict[str, int]
+    paths: list[str]
+
+
+class BlobFacts(TypedDict, total=False):
+    """What blobstore.stat() says about one blob, in the field names
+    linked_data.media_object() reads (a blossom_auth.BlobDescriptor)."""
+    sha256: str
+    size: Optional[int]
+    type: Optional[str]
+    uploaded: int
+    url: str

node/planes/identity/presence/__init__.py

@@ -0,0 +1,7 @@
+"""What this node says it is alive, and what it makes of a peer saying so.
+
+One-module compartment: everything is in compartment.py.
+"""
+from .compartment import Presence
+
+__all__ = ['Presence']