Source code for fleetmesh_node.planes.identity.linked.compartment

"""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 fleetmesh_node.compartment import stores as st
from fleetmesh_node.compartment import Command, Compartment, Need
from fleetmesh_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 fleetmesh_node.channels import Channel, INFO
from fleetmesh_node.metrics import COUNTER, Metric
from fleetmesh_node.config.parameter import Parameter, ParamBlock


[docs]@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
[docs]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), )
[docs] 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 ----------------------------------------------------------
[docs] 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)
[docs] def tick(self, now: int) -> list[tuple[Any, ...]]: return []
[docs] def state(self) -> LinkedState: return {'served': dict(self.served), 'paths': self.paths()}
[docs] 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}
[docs] 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}
[docs] 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}
[docs] @staticmethod def paths() -> list[str]: return [PREFIX + 'service.jsonld', PREFIX + 'blob/<sha256>.jsonld', PREFIX + 'standing.jsonld']
# ---- the documents --------------------------------------------------------
[docs] 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']
[docs] 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
[docs] 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 ---------------------------------------------------------------
[docs] 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