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