Skip to content

Latest commit

 

History

History
413 lines (333 loc) · 22.5 KB

README.md

File metadata and controls

413 lines (333 loc) · 22.5 KB

@netscript/plugin

JSR CI Docs

The plugin authoring contract for NetScript: a fluent definePlugin builder producing type-safe manifests that host tooling turns into runtime files, services, and Aspire resources.

Every NetScript plugin — workers, sagas, triggers, streams, auth, AI, and yours — is at its core a manifest: plain, validated data declaring what the plugin contributes to an app. This package is where that contract lives. definePlugin gives authors a chainable, type-narrowing builder; inspectPlugin and verifyPlugin give hosts and tests a way to interrogate any manifest without executing it. If you are building a plugin or a tool that consumes plugins, this is the package you build against.

Because manifests are data, the whole ecosystem stays inspectable: the CLI scaffolds from them, Aspire wiring is generated from them, and marketplace tooling reads them — all without running plugin code.

Why authors use it

  • A builder that catches mistakes at compile time — definePlugin(name, version) returns a chainable, type-narrowing PluginBuilder; .build() yields a schema-validated PluginManifest with typed PluginError classes for invalid or duplicate definitions.
  • A rich contribution vocabulary — declare services, background processors, stream topics, database schemas, migrations, runtime-config topics, and telemetry as typed contribution axes.
  • Typed cross-plugin dependencies — .withDependencies({...}) registers sibling plugins by alias and threads a DependencyContext into contribution callbacks.
  • Inspection without execution — inspectPlugin returns a JSON-stable report for a manifest, registry, or path target; verifyPlugin checks a manifest against declared expectations.
  • One service identity contract — Principal and ServiceHandlerContext are owned by @netscript/service; the plugin root and ./service entrypoint re-export those same types rather than defining plugin-local copies.
  • Focused subpaths for every consumer — host tooling, CLI command groups, discovery, abstract bases, protocol, templates, and test fixtures each get their own entrypoint, so nobody imports more than they need.

Architecture

flowchart LR
    A["Plugin author<br/>definePlugin(...).build()"] --> M["PluginManifest<br/>(validated data)"]
    M --> C["NetScript CLI<br/>install · sync · doctor"]
    M --> G["Generated wiring<br/>files · registries · Aspire"]
    M --> I["inspectPlugin / verifyPlugin<br/>(tests, tooling, marketplace)"]
Loading

Install

deno add jsr:@netscript/plugin@<version>

Pin <version> to match your installed CLI; bare jsr:@netscript/* specifiers do not resolve on the pre-release line.

Quick example

import { definePlugin, inspectPlugin } from '@netscript/plugin';

const plugin = definePlugin('@example/billing', '0.0.1-alpha.0')
  .withDescription('Billing service and invoice processor.')
  .withService({
    name: 'billing-api',
    entrypoint: 'services/api/main.ts',
  })
  .build();

console.log(inspectPlugin(plugin).summary);

Contribution methods such as .withService(...) accumulate plain data; .build() validates the whole manifest at once, so a malformed contribution fails the build with a typed error rather than surfacing later inside a host.

Service identity types

Plugin authors can import service identity types from the plugin surface when a contribution names them directly:

import type { Principal, ServiceHandlerContext } from '@netscript/plugin';

type BillingContext = ServiceHandlerContext<{ readonly tenantId: string }>;

function requirePrincipal(context: BillingContext): Principal {
  if (!context.principal) {
    throw new Error('authenticated principal required');
  }
  return context.principal;
}

These are re-exports of the public @netscript/service contracts. The service package remains the owner, and ServiceHandlerContext.principal remains optional so unguarded handlers and existing plugin services are unaffected. Narrow the principal in handlers that require identity; do not add a second plugin-specific principal shape.

Background child health

@netscript/plugin/health exports ChildHealthState, ChildHealthSnapshot, ChildFatalError, ChildHealthMonitor, CHILD_CRASH_LOOP_THRESHOLD, childHealthResponse, and runChildHealthProcess.

import { ChildHealthMonitor } from '@netscript/plugin/health';

const health = new ChildHealthMonitor();
health.registryLoaded();
health.dependenciesReady();
health.running();
console.log(health.snapshot().state); // ready

The closed state vocabulary is starting | ready | degraded | crash-looping | stopped | failed. The payload also reports registryReady, dependencyReady, cumulative restartCount, and lastFatalError (a fixed redacted message plus an epoch-millisecond timestamp, or null). Registry readiness means the generated definitions were loaded and validated. Dependency readiness includes runtime registration, startup checks, and listener failures, rather than a continuous backing-service heartbeat.

By default, three restarts within 60 seconds, including the window boundary, latch crash-looping. Recovery requires a full 60 seconds of uninterrupted running with both readiness fields true; a brief retry cannot turn the child green. A new failure resets the clean window, and clean shutdown reports stopped. Restart history retains at most the configured number of timestamps. Health responses return HTTP 200 only for ready with both readiness fields true; all other states return HTTP 503. Raw exception messages, stacks, credentials, and definition data never enter this payload.

Generated sagas and triggers retain this history across process replacements in .data/child-health/sagas.json and .data/child-health/triggers.json, relative to the background service's working directory. The project already ignores .data/. The first boot does not count as a restart. A recorded fatal failure counts on the next boot, including Deno watch reloads in the same OS process. An unclean replacement with a different process identity also counts. Ordinary healthy watch reloads and a restart after clean shutdown do not count. At the third restart in the window, /health reports crash-looping and HTTP 503 during bootstrap and after brief successful starts. A single failed boot followed by stable running stays ready.

Configure the threshold through the health monitor options and pass the same monitor to runtime and process transport:

import { ChildHealthMonitor, runChildHealthProcess } from '@netscript/plugin/health';

const health = new ChildHealthMonitor(Date.now, {
  crashLoopThreshold: { restarts: 5, windowMs: 120_000 },
});
await runChildHealthProcess(
  async (monitor, signal) => {
    monitor.registryLoaded();
    monitor.dependenciesReady();
    monitor.running();
    await new Promise<void>((resolve) => {
      if (signal.aborted) resolve();
      else signal.addEventListener('abort', () => resolve(), { once: true });
    });
  },
  undefined,
  { health, restartHistoryPath: '.data/child-health/custom.json' },
);

Both threshold values must be positive; the restart count must be a safe integer and the window must be finite. TriggerHealthMonitor accepts the same options as its second constructor argument. Each history path has one process owner: replicas need separate paths on persistent local storage. The service needs read/write access to the parent directory. FileChildRestartHistory atomically replaces a versioned record, storing only process identity, failure status, bounded timestamps and restart accounting. A missing record means first boot; corrupt, oversized or unwritable history fails health closed. Storage loss resets process history, so ephemeral filesystems and distributed replica detection are outside this local guarantee. Healthy polling reads memory; it does not read the filesystem. A complete live ready window clears the stored latch; downtime never counts as recovery. Workers retain their existing in-process listener restart budget and health behavior.

To extend storage, implement the synchronous ChildRestartHistoryPort and call health.trackProcess(history, processId) before bootstrap. Synchronous writes ensure abrupt termination cannot skip a pending accounting write. Read this section as the contributor entry point, then run the generated-process regressions in tests/health/generated-crash-loop_test.ts.

Generated workers, triggers, and sagas glue starts the health listener before bootstrap. The listener binds 127.0.0.1 by default. PORT selects the port; without it, the operating system assigns an ephemeral port. Pass ChildHealthProcessOptions.hostname: '0.0.0.0' when container health checks must reach the listener from another network namespace. Generated workers, sagas and triggers forward NETSCRIPT_CHILD_HEALTH_HOSTNAME to that option, so a container launch can set it to 0.0.0.0 without editing generated glue. Leave it unset for loopback probes, including the generated Aspire executable launches.

On a stop signal, runChildHealthProcess gives work 30 seconds to drain and reserves five more seconds for onShutdown resource callbacks and the health listener. drainTimeoutMs bounds the whole shutdown (default 35_000); cleanupTimeoutMs reserves part of that total (default min(5_000, drainTimeoutMs / 5)). Every cleanup is attempted even if work or another cleanup hangs. Generated roles close the shared KV/Redis connection with closeKv() and dispose database clients actually acquired by the host bootstrap, without opening unused clients during shutdown.

Exit codes are 0 for a clean drain, 1 for a fatal runtime or cleanup failure, and 2 when work or cleanup exceeds its deadline. Fatal bootstrap causes are logged to stderr and remain visible as red health for one second before shutdown begins. exitOnShutdown: false leaves termination to an embedding host: clean shutdown returns and failures reject with PluginError.

The optional PluginServiceContext.dispose callback belongs to the host. The context factory memoizes it but never closes lazy KV or database accessors implicitly. A service signal runs that callback in the reserved cleanup phase. Manual service stop and external cancellation leave process-owned disposal to the embedding host.

Public surface

Entry What it gives you
. definePlugin, PluginBuilder, inspectPlugin, verifyPlugin, Principal, ServiceHandlerContext, the manifest schema, and the typed error classes
./health Background child state, bounded restart policy, and the child HTTP health transport
./adapter The adapter seam deployable plugins expose and hosts drive
./config Configuration surfaces for host tooling
./cli Plugin CLI command-group plumbing and argument parsing
./sdk Plugin discovery for external tooling
./contract-base The base oRPC contract every plugin API contract extends
./abstracts Abstract bases marking plugin extension points
./testing Fixtures for exercising manifests and adapters in tests
./loader The host-side plugin loader entrypoint
./service Plugin service composition plus the service-owned Principal and ServiceHandlerContext types

The always-current symbol list is deno doc jsr:@netscript/plugin@<version> (pin <version> on the pre-release line, as above).

Validate a root composition

Hosts compose many manifests. validatePluginComposition rejects duplicate plugin names, unknown contribution keys, colliding contribution identities, and missing or version-mismatched dependencies. It returns structured diagnostics instead of throwing. createPluginHostBootstrap, the CLI host loader, and netscript generate aspire run the same check, so you do not need your own axis allowlist.

import { definePlugin, validatePluginComposition } from '@netscript/plugin/config';

const result = validatePluginComposition([
  definePlugin('@example/a', '1.0.0').withService({ name: 'api', entrypoint: './a.ts' }).build(),
  definePlugin('@example/b', '1.0.0').withService({ name: 'api', entrypoint: './b.ts' }).build(),
]);

if (!result.ok) {
  for (const diagnostic of result.diagnostics) console.error(diagnostic.code, diagnostic.message);
}

Breaking: unknown contribution keys now fail validation; they are no longer ignored. Rename a misspelled key to the documented one. The per-key identity and scope rules are listed in the plugin reference.

Extend SDK discovery

Each plugin owns its discovery declaration. Its generated control-plane module exports the factory name and registry axis that AstExtractor reads from the same files it already walks:

export const NETSCRIPT_CONTRIBUTION_BUILDERS = [
  { callee: 'defineChannelSync', axis: 'channel-syncs' },
] as const;

External tooling can also add a plugin's contribution factory to one discovery run without changing source files:

import { type AstExtractorOptions, startWalker } from '@netscript/plugin/sdk';

const options = {
  additionalBuilders: [
    { callee: 'defineChannelSync', axis: 'channel-syncs' },
  ],
} satisfies AstExtractorOptions;

const registries = await startWalker('.', options);

Official core packages publish factory-owned patterns at their /discovery subpath. The CLI composes these patterns through additionalBuilders before walking any project; install and sync render each plugin's control-plane declaration from the same metadata. The generic SDK contains no plugin-specific factory table. Published core dependencies are not walked. Additional mappings are snapshotted per extractor instance. Malformed identifiers, blank axes, conflicting declarations for a callee, and a recognizable contribution factory call without a matching declaration throw a TypeError instead of silently omitting contributions.

This changes the migration boundary for projects scaffolded before 0.0.7: re-run plugin sync or update so each installed plugin's control-plane module receives its declaration before using no-argument discovery. Updates validate the staged, regenerated modules, so older workers and triggers installations can acquire their missing declarations during the update itself. Passing additionalBuilders is the explicit compatibility path when regeneration is not available.

Core-only hosts and schema maps

A host using the published @netscript/plugin-sagas-core in-process does not need a saga plugin service. Put this literal declaration in a TypeScript module inside the walked project, for example discovery.ts at the project root. It need not be imported by the application. Discovery reads source text; it does not traverse published dependency imports to find metadata.

export const NETSCRIPT_CONTRIBUTION_BUILDERS = [
  { callee: 'defineSaga', axis: 'sagas' },
  { callee: 'defineStreamSchema', axis: null },
] as const;

defineSaga produces an id-bearing definition for the sagas registry. defineStreamSchema returns a collection schema map consumed by the durable stream producer; it has no contribution id. axis: null explicitly declares a non-registry factory: discovery validates its declaration and excludes its values before the id-based registry emitter. Do not invent a schema axis or an id. The streams control-plane module now emits this exclusion during installation. Identical metadata from a host and a control module is accepted; conflicting axes still fail. Tooling can also pass either declaration through additionalBuilders.

The CLI supplies first-party metadata even for core-only hosts and older installed control modules. Single-plugin updates succeed in either order: plugin update streams then plugin update workers, or workers then streams. No bulk update or host workaround is required. Standalone SDK tooling still passes the core package patterns through additionalBuilders or supplies literal declarations. plugin update runs installation in an isolated copy of the project, then walks that updated tree and resolves every registry emission before applying changes to the live project. New declarations and contribution files participate in the same walk. An undeclared factory, malformed declaration, or extraction/emission failure leaves existing files byte-identical and creates no installation files in the live project. The temporary tree is removed on success or failure. This guarantee covers discovery failures; applying files retains normal filesystem error behavior.

SDK compatibility: ContributionBuilderPattern.axis is now string | null; tooling reading this property must narrow axis !== null before using it as a string.

Docs

Compatibility

Manifests and the builder are plain TypeScript — importable in any TypeScript environment, including Node.js and Bun via JSR's npm compatibility. The loader and CLI plumbing target Deno 2.9+, matching the NetScript hosts that consume them.

License

Apache-2.0 — see LICENSE. Published to JSR with cryptographically verified provenance.

Explicit service authentication

createPluginService requires auth. Guarded services pass native service-auth options; JavaScript callers receive a TypeError for missing or ambiguous policies before a builder is constructed. TypeScript callers must migrate their service configuration.

import { assemblePluginContractRouter, createPluginService } from '@netscript/plugin/service';
import { createAuthServiceAuthenticator } from '@netscript/plugin-auth/authenticator';
import { createContractAuthorizer } from '@netscript/service/auth';
import { mountPluginContract } from '@netscript/plugin/contract-base';
import { baseContract, SuccessSchema } from '@netscript/contracts';
import { implement } from '@orpc/server';

const contract = {
  list: baseContract.route({ method: 'GET', path: '/reports' }).output(SuccessSchema)
    .meta({ access: { authentication: 'required', authorization: { scopes: ['reports:read'] } } }),
};
const contractMount = { version: 'v1', namespace: 'reports' };
const implementation = implement(contract);
const router = assemblePluginContractRouter(implementation, {
  ...contractMount,
  handlers: { list: implementation.list.handler(() => ({ success: true })) },
});

const service = createPluginService(router, {
  name: 'reports',
  auth: {
    authn: {
      authenticator: createAuthServiceAuthenticator({ serviceName: 'auth', timeoutMs: 10_000 }),
    },
    authz: { authorizer: createContractAuthorizer(mountPluginContract(contract, contractMount)) },
  },
});

The contract must declare the required access metadata, and the plugin must declare its auth service dependency. The builder resolves procedure policy across REST and RPC; do not infer a procedure's required scope from the transport's HTTP method.

contractMount is the same { version, namespace } value used to assemble the router. mountPluginContract prefixes REST paths and nests RPC keys without changing the source contract, its access metadata, or its errors. Passing the flat contract to the authorizer would deny mounted requests because their paths differ. The generator exports one mount constant in handlers.ts and shares it with the authorizer; preserve that single authority when adapting the scaffold.

For a deliberately public service, record the reason instead:

import { createPluginService } from '@netscript/plugin/service';

const service = createPluginService({}, {
  name: 'public-health',
  auth: { public: true, reason: 'Public health service without protected operations' },
});

Never combine public and guarded fields. Public reasons must be nonblank. Options pass through unchanged: a custom nonempty allowAnonymous list replaces the native default. The builder's built-in health routes remain public because they are registered before auth middleware; raw routes are installed after it and follow the configured guards.

The existing first-party public declarations record unfinished adoption, not proof that those services are guarded. Their credential propagation, session seeding, per-service access policy and auth discovery work remain under #1383; auth signout authorization remains under #1384. This source change does not imply availability in an existing published package.