Plugin SDK

A plugin extends Nistor without changing it. There are two sides: the server (Python) and the web shell (JavaScript).

Server side#

A plugin is a Python package, nistor-plugin-<id>, that declares entry points in its pyproject.toml. Installing it is enough to activate it. The groups include:

A usage reporter receives one whole clock hour at a time: once per hour, and again for an hour whose report failed. It is built once per process and called from one thread with a deadline, so it should bound its own calls. A reporter installed in an image that gives it no destination answers False from an optional configured(): it is then not called, and when no installed reporter is configured nothing is collected. Meter with these semantics:

• the same hour can arrive more than once (a restart, several jobs instances, a retry): keep the latest report per deployment and window start;
• hours arrive in order, oldest first. A reporter whose report() raises (a failed or timed-out publish) gets that hour again at the next hourly cycles, before any later one, without holding back the other reporters; so raise on a failed publish rather than swallow it. A retry after a partial success is safe, since the latest report wins;
• hours are not guaranteed contiguous, but gaps come only from a new process, which starts from the last whole hour, from the catch-up cap (an hour more than a day old is dropped, with a warning), and, for one reporter, from the hours its plugin was held (read-only or inactive), which are skipped on purpose and never sent later;
• a run counts in the hour it was created, under its state at report time, so a run still running is counted as running. Shadow runs, test runs, retries and externally triggered runs all count as runs;
• the node counts, the active plugins and the active users of the last 24 hours are taken at report time.

The manifest declares requires_core_api, a version specifier checked against the core's API version at load time. A plugin the running core cannot satisfy is reported and skipped; it does not stop the server. Separately, set NISTOR_PLUGIN_VALIDATION=strict to make an executor plugin that fails validation a startup error. The range's lower bound is the minor that added the newest core name, contract or field the plugin uses: nistor_testing.core_api_floors records what each minor added, and floor_problems(plugin_id, requires, package_needs(package_dir)) returns the problems for a range that starts lower (empty when it does not).

A plugin may import nistor_core and the tool contract. It may not import a tool or the server's internal modules. nistor-testing has a plugin kit (nistor_testing.plugin_kit) that checks a plugin's manifest the way the tool kit checks a tool's. Its uninstall rehearsal (keep, then a reinstall, finds the plugin's data again) is opt-in: set uninstall_rehearsal = True on your PluginConformance subclass; it needs a test database, as the symmetry check does.

Web shell#

@nistor-io/plugin-sdk is the API a shell plugin builds against: slot definitions, the plugin registry, API client helpers, authentication, capabilities, navigation and a few generic hooks. @nistor-io/ui is the design system.

• A plugin registers slot items (a page, a navigation entry, a panel) in the slots the shell exposes.
• A plugin is built as a Module Federation remote, which the shell loads at runtime. The server side points to it through the nistor.ui entry point.
• @nistor-io/ui may import the SDK; the SDK never imports @nistor-io/ui.

cd web && npm ci

The SDK's README.md (web/plugin-sdk/README.md) lists its exports and the testing helpers.

Compatibility#

The SDK and the contracts follow Versioning: a minor release may add, a major release may remove after one minor of deprecation.