"""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