Source code for fleetmesh_core.peering.projection

"""The relay score a node projects for clients: kind 30385 under NIP-85,
derived from a kind 30802 and from nothing else.

A kind 30802 is a peer verdict, read by nodes setting budgets. A client
choosing a relay reads none of that. It reads NIP-85, where a provider it has
chosen publishes a rank for a subject, and for a URL the subject is a NIP-73
identifier: kind 30385, `d` the URL, `k` the word `web`. This module writes one
of those per ws or wss endpoint the reported node declares, so a client that
already understands NIP-85 learns what the mesh found without learning the
mesh.

Adverse only. A node publishes a score for a peer it has reported and for no
other peer. The rank is not the peer's standing - standing lives in blinded
grants and unpublished clean windows precisely so that it is not on a relay -
it is how far the reporter's own budget for the subject fell: 100 times the
multiplier the ladder applied. The report is cited by coordinate in an `a` tag,
so the evidence is one fetch away and the score never says more than the
report does.

The specification had held this back while nostr-protocol/nips PR 2418, which
proposes a differently shaped relay assertion under the same kind number,
settled. It has not settled and never discussed the number. Merged NIP-85
already assigns kind 30385 to NIP-73 identifiers and a relay URL is one, so the
projection is published under the documents that exist. If the proposal merges
on another number a second serialiser follows it.

Everything here reads its shape from `projection` in constants.json.
"""
from __future__ import annotations

import ipaddress
import re
from typing import Optional, Sequence

from ..wire import schema_files

from ..storage import store
from ..wire import spelling
from ..wire.interfaces import (
    EventLike,
    ProjectionConstants,
    SchemaConstantsDocument,
    UnsignedNostrEvent,
)

CONSTANTS: SchemaConstantsDocument = schema_files.load_constants()
P: ProjectionConstants = CONSTANTS['projection']

KIND: int = P['kind']
REPORT: int = 30802
RANK: dict[str, int] = P['rank_by_outcome']
IDENTIFIER_TYPE: str = 'web'
DEFAULT_PORT: dict[str, int] = {'ws': 80, 'wss': 443}


def _is_hex64(s: object) -> bool:
    return spelling.is_hex(s, 64)


# ---------------------------------------------------------- the identifier --
[docs]def canonical_relay(url: str) -> str: """The one spelling of a relay address, per projection.canonical_relay. Two nodes reporting the same relay must publish the same `d`, or a client sees two subjects where there is one. NIP-73 says a URL is normalised with no fragment and stops there; this says the rest, and it says it by refusing: a general URL parser (urlsplit, WHATWG) normalises IDNA, IP shorthand, dot segments and percent-encoding each in its own way, so two runtimes agree only if neither is asked to. The grammar is scheme "://" host [":" port] [path] ["?" ...] ["#" ...] scheme ws | wss, any case, lowercased host an LDH domain name (lowercased; a non-ASCII name is presented as its A-labels), a dotted-quad IPv4, or a bracketed IPv6 literal in its RFC 5952 spelling; nothing else, no userinfo port ASCII digits 1..65535 without leading zeros; the default is dropped path "/"-separated segments of URL path characters (no ".", "..", "", space, backslash or non-ASCII); trailing slashes are dropped query and fragment are not part of a relay's identity and are dropped. Raises ValueError for an address that is not a relay's. """ if not isinstance(url, str) or not url.strip(): raise ValueError('a relay address is a non-empty string') s = url.strip() scheme, sep, rest = s.partition('://') scheme = scheme.lower() if not sep or scheme not in DEFAULT_PORT: raise ValueError('scheme must be ws or wss, not %r' % (scheme or s)) for cut in '#?': rest = rest.split(cut, 1)[0] slash = rest.find('/') authority, path = (rest, '') if slash < 0 else (rest[:slash], rest[slash:]) if '@' in authority: raise ValueError('a relay address carries no userinfo') if authority.startswith('['): close = authority.find(']') if close < 0: raise ValueError('an IPv6 literal closes its bracket') host, port_part = authority[:close + 1], authority[close + 1:] else: host, _, port_text = authority.partition(':') port_part = ':' + port_text if _ else '' host = _canonical_host(host) port = None if port_part: digits = port_part[1:] port = store.ascii_int(digits) if port is None or digits != str(port) or not 0 < port < 65536: raise ValueError('port out of range') netloc = host if port in (None, DEFAULT_PORT[scheme]) else '%s:%d' % (host, port) return '%s://%s%s' % (scheme, netloc, _canonical_path(path))
_LDH = re.compile(r'^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$') _PATH_CHARS = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~!$&'()*+,;=:@%") def _canonical_host(host: str) -> str: if not host: raise ValueError('a relay address names a host') if host.startswith('['): if not host.endswith(']'): raise ValueError('an IPv6 literal closes its bracket') text = host[1:-1] if '%' in text: raise ValueError('an IPv6 literal carries no zone id') try: addr = ipaddress.IPv6Address(text) except ValueError: raise ValueError('not an IPv6 address: %s' % host) if int(addr) >> 32 in (0, 0xffff): raise ValueError('an IPv4 address is written as a dotted quad, not embedded in IPv6') if str(addr) != text: raise ValueError('an IPv6 literal is written in its RFC 5952 form: [%s]' % addr) return host if host.replace('.', '').isdigit() and host.isascii(): parts = host.split('.') if len(parts) != 4 or any(not p or p != str(int(p)) or int(p) > 255 for p in parts): raise ValueError('an IPv4 address is four decimal octets') return host lowered = host.lower() if not lowered.isascii(): raise ValueError('a non-ASCII host is presented as its A-labels (xn--)') labels = lowered.split('.') if len(lowered) > 253 or any(not _LDH.match(label) for label in labels): raise ValueError('host is not a valid domain name') for label in labels: if label.startswith('xn--') and not _punycode_ok(label[4:]): raise ValueError('%s is not a well-formed A-label' % label) return lowered def _punycode_ok(tail: str) -> bool: """Punycode that decodes to a non-ASCII name and re-encodes to itself.""" try: name = tail.encode('ascii').decode('punycode') except UnicodeError: return False return bool(name) and not name.isascii() and name.encode('punycode').decode('ascii') == tail def _canonical_path(path: str) -> str: path = path.rstrip('/') if not path: return '' for seg in path[1:].split('/'): if seg in ('', '.', '..') or any(ch not in _PATH_CHARS for ch in seg): raise ValueError('path is not canonical: %r' % path) return path
[docs]def relay_endpoints(descriptor: EventLike) -> list[str]: """The relay addresses a kind 11801 declares: ws and wss endpoints, canonical, deduplicated, sorted. An endpoint that does not canonicalise is skipped rather than fatal; it is the descriptor's defect and the validator reports it there. """ out: set[str] = set() for t in store.tags(descriptor, 'endpoint'): if len(t) >= 3 and t[1] in DEFAULT_PORT: try: out.add(canonical_relay(t[2])) except ValueError: continue return sorted(out)
# ----------------------------------------------------------- the assertion --
[docs]def coordinate(report: EventLike) -> str: """The NIP-01 `a` value of a kind 30802: kind, author, and its `d`.""" d = store.first_tag(report, 'd') return '%d:%s:%s' % (REPORT, report.get('pubkey', ''), d[1] if d and len(d) > 1 else '')
[docs]def project( report: EventLike, endpoints: Sequence[str], now: Optional[int] = None, ) -> list[UnsignedNostrEvent]: """The kind 30385 events a report projects to: one per endpoint, unsigned. `endpoints` is what relay_endpoints() returned for the subject's descriptor. A subject with none projects to nothing, which is right: a client cannot connect to it, so there is nothing to score. `now` is the created_at; a node stamps it past the last one at that coordinate, like every other addressable event it republishes. """ # `!=` let 30802.0 and True-shaped kinds through; a kind is a JSON integer. if not store.is_int(report.get('kind')) or report.get('kind') != REPORT: raise ValueError('only a kind 30802 projects; this is kind %r' % report.get('kind')) if not store.is_hex64(report.get('pubkey')): raise ValueError('a report has a 64-hex pubkey') if now is None and not store.is_int(report.get('created_at')): raise ValueError('a report has an integer created_at') outcome = store.first_tag(report, 'outcome') if outcome is None or len(outcome) < 2 or outcome[1] not in RANK: raise ValueError('outcome %r is not a finding the projection prices' % (outcome[1] if outcome and len(outcome) > 1 else None)) subject = store.first_tag(report, 'd') if subject is None or len(subject) < 2 or not _is_hex64(subject[1]): raise ValueError('a report names its subject in d') created_at = report['created_at'] if now is None else now # Only a well-formed expiration is carried across (store.expiration's # rule); garbage on the report does not become garbage on the projection. exp_ts = store.expiration(report) out: list[UnsignedNostrEvent] = [] for url in sorted(set(endpoints)): if canonical_relay(url) != url: raise ValueError('endpoint %r is not canonical' % url) tags: list[list[str]] = [ ['d', url], ['k', IDENTIFIER_TYPE], ['p', subject[1]], ['a', coordinate(report)], ['rank', str(RANK[outcome[1]])], ] if exp_ts is not None: tags.append(['expiration', str(exp_ts)]) out.append(store.make_event(report['pubkey'], created_at, KIND, tags, '')) return out
[docs]def check_projection( event: EventLike, report: Optional[EventLike] = None, endpoints: Optional[Sequence[str] | set[str]] = None, ) -> list[str]: """Everything a reader may hold a projection to. Returns the problems. Alone, the shape: the tags NIP-85 and this protocol require, a canonical `d`, a rank the ladder can produce. With the report, the derivation: same author, the coordinate really is that report's, the rank is the report's outcome priced, the expiry is the report's. With the subject's endpoints, that `d` is one of them. """ p: list[str] = [] if not store.is_int(event.get('kind')) or event.get('kind') != KIND: p.append('kind must be %d' % KIND) if not isinstance(event.get('tags'), list) or any( not isinstance(t, list) or not t or not all(isinstance(x, str) for x in t) for t in event['tags']): p.append('every tag must be a non-empty array of strings') d = store.first_tag(event, 'd') if d is None or len(d) < 2 or not d[1]: p.append('d is required') else: try: if canonical_relay(d[1]) != d[1]: p.append('d is not canonical: %r' % d[1]) except ValueError as e: p.append('d is not a relay address: %s' % e) k = store.first_tag(event, 'k') if k is None or len(k) < 2 or k[1] != IDENTIFIER_TYPE: p.append('k must be %s' % IDENTIFIER_TYPE) subj = store.first_tag(event, 'p') if subj is None or len(subj) < 2 or not _is_hex64(subj[1]): p.append('p must name the subject node') a = store.first_tag(event, 'a') if a is None or len(a) < 2: p.append('a must cite the report') else: parts = a[1].split(':') if (len(parts) != 3 or parts[0] != str(REPORT) or not _is_hex64(parts[1]) or not _is_hex64(parts[2])): p.append('a is not a kind 30802 coordinate: %r' % a[1]) else: if parts[1] != event.get('pubkey'): p.append('a cites a report by someone else; a projection is of its author\'s own report') if subj is not None and len(subj) >= 2 and parts[2] != subj[1]: p.append('a cites a report about a different subject than p') rank = store.first_tag(event, 'rank') if rank is None or len(rank) < 2 or store.ascii_int(rank[1]) is None: p.append('rank must be a decimal integer') elif store.ascii_int(rank[1]) not in RANK.values(): p.append('rank %s is not one the ladder produces' % rank[1]) if event.get('content', '') != '': p.append('content is empty') if len(store.tags(event, 'd')) > 1 or len(store.tags(event, 'rank')) > 1: p.append('one d and one rank') if report is not None: if report.get('pubkey') != event.get('pubkey'): p.append('the report and the projection have different authors') if a is not None and len(a) >= 2 and a[1] != coordinate(report): p.append('a does not cite this report') outcome = store.first_tag(report, 'outcome') outcome_name = outcome[1] if outcome is not None and len(outcome) > 1 else None want = RANK.get(outcome_name) if outcome_name is not None else None if want is None: p.append('the report has no outcome the projection prices') elif rank is not None and len(rank) >= 2 and rank[1] != str(want): p.append('rank %s but the report is %s, which prices at %d' % (rank[1], outcome_name, want)) if store.expiration(report) != store.expiration(event): p.append('expiration is the report\'s') if endpoints is not None and d is not None and len(d) >= 2 and d[1] not in endpoints: p.append('d is not an endpoint the subject declares') return p
# ---------------------------------------------------------- NIP-32 Labels -- LABEL_KIND: int = 1985 LABEL_NAMESPACE: str = 'fleetmesh.reputation' LABEL_BY_OUTCOME: dict[str, str] = { 'S1': 's1-divergence', 'S2': 's2-misreport', 'S3': 's3-overrun', 'S4': 's4-tamper', }
[docs]def label( report: EventLike, now: Optional[int] = None, ) -> UnsignedNostrEvent: """Build a NIP-32 kind 1985 moderation/reputation label derived from an adverse report.""" if not store.is_int(report.get('kind')) or report.get('kind') != REPORT: raise ValueError('only a kind 30802 projects a label; this is kind %r' % report.get('kind')) outcome = store.first_tag(report, 'outcome') if outcome is None or len(outcome) < 2 or outcome[1] not in LABEL_BY_OUTCOME: raise ValueError('outcome %r is not a finding with a label mapping' % (outcome[1] if outcome and len(outcome) > 1 else None)) subject = store.first_tag(report, 'd') if subject is None or len(subject) < 2 or not _is_hex64(subject[1]): raise ValueError('a report names its subject in d') created_at = report.get('created_at', 0) if now is None else now expiration = store.first_tag(report, 'expiration') label_value = LABEL_BY_OUTCOME[outcome[1]] tags: list[list[str]] = [ ['L', LABEL_NAMESPACE], ['l', label_value, LABEL_NAMESPACE], ['p', subject[1]], ['a', coordinate(report)], ] if report.get('id'): tags.append(['e', report['id']]) if expiration is not None and len(expiration) > 1: tags.append(['expiration', expiration[1]]) return store.make_event(report.get('pubkey', ''), created_at, LABEL_KIND, tags, '')