fleetmesh-node 0.2.0__py3-none-any.whl

node/meshnode.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""meshnode: the operator's command.
+
+<!-- commands:begin -->
+    meshnode init DIR                       generate keys, write config, mine and publish the descriptor
+    meshnode run DIR                        start the node and tick until SIGTERM
+    meshnode status DIR                     what the running node last wrote, and its trouble
+    meshnode health DIR                     every error plane: relays, drops, rejections, failures
+    meshnode whoami DIR                     the node's identity: DID, npub, keys, descriptor
+    meshnode check DIR                      is this directory a node that can run? exits 1 if not
+    meshnode tick DIR                       one tick now, and what it did (needs the node running)
+    meshnode api DIR                        the control socket described by itself: protocol, commands, arguments, replies
+    meshnode peers DIR                      every peer: tiers, pending grant, last window, standing
+    meshnode grant DIR PEER                 both grants with a peer, their history, and what waits for the boundary
+    meshnode windows DIR PEER               the windows this node priced for a peer
+    meshnode peer DIR PEER                  add a peer and shard to pull from
+    meshnode unpeer DIR PEER                stop pulling from a peer; the grants stay live
+    meshnode trust DIR PEER                 inspect or set a peer's tier, which nothing else can raise
+    meshnode terminate DIR PEER             end a peering: zero both grants and tell the peer (needs the node running)
+    meshnode retire DIR                     leave the mesh in order: hand over every asserted shard, withdraw the claims, stop
+    meshnode withdraw DIR PEER WINDOW       withdraw a finding this node made about one window (needs the node running)
+    meshnode standing DIR PEER TARGET       ask a peer what it knows about a third node (needs the node running)
+    meshnode reports DIR TARGET             the kind 30802s about a node, weighed by this one (needs the node running)
+    meshnode strain DIR                     what this node has survived, by direction, and the reserves it sets
+    meshnode subsystems DIR                 every compartment of this node, and what each has refused
+    meshnode refusals DIR                   every no this node said, across every compartment
+    meshnode events DIR                     the node's recent bus events, from memory
+    meshnode subscribe DIR                  follow the node's bus live, one line per event
+    meshnode capacity DIR                   this node's own ceiling, the pressure on it, and what it is shedding
+    meshnode scheduled DIR                  every scheduled pull, throttles and holds
+    meshnode coverage DIR ACTION SHARD      the shards this node claims to hold, as kind 30803
+    meshnode descriptor DIR                 the kind 11801 this node published
+    meshnode pull DIR PEER SHARD            pull a shard from a peer now (needs the node running)
+    meshnode bridge DIR ACTION              interact with the Universal Nostr Relay Bridge
+    meshnode compute DIR ACTION             inspect or interact with the compute market and order book
+    meshnode dvm DIR ACTION                 interact with the NIP-90 Data Vending Machine Gateway
+    meshnode settle DIR ACTION              inspect settlement rails, escrows, and execute live payments
+    meshnode gossip DIR ACTION              gossip/1.0 group topics: create and publish rosters, flood sealed wraps
+    meshnode enclave DIR ACTION             inspect and interact with hardware enclaves and passkeys
+    meshnode iroh DIR ACTION                iroh P2P QUIC transport diagnostics and control
+    meshnode fips DIR ACTION                FIPS Native Datagram API transport diagnostics and control
+    meshnode cluster DIR CLUSTER_ACTION     manage a local multi-node testnet cluster
+    meshnode nsite DIR ACTION               host static sites (NIP-5A): publish this node's site, manage custom domains
+    meshnode sidecars DIR ACTION            fronted sidecars (grasp, ncontainer, magpie, ...): self-test results, or run the tests now
+    meshnode sidecar-manifest FILE          write, lint or try a sidecar manifest with no node (for sidecar authors)
+    meshnode plugin-check REF               hold a plugin class to the rules the node applies at startup, with no node (for plugin authors)
+<!-- commands:end -->
+
+Two kinds of command. The ones that read state read the node directory, so
+they work whether the node is running or not. The ones that change what the
+node is told to do - peer, unpeer, trust, coverage - write config.json and
+nothing else; a running node re-reads it every tick. The ones that need the
+daemon itself - pull, terminate, withdraw, standing, reports, tick, republish - go over
+the control socket in the directory, and say so when no node is running.
+
+PEER may be a pubkey, a did:nostr, an npub, or an unambiguous prefix of a peer this
+node holds a grant with.
+
+`trust` is the only thing that raises a peer's tier. The severity ladder
+lowers one and never raises it, because standing is bought with observed
+time rather than granted by arithmetic; seeding a tier for a node you know
+out of band is a human decision, recorded as a signed grant and reversible.
+A peer left alone opens at probation, whose reporter weight is zero.
+
+DIR holds keys.json (0600), config.json, descriptor.json, events.sqlite,
+grants.sqlite, accounts.sqlite, status.json and, while the node runs, the
+control socket.
+
+The command table above sits between marker comments and is regenerated from
+the parser by `scripts/check-cli.py --write`; the checker fails when it drifts.
+The commands themselves live in node/commands/*.py, one module per group; this
+file only assembles the parser and is the `meshnode` entrypoint.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from typing import Sequence
+
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(os.path.abspath(__file__)), '..')))
+from node.commands import PROVIDERS, base, plugin_cli_classes, register_plugin_cli
+
+TIERS: tuple[str, ...] = base.TIERS
+
+
+def build_parser(argv: Sequence[str] | None = None) -> argparse.ArgumentParser:
+    """The whole operator CLI. Separate from main() so a checker can walk it.
+
+    `argv` lets the plugins a node directory declares add their verbs
+    (node/commands `register_plugin_cli`); without it the parser is the core
+    CLI alone, which is what the documentation checker reads.
+    """
+    ap = argparse.ArgumentParser(prog='meshnode', description=__doc__.split('\n\n')[0])
+    sub = ap.add_subparsers(dest='cmd', required=True)
+    for provider in PROVIDERS:
+        provider.register(sub)
+    if argv is not None:
+        register_plugin_cli(sub, plugin_cli_classes(argv))
+    return ap
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    a = build_parser(argv if argv is not None else sys.argv[1:]).parse_args(argv)
+    code = a.fn(a)
+    if isinstance(code, int) and code:
+        sys.exit(code)
+
+
+if __name__ == '__main__':
+    main()

node/metrics/__init__.py

@@ -0,0 +1,396 @@
+"""What a compartment measures, declared where the compartment is.
+
+The node already exposes Prometheus text, and it does it in one place for one
+compartment: `relayserver.render_metrics` hand-builds the exposition with the
+metric names, HELP and TYPE lines written inline, reaching into `self.store`,
+`self._conns` and `self.blob_store` behind `hasattr` guards and bare excepts.
+Meanwhile nineteen compartments keep a `counts` Counter and a `state()` dict
+that no exporter has ever seen. So a node reports the relay face and is silent
+about the budget, the scheduler, the grants and the bridge.
+
+That is the same shape as the log before `Channel`: one hand-written path, no
+declaration, and nothing a reader can enumerate. A `Metric` is the answer in
+the same form - declared beside the compartment that measures it, with its
+kind, its unit and its help text attached, so the exposition is rendered from
+declarations rather than typed out.
+
+`relayserver` already takes a `metrics_provider` callable and nothing ever
+passed one. That seam is what this plugs into: the registry becomes the
+provider, and the relay face's own numbers become declared metrics like
+everybody else's.
+
+## The bus does the counting
+
+A metric naming a channel in `counts` is incremented by that channel being
+raised. `Log.say` tells the registry, so declaring
+
+    Channel(name='release.available', ...)
+    Metric(name='release_available', kind=COUNTER, counts='release.available')
+
+is all a compartment does to get both a log line and a counter, and the two
+cannot disagree about how many there were. Monitors ride the bus the log
+rides, which is the point of putting them on it.
+
+A gauge reads the world instead, through `sample`. A sampler that raises is
+counted and skipped: an exporter that can be taken down by one bad reading
+takes the monitoring down exactly when something is wrong.
+
+## Prometheus names are not Python names
+
+Exposition names must match [a-zA-Z_:][a-zA-Z0-9_:]*, so a channel's dots
+cannot appear in one; a counter conventionally ends `_total`; a unit belongs
+in the name as `_bytes` or `_seconds`. All three are derived here and checked
+at registration, because a name Prometheus rejects is a metric that silently
+never arrives.
+"""
+from __future__ import annotations
+
+import collections
+import dataclasses
+import re
+import threading
+from typing import Any, Callable, Iterable, Mapping, Optional, Sequence, TypedDict
+
+COUNTER, GAUGE, HISTOGRAM = 'counter', 'gauge', 'histogram'
+KINDS: tuple[str, ...] = (COUNTER, GAUGE, HISTOGRAM)
+
+# Every metric this node exposes carries the project prefix, so a Prometheus
+# server scraping several things can tell whose they are.
+PREFIX: str = 'fleetmesh'
+
+# Units that belong in the name, by Prometheus convention. A unit not listed
+# here is refused rather than appended blindly: 'ms' is the classic mistake,
+# and the convention is seconds.
+UNITS: tuple[str, ...] = ('bytes', 'seconds', 'ratio', 'info')
+
+_NAME = re.compile(r'[a-z_][a-z0-9_]*$')
+_LABEL = re.compile(r'[a-z_][a-z0-9_]*$')
+
+# Buckets for a latency histogram, in seconds. Declared so a compartment that
+# wants the usual spread does not retype it, and so two compartments measuring
+# latency are comparable.
+LATENCY_BUCKETS: tuple[float, ...] = (0.005, 0.025, 0.1, 0.5, 1.0, 5.0, 30.0)
+
+
+class MetricRecord(TypedDict, total=False):
+    """A metric as `meshnode metrics` and the docs read it."""
+    name: str
+    exposed: str
+    description: str
+    kind: str
+    unit: str
+    labels: list[str]
+    counts: str
+    tags: list[str]
+    compartment: str
+
+
+class RegistryState(TypedDict):
+    """What the registry itself is doing, for the health block."""
+    metrics: int
+    channels_bound: int
+    rejected: list[str]
+    failures: dict[str, int]
+
+
+class Reading(TypedDict, total=False):
+    """One value of one metric, with the labels it was recorded under."""
+    name: str
+    exposed: str
+    kind: str
+    labels: dict[str, str]
+    value: float
+    buckets: dict[str, int]
+    count: int
+    sum: float
+
+
+@dataclasses.dataclass(frozen=True)
+class Metric:
+    """One thing a compartment measures.
+
+    `counts` names a channel and makes this a counter the bus drives.
+    `sample` reads the world and makes it a gauge. A metric with neither is
+    incremented by hand through `Monitors.inc`, which is what a counter that
+    does not correspond to a single channel needs.
+    """
+    name: str
+    description: str
+    kind: str = GAUGE
+    unit: str = ''
+    labels: tuple[str, ...] = ()
+    counts: str = ''
+    sample: Optional[Callable[[], Any]] = None
+    buckets: tuple[float, ...] = ()
+    tags: tuple[str, ...] = ()
+
+    @property
+    def exposed(self) -> str:
+        """The Prometheus name: prefix, name, unit, and `_total` for a counter.
+
+        Derived rather than written, so a declaration cannot name one thing in
+        the docs and another in the exposition.
+        """
+        parts = [PREFIX, self.name]
+        if self.unit:
+            parts.append(self.unit)
+        out = '_'.join(parts)
+        if self.kind == COUNTER and not out.endswith('_total'):
+            out += '_total'
+        return out
+
+    def problems(self) -> list[str]:
+        """Everything wrong with this declaration, in sentences.
+
+        Collected rather than raised one at a time, as `config.Problems` does,
+        and checked at registration: a name Prometheus rejects is a metric
+        that silently never arrives, which is the failure mode worth paying a
+        check for.
+        """
+        out: list[str] = []
+        if not _NAME.match(self.name or ''):
+            out.append('%r must be lowercase letters, digits and underscores, '
+                       'starting with a letter or underscore' % self.name)
+        if self.kind not in KINDS:
+            out.append('%s: kind must be one of %s' % (self.name, ', '.join(KINDS)))
+        if self.unit and self.name.endswith('_' + self.unit):
+            # fleetmesh_updates_check_seconds_seconds, which is what the first
+            # declaration produced. The unit is appended from `unit`, so
+            # putting it in the name as well doubles it. Refused rather than
+            # quietly de-duplicated: the declaration is muddled and a silent
+            # fix leaves two spellings that look equally correct.
+            out.append('%s: the unit is appended from `unit`, so do not end the name '
+                       'with %r as well' % (self.name, self.unit))
+        if self.unit and self.unit not in UNITS:
+            out.append('%s: unit %r is not one of %s - milliseconds are a classic '
+                       'mistake and the convention is seconds'
+                       % (self.name, self.unit, ', '.join(UNITS)))
+        for lab in self.labels:
+            if not _LABEL.match(lab):
+                out.append('%s: label %r must be lowercase letters, digits and '
+                           'underscores' % (self.name, lab))
+        if self.kind == HISTOGRAM and not self.buckets:
+            out.append('%s: a histogram needs buckets; LATENCY_BUCKETS is the house set'
+                       % self.name)
+        if self.kind != HISTOGRAM and self.buckets:
+            out.append('%s: only a histogram has buckets' % self.name)
+        if self.counts and self.kind != COUNTER:
+            out.append('%s: a metric fed by a channel is a counter, not a %s'
+                       % (self.name, self.kind))
+        if self.counts and self.sample is not None:
+            out.append('%s: counts and sample are two sources for one metric; pick one'
+                       % self.name)
+        if self.kind == GAUGE and self.sample is None and not self.labels:
+            # A gauge nothing reads and nothing sets is a metric that will
+            # always report zero, which is worse than an absent one.
+            out.append('%s: a gauge needs a sample, or labels it is set under'
+                       % self.name)
+        if self.buckets and list(self.buckets) != sorted(self.buckets):
+            out.append('%s: buckets must be ascending' % self.name)
+        return out
+
+    def describe(self) -> MetricRecord:
+        out: MetricRecord = {
+            'name': self.name, 'exposed': self.exposed, 'description': self.description,
+            'kind': self.kind, 'labels': list(self.labels), 'tags': list(self.tags),
+        }
+        if self.unit:
+            out['unit'] = self.unit
+        if self.counts:
+            out['counts'] = self.counts
+        return out
+
+
+def declared(obj: Any) -> tuple[Metric, ...]:
+    """The metrics a compartment declares, or () for one not yet converted."""
+    return tuple(getattr(obj, 'METRICS', ()) or ())
+
+
+def every_metric(compartments: Sequence[Any]) -> list[MetricRecord]:
+    """Every declared metric, the companion of every_channel and
+    every_parameter: what the node measures, as those are what it says and
+    what it can be told."""
+    out: list[MetricRecord] = []
+    for c in compartments:
+        for m in declared(c):
+            row = m.describe()
+            row['compartment'] = (getattr(c, 'name', '') or getattr(c, 'key', '')
+                                  or getattr(c, '__name__', str(c)))
+            out.append(row)
+    return out
+
+
+def _key(labels: Mapping[str, str], names: Sequence[str]) -> tuple[str, ...]:
+    """The label values in declared order, so one series has one key."""
+    return tuple(str(labels.get(n, '')) for n in names)
+
+
+class Monitors:
+    """The registry: declarations in, readings out, adapters on the end.
+
+    One per node. `Log` holds a reference and tells it when a channel is
+    raised, which is how a counter declared against a channel is fed without
+    the compartment doing anything twice.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.RLock()
+        self.metrics: dict[str, Metric] = {}
+        self.owner: dict[str, str] = {}
+        self._counts: dict[str, dict[tuple[str, ...], float]] = collections.defaultdict(dict)
+        self._gauges: dict[str, dict[tuple[str, ...], float]] = collections.defaultdict(dict)
+        self._hist: dict[str, dict[tuple[str, ...], list[float]]] = collections.defaultdict(dict)
+        self._by_channel: dict[str, list[str]] = collections.defaultdict(list)
+        self.rejected: list[str] = []
+        self.failures: dict[str, int] = {}
+
+    # ---- declaring ------------------------------------------------------
+    def register(self, metrics: Iterable[Metric], owner: str = '') -> list[str]:
+        """Declare metrics. Returns the problems, and registers the rest.
+
+        A bad declaration is refused and reported rather than raised, so one
+        malformed metric cannot stop a node booting - but it is kept in
+        `rejected` and surfaced by `state()`, because a metric silently
+        missing from the exposition is the thing this checks for.
+        """
+        problems: list[str] = []
+        with self._lock:
+            for m in metrics:
+                bad = m.problems()
+                if m.exposed in self.metrics and self.metrics[m.exposed] != m:
+                    bad.append('%s: %s is already declared by %s; one exposition name is '
+                               'one metric' % (m.name, m.exposed, self.owner.get(m.exposed, '?')))
+                if bad:
+                    problems.extend(bad)
+                    self.rejected.extend(bad)
+                    continue
+                self.metrics[m.exposed] = m
+                self.owner[m.exposed] = owner
+                if m.counts:
+                    self._by_channel[m.counts].append(m.exposed)
+        return problems
+
+    def register_from(self, compartments: Iterable[Any]) -> list[str]:
+        out: list[str] = []
+        for c in compartments:
+            name = (getattr(c, 'name', '') or getattr(c, 'key', '')
+                    or getattr(c, '__name__', str(c)))
+            out.extend(self.register(declared(c), owner=name))
+        return out
+
+    # ---- recording ------------------------------------------------------
+    def observe(self, channel: str) -> None:
+        """A channel was raised. Increment every counter declared against it.
+
+        Called by `Log.say`, which is what puts the monitors on the same bus
+        as the log: one declaration feeds the line and the count, so they
+        cannot disagree about how many there were.
+        """
+        with self._lock:
+            for exposed in self._by_channel.get(channel, ()):
+                series = self._counts[exposed]
+                series[()] = series.get((), 0.0) + 1.0
+
+    def inc(self, name: str, n: float = 1.0, **labels: str) -> None:
+        """Increment a counter by hand, for one that is not a single channel."""
+        with self._lock:
+            m = self._find(name)
+            if m is None or m.kind != COUNTER:
+                self.failures[name] = self.failures.get(name, 0) + 1
+                return
+            k = _key(labels, m.labels)
+            self._counts[m.exposed][k] = self._counts[m.exposed].get(k, 0.0) + n
+
+    def set(self, name: str, value: float, **labels: str) -> None:
+        """Set a gauge that is pushed rather than sampled."""
+        with self._lock:
+            m = self._find(name)
+            if m is None or m.kind != GAUGE:
+                self.failures[name] = self.failures.get(name, 0) + 1
+                return
+            self._gauges[m.exposed][_key(labels, m.labels)] = float(value)
+
+    def observe_value(self, name: str, value: float, **labels: str) -> None:
+        """Record one observation into a histogram."""
+        with self._lock:
+            m = self._find(name)
+            if m is None or m.kind != HISTOGRAM:
+                self.failures[name] = self.failures.get(name, 0) + 1
+                return
+            self._hist[m.exposed].setdefault(_key(labels, m.labels), []).append(float(value))
+
+    def _find(self, name: str) -> Optional[Metric]:
+        if name in self.metrics:
+            return self.metrics[name]
+        for m in self.metrics.values():
+            if m.name == name:
+                return m
+        return None
+
+    # ---- reading --------------------------------------------------------
+    def read(self) -> list[Reading]:
+        """Every metric's current value, samplers called now.
+
+        A sampler that raises is counted and skipped. An exporter one bad
+        reading can take down is monitoring that fails exactly when something
+        is wrong, which is when it is wanted.
+        """
+        out: list[Reading] = []
+        with self._lock:
+            items = list(self.metrics.items())
+        for exposed, m in items:
+            if m.sample is not None:
+                try:
+                    val = m.sample()
+                except Exception:
+                    with self._lock:
+                        self.failures[m.name] = self.failures.get(m.name, 0) + 1
+                    continue
+                if isinstance(val, Mapping):
+                    for lab, v in val.items():
+                        labels = lab if isinstance(lab, tuple) else (lab,)
+                        out.append({'name': m.name, 'exposed': exposed, 'kind': m.kind,
+                                    'labels': dict(zip(m.labels, [str(x) for x in labels])),
+                                    'value': float(v)})
+                else:
+                    out.append({'name': m.name, 'exposed': exposed, 'kind': m.kind,
+                                'labels': {}, 'value': float(val)})
+                continue
+            with self._lock:
+                if m.kind == COUNTER:
+                    series = dict(self._counts.get(exposed, {}))
+                elif m.kind == GAUGE:
+                    series = dict(self._gauges.get(exposed, {}))
+                else:
+                    series = {}
+                    for k, vals in self._hist.get(exposed, {}).items():
+                        buckets = {}
+                        for b in m.buckets:
+                            buckets['%g' % b] = sum(1 for v in vals if v <= b)
+                        buckets['+Inf'] = len(vals)
+                        out.append({'name': m.name, 'exposed': exposed, 'kind': m.kind,
+                                    'labels': dict(zip(m.labels, k)), 'buckets': buckets,
+                                    'count': len(vals), 'sum': float(sum(vals))})
+            for k, v in series.items():
+                out.append({'name': m.name, 'exposed': exposed, 'kind': m.kind,
+                            'labels': dict(zip(m.labels, k)), 'value': float(v)})
+            if m.kind == COUNTER and not series:
+                # A declared counter that has not fired yet reports zero. An
+                # absent series and a zero one mean different things to an
+                # alert, and "it has never happened" is the useful one.
+                out.append({'name': m.name, 'exposed': exposed, 'kind': m.kind,
+                            'labels': {}, 'value': 0.0})
+        return out
+
+    def state(self) -> 'RegistryState':
+        """What the registry itself is doing, for the health block."""
+        with self._lock:
+            out: RegistryState = {
+                'metrics': len(self.metrics), 'channels_bound': len(self._by_channel),
+                'rejected': list(self.rejected), 'failures': dict(self.failures)}
+            return out
+
+
+__all__ = ['Metric', 'MetricRecord', 'Reading', 'Monitors', 'declared', 'every_metric',
+           'COUNTER', 'GAUGE', 'HISTOGRAM', 'KINDS', 'UNITS', 'PREFIX', 'LATENCY_BUCKETS',
+           'RegistryState']

node/metrics/adapters.py

@@ -0,0 +1,102 @@
+"""Rendering readings for whoever is asking.
+
+An adapter turns `Monitors.read()` into one wire format. They are separate
+from the registry for the reason the log's backends are separate from the
+channels: what a compartment measures is not a decision about who scrapes it,
+and a second consumer must not mean a second set of declarations.
+
+    prometheus   the text exposition format, which is also OpenMetrics-
+                 compatible enough for a Prometheus server to scrape
+    json         the same readings as data, for the control socket and the
+                 health block
+
+`relayserver` already accepts a `metrics_provider` callable and nothing ever
+passed one, so `provider(monitors)` is the function to hand it. The relay
+face's hand-written exposition then becomes the fallback it already is rather
+than the only path.
+"""
+from __future__ import annotations
+
+from typing import Callable, Mapping, Sequence, TypedDict
+
+from . import HISTOGRAM, Monitors, Reading, RegistryState
+
+
+class Exposition(TypedDict):
+    """The readings as data: what the control socket and the health block get.
+
+    A named record for the reason check-dicts.py enforces it - this is a row
+    an operator reads by field name.
+    """
+    metrics: list[Reading]
+    registry: RegistryState
+
+
+def _escape(v: str) -> str:
+    """A label value, escaped as the exposition format requires.
+
+    Backslash first, or the escapes introduced after it get escaped again.
+    """
+    return v.replace('\\', '\\\\').replace('"', '\\"').replace('\n', '\\n')
+
+
+def _labels(labels: Mapping[str, str], extra: Sequence[tuple[str, str]] = ()) -> str:
+    items = [(k, str(v)) for k, v in labels.items() if v != ''] + list(extra)
+    if not items:
+        return ''
+    return '{%s}' % ','.join('%s="%s"' % (k, _escape(v)) for k, v in items)
+
+
+def prometheus(monitors: Monitors) -> str:
+    """The text exposition format.
+
+    HELP and TYPE are emitted once per metric name and before its samples,
+    which the format requires: a repeated TYPE line makes a scrape fail, and
+    a scrape that fails is monitoring that is absent rather than wrong.
+    """
+    readings = monitors.read()
+    by_name: dict[str, list[Reading]] = {}
+    for r in readings:
+        by_name.setdefault(r['exposed'], []).append(r)
+
+    out: list[str] = []
+    for exposed, rows in by_name.items():
+        m = monitors.metrics.get(exposed)
+        if m is None:
+            continue
+        help_text = m.description.replace('\\', '\\\\').replace('\n', ' ')
+        out.append('# HELP %s %s' % (exposed, help_text))
+        out.append('# TYPE %s %s' % (exposed, m.kind))
+        for r in rows:
+            if m.kind == HISTOGRAM:
+                for le, n in (r.get('buckets') or {}).items():
+                    out.append('%s_bucket%s %d' % (
+                        exposed, _labels(r.get('labels', {}), [('le', le)]), n))
+                out.append('%s_sum%s %g' % (exposed, _labels(r.get('labels', {})),
+                                            r.get('sum', 0.0)))
+                out.append('%s_count%s %d' % (exposed, _labels(r.get('labels', {})),
+                                              r.get('count', 0)))
+            else:
+                out.append('%s%s %g' % (exposed, _labels(r.get('labels', {})),
+                                        r.get('value', 0.0)))
+    return '\n'.join(out) + ('\n' if out else '')
+
+
+def json_readings(monitors: Monitors) -> 'Exposition':
+    """The readings as data, for the control socket and the health block.
+
+    The same readings the exposition is built from, so a dashboard reading the
+    socket and a Prometheus server scraping the face cannot see different
+    numbers - which is the failure the log had before Channel.
+    """
+    return {'metrics': monitors.read(), 'registry': monitors.state()}
+
+
+def provider(monitors: Monitors) -> Callable[[], str]:
+    """The callable `relayserver(metrics_provider=...)` has always wanted."""
+    def render() -> str:
+        return prometheus(monitors)
+    return render
+
+
+__all__ = ['prometheus', 'json_readings', 'provider', 'Exposition']