fleetmesh-node 0.2.0__py3-none-any.whl

node/compartment/lint.py

@@ -0,0 +1,388 @@
+"""Static declaration linter for Compartment subclasses."""
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from . import lifecycle as lifecycle_mod
+from . import stores as stores_mod
+from .command import Command
+from .every import Every
+from .handler import Handler
+from .need import Need
+from .problem import (
+    DuplicateProblem,
+    IncompatibleProblem,
+    InvalidIdentifierProblem,
+    Problem,
+    Problems,
+    ReferenceProblem,
+    ShadowingProblem,
+    TypeMismatchProblem,
+)
+from .worker import Worker
+
+__all__ = [
+    'declaration_problems',
+]
+
+
+def declaration_problems(cls: type[Any], base_cls: type[Any]) -> list[str]:
+    """Everything wrong with this class's declarations, as sentences.
+
+    Collected rather than raised one at a time, like `Metric.problems`
+    and `config.Problems`: whoever fixes one wants to see them all.
+    Returns Problems (a list subclass) holding typed Problem instances.
+    """
+    out = Problems()
+    if not cls.abstract and not (isinstance(cls.name, str) and cls.name):
+        out.append(Problem(
+            'a compartment has a name (or is declared abstract=True, a kind to extend)',
+            surface='NAME',
+            code='missing_name',
+            target='name',
+        ))
+    for surface, attr in (
+        ('CHANNELS', 'name'),
+        ('METRICS', 'name'),
+        ('COMMANDS', 'key'),
+        ('STORES', 'key'),
+        ('NEEDS', 'key'),
+        ('EVERY', 'name'),
+        ('WORKERS', 'name'),
+        ('HANDLERS', 'kind'),
+    ):
+        seen: set[str] = set()
+        for d in getattr(cls, surface, ()) or ():
+            k = getattr(d, attr, None)
+            if k in seen:
+                out.append(DuplicateProblem(surface, str(k)))
+            seen.add(str(k))
+    # The annotation promises a Lifecycle; this is for the subclass that
+    # broke the promise, so look at it as whatever it actually is.
+    lc: object = cls.LIFECYCLE
+    if not isinstance(lc, lifecycle_mod.Lifecycle):
+        out.append(TypeMismatchProblem('LIFECYCLE', 'node.lifecycle.Lifecycle', type(lc).__name__,
+                                       message='LIFECYCLE is a node.lifecycle.Lifecycle'))
+        return out
+    for p in lc.problems():
+        out.add(p, surface='LIFECYCLE')
+    out.extend(store_problems(cls, base_cls))
+    out.extend(command_problems(cls, base_cls))
+    out.extend(command_data_problems(cls))
+    out.extend(need_problems(cls, base_cls))
+    out.extend(every_problems(cls))
+    out.extend(worker_problems(cls))
+    out.extend(schema_problems(cls))
+    out.extend(migration_problems(cls))
+    out.extend(handler_problems(cls, base_cls))
+    out.extend(dependency_problems(cls))
+    out.extend(channel_problems(cls))
+    out.extend(metric_problems(cls))
+    out.extend(cli_problems(cls))
+    out.extend(sidecar_problems(cls))
+    return out
+
+
+def schema_problems(cls: type[Any]) -> list[str]:
+    out = Problems()
+    declared: tuple[object, ...] = tuple(getattr(cls, 'SCHEMA', ()) or ())
+    from .schema import Index, Table
+    seen_tables: set[str] = set()
+    seen_indices: set[str] = set()
+    for s in declared:
+        if not isinstance(s, (Table, Index)):
+            out.append(TypeMismatchProblem('SCHEMA', 'Table or Index', type(s).__name__,
+                                           message='SCHEMA holds Table or Index, not %s' % type(s).__name__))
+            continue
+        if isinstance(s, Table):
+            if s.name in seen_tables:
+                out.append(DuplicateProblem('SCHEMA', s.name, message='SCHEMA declares table %r twice' % s.name))
+            seen_tables.add(s.name)
+            out.extend(s.problems())
+            for idx in s.indices:
+                if idx.name in seen_indices:
+                    out.append(DuplicateProblem('SCHEMA', idx.name, message='SCHEMA declares index %r twice' % idx.name))
+                seen_indices.add(idx.name)
+        elif isinstance(s, Index):
+            if s.name in seen_indices:
+                out.append(DuplicateProblem('SCHEMA', s.name, message='SCHEMA declares index %r twice' % s.name))
+            seen_indices.add(s.name)
+            out.extend(s.problems())
+    return out
+
+
+def migration_problems(cls: type[Any]) -> list[str]:
+    out = Problems()
+    declared: tuple[object, ...] = tuple(getattr(cls, 'MIGRATIONS', ()) or ())
+    from .schema import Migration
+    last_version = 0
+    seen_versions: set[int] = set()
+    for m in declared:
+        if not isinstance(m, Migration):
+            out.append(TypeMismatchProblem('MIGRATIONS', 'node.compartment.schema.Migration', type(m).__name__,
+                                           message='MIGRATIONS holds node.compartment.schema.Migration, not %s' % type(m).__name__))
+            continue
+        if m.version in seen_versions:
+            out.append(DuplicateProblem('MIGRATIONS', str(m.version), message='MIGRATIONS declares version %d twice' % m.version))
+        seen_versions.add(m.version)
+        if m.version <= last_version:
+            out.append(IncompatibleProblem(
+                'MIGRATIONS', str(m.version),
+                f'MIGRATIONS versions must be strictly ascending (got {m.version} after {last_version})'
+            ))
+        last_version = m.version
+        out.extend(m.problems())
+    if declared and not getattr(cls, 'SCHEMA', ()):
+        out.append(IncompatibleProblem(
+            'MIGRATIONS', 'SCHEMA',
+            'a compartment that declares MIGRATIONS must also declare SCHEMA'
+        ))
+    return out
+
+
+def handler_problems(cls: type[Any], base_cls: type[Any]) -> list[str]:
+    out = Problems()
+    declared: tuple[object, ...] = tuple(getattr(cls, 'HANDLERS', ()) or ())
+    for h in declared:
+        if not isinstance(h, Handler):
+            out.append(TypeMismatchProblem('HANDLERS', 'node.compartment.Handler', type(h).__name__,
+                                           message='HANDLERS holds node.compartment.Handler, not %s' % type(h).__name__))
+            continue
+        out.extend(h.problems(cls))
+    if declared and cls.handle is not base_cls.handle:
+        out.append(IncompatibleProblem(
+            'HANDLERS', 'handle',
+            'a compartment that declares HANDLERS does not write handle(): '
+            'the base dispatches them, from the declarations'
+        ))
+    return out
+
+
+def dependency_problems(cls: type[Any]) -> list[str]:
+    out = Problems()
+    req = getattr(cls, 'requires', ()) or ()
+    use = getattr(cls, 'uses', ()) or ()
+    if not isinstance(req, (tuple, list)):
+        out.append(TypeMismatchProblem('requires', 'tuple[str, ...]', type(req).__name__,
+                                       message='requires must be a tuple of strings, not %s' % type(req).__name__))
+        req = ()
+    if not isinstance(use, (tuple, list)):
+        out.append(TypeMismatchProblem('uses', 'tuple[str, ...]', type(use).__name__,
+                                       message='uses must be a tuple of strings, not %s' % type(use).__name__))
+        use = ()
+
+    seen_req: set[str] = set()
+    for r in req:
+        if not isinstance(r, str):
+            out.append(TypeMismatchProblem('requires', 'str', type(r).__name__,
+                                           message='requires entries must be strings, not %s' % type(r).__name__))
+            continue
+        if not r.isidentifier():
+            out.append(InvalidIdentifierProblem('requires', r, message='requires %r is not a valid identifier' % r))
+        if r in seen_req:
+            out.append(DuplicateProblem('requires', r, message='requires declares %r twice' % r))
+        seen_req.add(r)
+        if cls.name and r == cls.name:
+            out.append(IncompatibleProblem('requires', r, '%s cannot require itself' % cls.name))
+
+    seen_use: set[str] = set()
+    for u in use:
+        if not isinstance(u, str):
+            out.append(TypeMismatchProblem('uses', 'str', type(u).__name__,
+                                           message='uses entries must be strings, not %s' % type(u).__name__))
+            continue
+        if not u.isidentifier():
+            out.append(InvalidIdentifierProblem('uses', u, message='uses %r is not a valid identifier' % u))
+        if u in seen_use:
+            out.append(DuplicateProblem('uses', u, message='uses declares %r twice' % u))
+        seen_use.add(u)
+        if cls.name and u == cls.name:
+            out.append(IncompatibleProblem('uses', u, '%s cannot use itself' % cls.name))
+
+    overlap = seen_req & seen_use
+    for o in sorted(overlap):
+        out.append(IncompatibleProblem(
+            'requires/uses', o,
+            '%s cannot be both required and optional (in both requires and uses)' % o
+        ))
+    return out
+
+
+def channel_problems(cls: type[Any]) -> list[str]:
+    out = Problems()
+    from ..channels import Channel
+    declared: tuple[object, ...] = tuple(getattr(cls, 'CHANNELS', ()) or ())
+    for ch in declared:
+        if not isinstance(ch, Channel):
+            out.append(TypeMismatchProblem('CHANNELS', 'node.channels.Channel', type(ch).__name__,
+                                           message='CHANNELS holds node.channels.Channel, not %s' % type(ch).__name__))
+    return out
+
+
+def metric_problems(cls: type[Any]) -> list[str]:
+    out = Problems()
+    from ..metrics import Metric
+    declared: tuple[object, ...] = tuple(getattr(cls, 'METRICS', ()) or ())
+    for m in declared:
+        if not isinstance(m, Metric):
+            out.append(TypeMismatchProblem('METRICS', 'node.metrics.Metric', type(m).__name__,
+                                           message='METRICS holds node.metrics.Metric, not %s' % type(m).__name__))
+            continue
+        for p in m.problems():
+            out.add(p, surface='METRICS')
+    return out
+
+
+def cli_problems(cls: type[Any]) -> list[str]:
+    out = Problems()
+    declared: tuple[object, ...] = tuple(getattr(cls, 'cli', ()) or ())
+    for item in declared:
+        if not (isinstance(item, (tuple, list)) and len(item) == 2):
+            out.append(TypeMismatchProblem('cli', 'tuple[str, Callable]', type(item).__name__,
+                                           message='cli entries must be (verb, register_fn) pairs, not %s' % type(item).__name__))
+            continue
+        verb, fn = item
+        if not (isinstance(verb, str) and verb.isidentifier()):
+            out.append(InvalidIdentifierProblem('cli', str(verb), message='cli verb %r is not a valid identifier' % verb))
+        if not callable(fn):
+            out.append(TypeMismatchProblem('cli', 'callable register_fn', type(fn).__name__,
+                                           message='cli register function for %r must be callable, not %s' % (verb, type(fn).__name__)))
+    return out
+
+
+def sidecar_problems(cls: type[Any]) -> list[str]:
+    out = Problems()
+    declared: tuple[object, ...] = tuple(getattr(cls, 'sidecars', ()) or ())
+    for item in declared:
+        if not (isinstance(item, Mapping) or (isinstance(item, str) and item.startswith('@'))):
+            out.append(TypeMismatchProblem(
+                'sidecars', 'manifest mapping or "@/path" string', type(item).__name__,
+                message='sidecars holds manifest dict or "@/path", not %s' % type(item).__name__
+            ))
+    return out
+
+
+def worker_problems(cls: type[Any]) -> list[str]:
+    out = Problems()
+    declared: tuple[object, ...] = tuple(getattr(cls, 'WORKERS', ()) or ())
+    for w in declared:
+        if not isinstance(w, Worker):
+            out.append(TypeMismatchProblem('WORKERS', 'node.compartment.Worker', type(w).__name__,
+                                           message='WORKERS holds node.compartment.Worker, not %s' % type(w).__name__))
+            continue
+        out.extend(w.problems(cls))
+    return out
+
+
+def every_problems(cls: type[Any]) -> list[str]:
+    out = Problems()
+    declared: tuple[object, ...] = tuple(getattr(cls, 'EVERY', ()) or ())
+    for e in declared:
+        if not isinstance(e, Every):
+            out.append(TypeMismatchProblem('EVERY', 'node.compartment.Every', type(e).__name__,
+                                           message='EVERY holds node.compartment.Every, not %s' % type(e).__name__))
+            continue
+        out.extend(e.problems(cls))
+    return out
+
+
+def need_problems(cls: type[Any], base_cls: type[Any]) -> list[str]:
+    out = Problems()
+    declared: tuple[object, ...] = tuple(getattr(cls, 'NEEDS', ()) or ())
+    for n in declared:
+        if not isinstance(n, Need):
+            out.append(TypeMismatchProblem('NEEDS', 'node.compartment.Need', type(n).__name__,
+                                           message='NEEDS holds node.compartment.Need, not %s' % type(n).__name__))
+            continue
+        out.extend(n.problems(cls))
+    fc = getattr(cls.from_context, '__func__', None)
+    base_fc = getattr(base_cls.from_context, '__func__', None)
+    if declared and fc is not base_fc:
+        out.append(IncompatibleProblem(
+            'NEEDS', 'from_context',
+            'a compartment that declares NEEDS does not override from_context: '
+            'the base constructs it from the declarations'
+        ))
+    return out
+
+
+def command_problems(cls: type[Any], base_cls: type[Any]) -> list[str]:
+    out = Problems()
+    declared: tuple[object, ...] = tuple(cls.COMMANDS)
+    for c in declared:
+        if not isinstance(c, Command):
+            out.append(TypeMismatchProblem('COMMANDS', 'node.compartment.Command', type(c).__name__,
+                                           message='COMMANDS holds node.compartment.Command, not %s' % type(c).__name__))
+            continue
+        out.extend(c.problems(cls))
+    if declared and cls.command is not base_cls.command:
+        out.append(IncompatibleProblem(
+            'COMMANDS', 'command',
+            'a compartment that declares COMMANDS does not write command(): '
+            'the base answers them, from the declarations'
+        ))
+    return out
+
+
+def store_problems(cls: type[Any], base_cls: type[Any]) -> list[str]:
+    out = Problems()
+    persisted = []
+    declared: tuple[object, ...] = tuple(cls.STORES)
+    for s in declared:
+        if not isinstance(s, stores_mod.Store):
+            out.append(TypeMismatchProblem('STORES', 'node.stores.Store', type(s).__name__,
+                                           message='STORES holds node.stores.Store, not %s' % type(s).__name__))
+            continue
+        out.extend(s.problems())
+        if any(s.key in vars(k) for k in cls.__mro__ if k is not object):
+            out.append(ShadowingProblem('STORES', s.key, cls.__name__))
+        if s.persist == stores_mod.SNAPSHOT:
+            persisted.append(s.key)
+    snap = cls.LIFECYCLE.snapshot
+    if persisted and not snap:
+        out.append(IncompatibleProblem(
+            'STORES', ', '.join(persisted),
+            'stores %s persist across a restart, so LIFECYCLE must declare snapshot=N '
+            '(the version of their shape)' % ', '.join(persisted)
+        ))
+    if snap and not persisted and cls.snapshot is base_cls.snapshot:
+        out.append(IncompatibleProblem(
+            'STORES', 'snapshot',
+            'Lifecycle(snapshot=%d) carries nothing: declare a SNAPSHOT store, or snapshot() '
+            'and restore(state)' % snap
+        ))
+    if snap and (cls.snapshot is base_cls.snapshot) != (cls.restore is base_cls.restore):
+        out.append(IncompatibleProblem(
+            'STORES', 'snapshot/restore',
+            'snapshot() and restore(state) come as a pair'
+        ))
+    return out
+
+
+def command_data_problems(cls: type[Any]) -> list[str]:
+    out = Problems()
+    own = {s.key for s in cls.STORES if isinstance(s, stores_mod.Store)}
+    reach = set(cls.requires) | set(cls.uses)
+    for c in cls.COMMANDS:
+        if not isinstance(c, Command):
+            continue
+        for verb, refs in (('reads', c.reads), ('writes', c.writes)):
+            for ref in refs:
+                other, dot, key = ref.partition('.')
+                if not dot and ref not in own:
+                    out.append(ReferenceProblem(
+                        'COMMANDS', f'{c.key}.{verb}', ref,
+                        'command %s %s store %r, which this compartment does not declare' % (c.key, verb, ref)
+                    ))
+                elif dot and verb == 'writes':
+                    out.append(IncompatibleProblem(
+                        'COMMANDS', f'{c.key}.writes',
+                        'command %s writes %s, a store of %s; a command writes only its own '
+                        "compartment's stores - ask %s instead" % (c.key, ref, other, other)
+                    ))
+                elif dot and other not in reach:
+                    out.append(ReferenceProblem(
+                        'COMMANDS', f'{c.key}.reads', other,
+                        'command %s reads %s from %s, which this compartment neither requires nor uses' % (c.key, key, other)
+                    ))
+    return out

node/compartment/need.py

@@ -0,0 +1,158 @@
+"""Declared dependencies a compartment takes from the node."""
+from __future__ import annotations
+
+import dataclasses
+import inspect
+from typing import Any, Mapping, Optional
+
+from .problem import (IncompatibleProblem, Problem, Problems,
+                      ReferenceProblem, TypeMismatchProblem)
+
+
+@dataclasses.dataclass(frozen=True)
+class Need:
+    """One dependency a compartment takes from the node, declared where the
+    compartment is.
+
+    Resolved against NodeContext at assembly by the base `from_context`:
+      - a field (`ks`, `transport`, `stores.grants`, `clock`, `propose`, `pull`, `regrant`, etc.)
+      - a typed config block (`Need('settings', block=SettlementConfig)`)
+      - a compartment, which must appear in `requires` or `uses`, resolved from registry / context
+      - a live config getter (`Need('cfg', 'cfg', getter=True)` or `Need('cfg', block=UpdatesConfig, getter=True)`)
+      - a node-relative path (`Need('db_path', path='DB')` or `Need('db_path', path='updates.sqlite')`)
+      - or `late=True`: resolved and bound after all compartments are assembled, replacing wire().
+    """
+    key: str
+    source: Optional[str] = None
+    block: Optional[type] = None
+    late: bool = False
+    getter: bool = False
+    path: Optional[str] = None
+    field: Optional[str] = None
+
+    def __init__(
+        self,
+        key: str,
+        source: Optional[str] = None,
+        *,
+        block: Optional[type] = None,
+        late: bool = False,
+        getter: bool = False,
+        path: Optional[str] = None,
+        field: Optional[str] = None,
+    ) -> None:
+        object.__setattr__(self, 'key', key)
+        object.__setattr__(self, 'source', source if source is not None else (None if (block is not None or path is not None) else key))
+        object.__setattr__(self, 'block', block)
+        object.__setattr__(self, 'late', late)
+        object.__setattr__(self, 'getter', getter)
+        object.__setattr__(self, 'path', path)
+        object.__setattr__(self, 'field', field)
+
+    def resolve(self, ctx: Any, cls: type) -> Any:
+        if self.late:
+            return None
+        if self.path is not None:
+            rel = getattr(cls, self.path, self.path)
+            return ctx.path(rel)
+        if self.block is not None:
+            if self.getter:
+                return ctx.block_getter(self.block)
+            b = ctx.block(self.block)
+            if self.field is not None:
+                return getattr(b, self.field)
+            return b
+        src = self.source or self.key
+        if self.getter:
+            if src == 'cfg':
+                return ctx.cfg_getter()
+            return lambda: self._resolve_src(ctx, cls, src)
+        res = self._resolve_src(ctx, cls, src)
+        if self.field is not None:
+            if isinstance(res, Mapping):
+                return res.get(self.field)
+            return getattr(res, self.field)
+        return res
+
+    def _resolve_src(self, ctx: Any, cls: type, src: str) -> Any:
+        reqs = getattr(cls, 'requires', ()) or ()
+        uses = getattr(cls, 'uses', ()) or ()
+        if src in reqs or src in uses:
+            return ctx.optional(src)
+        val = ctx
+        for part in src.split('.'):
+            if hasattr(val, part):
+                val = getattr(val, part)
+            elif isinstance(val, Mapping) and part in val:
+                val = val[part]
+            else:
+                raise AttributeError(f"NodeContext has no field {part!r} (resolving {src!r})")
+        return val
+
+    def resolve_late(self, ctx: Any, instance: Any, registry: Any) -> Any:
+        comp_name = self.source or self.key
+        val = registry.get(comp_name)
+        if val is None:
+            val = getattr(ctx, comp_name, None)
+        return val
+
+    def problems(self, cls: type) -> list[str]:
+        out = Problems()
+        if not self.key or not isinstance(self.key, str):
+            out.append(Problem('Need key must be a non-empty string', surface='NEEDS', code='empty_key', target=''))
+            return out
+
+        # Check __init__ parameter (unless late=True)
+        if not self.late:
+            try:
+                init_fn = getattr(cls, '__init__', None)
+                if init_fn is not None:
+                    sig = inspect.signature(init_fn)
+                    params = sig.parameters
+                    has_varkw = any(p.kind == inspect.Parameter.VAR_KEYWORD for p in params.values())
+                    if not has_varkw and self.key not in params:
+                        out.append(IncompatibleProblem(
+                            'NEEDS', self.key,
+                            f"need {self.key!r} is not an __init__ parameter of {cls.__name__}"
+                        ))
+            except (ValueError, TypeError):
+                pass
+
+        if self.path is not None:
+            if not isinstance(self.path, str) or not self.path:
+                out.append(TypeMismatchProblem('NEEDS', 'non-empty str path', type(self.path).__name__,
+                                               message=f"need {self.key!r}: path must be a non-empty string"))
+        elif self.block is not None:
+            blk: object = self.block
+            if not isinstance(blk, type):
+                out.append(TypeMismatchProblem('NEEDS', 'type', type(blk).__name__,
+                                               message=f"need {self.key!r}: block must be a type, got {type(blk).__name__}"))
+        else:
+            src = self.source or self.key
+            reqs = getattr(cls, 'requires', ()) or ()
+            uses = getattr(cls, 'uses', ()) or ()
+            top = src.split('.')[0]
+            from .context import NodeContext
+            known_context_fields = set(NodeContext.__dataclass_fields__.keys()) | {
+                'pubkey', 'did', 'node_class',
+            }
+            if top in known_context_fields:
+                if top == 'stores' and '.' in src:
+                    store_field = src.split('.')[1]
+                    from .context import NodeStores
+                    if store_field not in NodeStores._fields:
+                        out.append(ReferenceProblem(
+                            'NEEDS', self.key, store_field,
+                            message=f"need {self.key!r}: stores has no field {store_field!r} (declared: {', '.join(NodeStores._fields)})"
+                        ))
+            elif self.late:
+                pass  # late needs can name any compartment built after this one
+            elif src in reqs or src in uses:
+                pass  # valid declared dependency
+            else:
+                out.append(ReferenceProblem(
+                    'NEEDS', self.key, src,
+                    message=f"need {self.key!r}: source {src!r} is neither a NodeContext field nor in requires/uses"
+                ))
+        return out
+