Source code for fleetmesh_node.commands.plugin_cmds

"""`plugin-check REF`: the conformance check a plugin author runs before an
operator ever lists the plugin in a config. No node, no keys: the module is
imported and the class is held to exactly the rules `fleetmesh_node/app/core.py`
applies at startup (`load_plugins`, the PIURI origin rule, `plugin_sidecars`)
and `fleetmesh_node/commands` applies to its verbs - the same functions, not a copy of
them, so the check cannot drift from the node. Exit 0 when every rule holds,
1 when one does not (each failure on its own line), 2 when REF cannot be
imported at all."""
from __future__ import annotations

import argparse
import json
from typing import Optional, TypedDict

from .. import compartment as compartment_mod
from ..planes.services.sidecars.manifest import SidecarDict
from fleetmesh_core.identity import origin as origin_mod
from .base import fail


[docs]class Declares(TypedDict, total=False): builtin: bool after: str piuris: list[str] sidecars: list[SidecarDict] cli: list[str]
[docs]class Report(TypedDict): ref: str name: Optional[str] ok: bool findings: list[str] declares: Declares
NOT_CONFORMANT = 1 NOT_IMPORTABLE = 2
[docs]def check_plugin(ref: str) -> Report: """Every rule, as {'ref', 'ok', 'name', 'findings': [..], 'declares': {...}}. Raises ValueError when the ref does not import (nothing else to say).""" from ..app import core as core_mod from . import PROVIDERS, _import_ref cls = _import_ref(ref) findings: list[str] = [] declares: Declares = {} # 1. the subsystem/1 declaration, held to the same rules as at startup. # A built-in is checked as if it were a plugin spliced in where it ships: # the manifest without it is the base, its predecessor the anchor. So # "plugin" means who shipped the class, not a different set of rules. builtin = cls in core_mod.MANIFEST declares['builtin'] = builtin base = tuple(c for c in core_mod.MANIFEST if c is not cls) after = None if builtin: i = core_mod.MANIFEST.index(cls) after = str(core_mod.MANIFEST[i - 1].name) if i else None try: from ..config.compartments import PluginSpec if builtin and after is None: manifest = (cls,) + base else: manifest = core_mod.load_plugins([PluginSpec(ref=ref, after=after)], base) declares['after'] = str(manifest[manifest.index(cls) - 1].name) if manifest.index(cls) else '-' except ValueError as e: findings.append(str(e)) api = getattr(cls, 'api', None) if api != compartment_mod.Compartment.API: findings.append('api is %r; this node speaks %s' % (api, compartment_mod.Compartment.API)) if not callable(getattr(cls, 'from_context', None)): findings.append('no from_context(ctx) constructor') for attr in ('requires', 'uses'): for dep in getattr(cls, attr, ()) or (): if dep not in {c.name for c in core_mod.MANIFEST}: findings.append('%s names %r, which is not a compartment' % (attr, dep)) # 2. dialects: its own origin piuris = list(getattr(cls, 'piuris', ()) or ()) declares['piuris'] = piuris builtin = cls in core_mod.MANIFEST for piuri in piuris: # A built-in speaks fleetmesh.org's protocols by definition; the # origin rule is for plugins, which speak their own. if not builtin and origin_mod.reserved(piuri, core_mod.validate.FLEETMESH_ORIGIN): findings.append('claims the reserved-origin protocol %s; plugins speak their own origin' % piuri) if piuris and not callable(getattr(cls, 'handle', None)): findings.append('declares piuris but no handle(inbound)') # 3. sidecars: manifests that lint, under their own origin try: declares['sidecars'] = [s.to_dict() for s in core_mod.plugin_sidecars(cls)] except ValueError as e: findings.append(str(e)) # 4. CLI verbs: none that a core command owns parser = argparse.ArgumentParser(prog='meshnode') sub = parser.add_subparsers(dest='cmd') for p in PROVIDERS: p.register(sub) verbs = [v for v, _ in (getattr(cls, 'cli', None) or ())] declares['cli'] = verbs for verb in verbs: if verb in sub.choices: findings.append('command %r already exists in meshnode' % verb) return {'ref': ref, 'name': getattr(cls, 'name', None), 'ok': not findings, 'findings': findings, 'declares': declares}
[docs]def cmd_plugin_check(a: argparse.Namespace) -> int: try: r = check_plugin(a.ref) except ValueError as e: fail(str(e), NOT_IMPORTABLE) if a.json: print(json.dumps(r, indent=2)) else: d = r['declares'] print('%s (%s%s): %s' % (r['ref'], r['name'], ', built-in' if d.get('builtin') else '', 'conformant' if r['ok'] else 'NOT conformant')) if 'after' in d: print(' ticks after %s' % d['after']) print(' dialects %s' % (', '.join(d.get('piuris') or []) or '-')) print(' sidecars %s' % (', '.join('%s (%s)' % (s['name'], s['capability']) for s in d.get('sidecars') or []) or '-')) print(' cli verbs %s' % (', '.join(d.get('cli') or []) or '-')) for f in r['findings']: print(' FAIL %s' % f) return 0 if r['ok'] else NOT_CONFORMANT
[docs]class PluginCommandProvider: """Registers plugin-check."""
[docs] @classmethod def register(cls, sub: argparse._SubParsersAction) -> None: p = sub.add_parser('plugin-check', help='hold a plugin class to the rules the node applies at startup, with no node (for plugin authors)') p.add_argument('ref', help='package.module:Class, importable from here') p.add_argument('--json', action='store_true', help='print the result as JSON') p.set_defaults(fn=cmd_plugin_check)