@syncbridge/common 1.1.4 → 2.0.1

package/README.md

@@ -1 +1,192 @@
-# SyncBridge Common Library
+# @syncbridge/common
+
+What a SyncBridge module is written against. A module is an npm package
+of **components** - clients, servers, connections - and **apps**, which
+SyncBridge runs as workers, each a Node.js process of its own, made of
+components. This package gives you the decorators that describe them, the
+base classes they extend, and their lifecycle.
+
+```sh
+npm i -D @syncbridge/common
+```
+
+SyncBridge provides `@syncbridge/common` to every module it runs, so a
+module declares it in `peerDependencies`, never in `dependencies`:
+
+```json
+"peerDependencies": { "@syncbridge/common": "^2.0.0" }
+```
+
+Start a module with `npx @syncbridge/syncbuild init @vendor/name`
+([`@syncbridge/syncbuild`](https://www.npmjs.com/package/@syncbridge/syncbuild)),
+and test it with
+[`@syncbridge/testing`](https://www.npmjs.com/package/@syncbridge/testing).
+
+## A component
+
+A component is a class that extends `ComponentBase`, decorated with
+`@Component`. Its settings - shown in SyncBridge's UI and kept in the
+worker's profile - are a variables class, given with `UseVariables`:
+
+```ts
+import {
+  Component,
+  ComponentBase,
+  DefineVariable,
+  VariableType,
+} from '@syncbridge/common';
+
+export class WeatherClientVariables {
+  @DefineVariable({ label: 'API address', required: true })
+  declare url: string;
+
+  @DefineVariable({ label: 'API key', type: VariableType.Secret })
+  declare apiKey?: string;
+
+  @DefineVariable({ label: 'Interval (s)', default: 60, minValue: 5 })
+  declare interval: number;
+}
+
+@Component({
+  displayName: 'Weather client',
+  description: 'Reads the weather from a web service',
+  tags: ['weather', 'http'],
+})
+export class WeatherClientComponent extends ComponentBase {
+  @Component.UseVariables()
+  declare values: WeatherClientVariables;
+
+  protected async _start(abortSignal?: AbortSignal): Promise<void> {
+    await super._start(abortSignal);
+    this.logger?.info(`Reading ${this.values.url}`);
+  }
+
+  protected async _stop(): Promise<void> {
+    /* Close what _start opened */
+    await super._stop();
+  }
+}
+```
+
+An element's URI is `<package>:<className>`. A component's class name is
+its class's without `Component` (`@acme/weather:WeatherClient`); an app's
+is its class's (`@acme/weather:WeatherStationApp`). Give `className` to
+choose another.
+
+## An app
+
+An app extends `AppBase`, decorated with `@App`. It names the components it
+uses with `UseComponent`, by URI. SyncBridge creates them with the values the
+worker's profile gives, and starts them before the app:
+
+```ts
+import { App, AppBase, DefineVariable } from '@syncbridge/common';
+import type { WeatherClientComponent } from './weather-client.component.js';
+
+export class WeatherStationVariables {
+  @DefineVariable({ label: 'Station name', default: 'Station 1' })
+  declare name: string;
+}
+
+@App({ displayName: 'Weather station' })
+export class WeatherStationApp extends AppBase {
+  @App.UseVariables()
+  declare values: WeatherStationVariables;
+
+  @App.UseComponent({
+    uri: '@acme/weather:WeatherClient',
+    required: true,
+  })
+  declare readonly weather: WeatherClientComponent;
+
+  protected async _start(abortSignal?: AbortSignal): Promise<void> {
+    await super._start(abortSignal);
+    this.logger?.info(`${this.values.name} started`);
+  }
+}
+```
+
+A component may use components too, with `Component.UseComponent`. A URI
+can name another module's component, for example
+`@syncbridge/net:TcpClient`. Declare that module as a peer as well.
+
+## Variables
+
+`@DefineVariable` describes a setting. Its type is read from the
+property's TypeScript type when not given. Some options:
+
+| Option | Meaning |
+| --- | --- |
+| `label`, `description` | How it is shown |
+| `type` | `VariableType`: `String`, `Secret` (a password or key, kept encrypted in the profile), `Number`, `BigInt`, `Boolean`, `Enum`, `Nested` |
+| `default`, `required` | Its default value, and whether it must be given |
+| `enumValues` | The values of an enum |
+| `enumSource` | Values SyncBridge fills in from the server it runs on: `EnumSource.SerialPorts`, `EnumSource.NetworkAddresses` |
+| `format`, `pattern` | A string's format (`url`, `email`, `date-time`...) or pattern |
+| `minValue`, `maxValue` | A number's range |
+| `isArray` | A list of values |
+| `hotPlug` | A change applies while running, without a restart |
+| `index` | Its order in the UI |
+
+## Lifecycle
+
+Apps and components are `Runnable`s. Override the protected methods, and
+always call `super`:
+
+- `_init()`: once, before the first start.
+- `_start(abortSignal)`: start working. The signal aborts when a stop comes
+  while starting.
+- `_stop()`: stop, and release what `_start` took. Close every timer,
+  socket and pool: what is left open is logged as a warning when the
+  worker ends.
+- `_restart()`: stop and start in place, for example when values change.
+
+`status` is a `ServiceStatus`: `stopped`, `starting`, `started`,
+`unhealthy`, `stopping`. Report trouble with
+`this.setStatus(ServiceStatus.unhealthy, message)`. An app's status
+follows its components'.
+
+## Logging
+
+`this.logger` writes the element's log. A log channel is a log of its own
+that the user can turn on, filter and keep apart, such as what a
+connection sends and receives:
+
+```ts
+import { LogChannel } from '@syncbridge/common';
+
+@LogChannel({ name: 'communication', title: 'Communication', kind: 'transmit' })
+declare readonly ioLog: LogChannel;
+
+// later
+this.ioLog.info('Sent', { bytes: 42 });
+```
+
+## Permissions
+
+SyncBridge runs each worker as a Linux user of its own, under Node's
+permission model. A component or app that needs more than its own data
+directory declares it:
+
+```ts
+@Component({
+  displayName: 'Serial client',
+  permissions: [WorkerPermission.SerialPorts, WorkerPermission.NativeCode],
+})
+```
+
+- `SerialPorts`: the serial devices.
+- `NativeCode`: native addons (`.node`), such as `serialport` or `oracledb`.
+- `ChildProcesses`: starting other programs.
+
+A subclass has its base's permissions. `spm verify` runs a module under
+the permission model and tells you what it failed to declare.
+
+## Examples
+
+The modules SyncBridge ships are open source:
+[syncbridge-io/public-modules](https://github.com/syncbridge-io/public-modules).
+
+## License
+
+[MIT](LICENSE)

package/app-factory.d.ts

@@ -0,0 +1,29 @@
+import { AppBase } from './classes/app-base.js';
+import { StackExecutor } from './classes/stack-executor.js';
+import type { LogChannel } from './decorators/log-channel.decorator.js';
+import type { ILogger } from './interfaces/index.js';
+import { Profile } from './models/index.js';
+export declare namespace AppFactory {
+    const METADATA_KEY: unique symbol;
+    const PROFILE_KEY: unique symbol;
+    interface AppOptions {
+        logger?: ILogger;
+        dataDirectory?: string;
+        /** Where the log channels hand their records; without it they drop them */
+        logSink?: LogChannel.Sink;
+    }
+    function createApp<T extends AppBase>(profile: Profile, options?: AppOptions): Promise<T>;
+    function createAppSilent<T extends AppBase>(profile: Profile, options?: AppOptions): Promise<{
+        result: true;
+        app: T;
+        issues: StackExecutor.Issue[];
+    } | {
+        result: false;
+        issues: StackExecutor.Issue[];
+    }>;
+    function updateApp(app: AppBase, profile: Profile, options?: AppOptions): Promise<void>;
+    function updateAppSilent(app: AppBase, profile: Profile, options?: AppOptions): Promise<{
+        result: boolean;
+        issues: StackExecutor.Issue[];
+    }>;
+}

package/{processor-factory.js → app-factory.js}

@@ -1,21 +1,22 @@
 import { clone } from '@jsopen/objects';
 import equal from 'fast-deep-equal';
+import { AppBase } from './classes/app-base.js';
 import { ComponentBase } from './classes/component-base.js';
-import { ProcessorBase } from './classes/processor-base.js';
+import { LogChannelWriter } from './classes/log-channel-writer.js';
 import { SbError, SbValidationError } from './classes/sb-error.js';
 import { StackExecutor } from './classes/stack-executor.js';
-import { ElementComponentMetadataRecord, ProcessorMetadata, Profile, ProfileComponentRecord, VariableMetadataRecord, } from './models/index.js';
+import { AppMetadata, ElementComponentMetadataRecord, Profile, ProfileComponentRecord, VariableMetadataRecord, } from './models/index.js';
 import { initializeModelsDocument } from './models-document.js';
 import { ExtensionRegistry } from './registry/extension-registry.js';
 import { decodeProfileSilent } from './utils/decode-profile.js';
-export var ProcessorFactory;
-(function (ProcessorFactory) {
-    ProcessorFactory.METADATA_KEY = Symbol('METADATA');
-    ProcessorFactory.PROFILE_KEY = Symbol('PROFILE');
-    async function createProcessor(profile, options) {
-        const r1 = await createProcessorSilent(profile, options);
+export var AppFactory;
+(function (AppFactory) {
+    AppFactory.METADATA_KEY = Symbol('METADATA');
+    AppFactory.PROFILE_KEY = Symbol('PROFILE');
+    async function createApp(profile, options) {
+        const r1 = await createAppSilent(profile, options);
         if (!r1.result) {
-            const msg = 'Error while creating processor.\n  ' +
+            const msg = 'Error while creating app.\n  ' +
                 r1.issues
                     .map(issue => `- ${issue.message}. Location: /${issue.location}`)
                     .join('\n  ');
@@ -27,19 +28,19 @@ export var ProcessorFactory;
                 issues: r1.issues,
             });
         }
-        return r1.processor;
+        return r1.app;
     }
-    ProcessorFactory.createProcessor = createProcessor;
-    async function createProcessorSilent(profile, options) {
+    AppFactory.createApp = createApp;
+    async function createAppSilent(profile, options) {
         const ctx = {
             stackExecutor: new StackExecutor(),
-            processor: undefined,
+            app: undefined,
             profile,
             options,
         };
         try {
             await initializeModelsDocument();
-            if (!(await _configureProcessor(ctx))) {
+            if (!(await _configureApp(ctx))) {
                 return {
                     result: false,
                     issues: ctx.stackExecutor.issues,
@@ -47,7 +48,7 @@ export var ProcessorFactory;
             }
             return {
                 result: true,
-                processor: ctx.processor,
+                app: ctx.app,
                 issues: ctx.stackExecutor.issues,
             };
         }
@@ -66,11 +67,11 @@ export var ProcessorFactory;
             };
         }
     }
-    ProcessorFactory.createProcessorSilent = createProcessorSilent;
-    async function updateProcessor(processor, profile, options) {
-        const r1 = await updateProcessorSilent(processor, profile, options);
+    AppFactory.createAppSilent = createAppSilent;
+    async function updateApp(app, profile, options) {
+        const r1 = await updateAppSilent(app, profile, options);
         if (!r1.result) {
-            const msg = 'Error while updating processor.\n  ' +
+            const msg = 'Error while updating app.\n  ' +
                 r1.issues
                     .map(issue => `- ${issue.message}. Location: /${issue.location}`)
                     .join('\n  ');
@@ -83,20 +84,20 @@ export var ProcessorFactory;
             });
         }
     }
-    ProcessorFactory.updateProcessor = updateProcessor;
-    async function updateProcessorSilent(processor, profile, options) {
+    AppFactory.updateApp = updateApp;
+    async function updateAppSilent(app, profile, options) {
         if (options?.logger)
-            processor.logger = options.logger;
+            app.logger = options.logger;
         if (options?.dataDirectory)
-            processor.dataDirectory = options.dataDirectory;
+            app.dataDirectory = options.dataDirectory;
         const ctx = {
             stackExecutor: new StackExecutor(),
-            processor,
+            app,
             profile,
             options,
             valueUpdates: new Map(),
         };
-        if (!(await _configureProcessor(ctx))) {
+        if (!(await _configureApp(ctx))) {
             return {
                 result: false,
                 issues: ctx.stackExecutor.issues,
@@ -113,14 +114,14 @@ export var ProcessorFactory;
                 await obj.emitAsyncSafe('values-updated', properties);
             }
         };
-        await signalUpdates(processor);
+        await signalUpdates(app);
         return {
             result: true,
             issues: ctx.stackExecutor.issues,
         };
     }
-    ProcessorFactory.updateProcessorSilent = updateProcessorSilent;
-    async function _configureProcessor(ctx) {
+    AppFactory.updateAppSilent = updateAppSilent;
+    async function _configureApp(ctx) {
         /* Decode profile */
         const r1 = decodeProfileSilent(ctx.profile);
         if (!r1.result) {
@@ -128,14 +129,14 @@ export var ProcessorFactory;
             return false;
         }
         ctx.profile = r1.profile;
-        const oldMetadata = ctx.processor?.[ProcessorFactory.METADATA_KEY];
-        const oldProfile = ctx.processor?.[ProcessorFactory.PROFILE_KEY];
-        if (!ctx.processor) {
-            /* Create new processor instance */
-            const reg = ExtensionRegistry.getProcessor(r1.profile.processorUri, r1.profile.processorVersion);
-            const processorClass = await reg.getClass();
-            /* Create processor instance */
-            ctx.processor = new processorClass({
+        const oldMetadata = ctx.app?.[AppFactory.METADATA_KEY];
+        const oldProfile = ctx.app?.[AppFactory.PROFILE_KEY];
+        if (!ctx.app) {
+            /* Create new app instance */
+            const reg = ExtensionRegistry.getApp(r1.profile.appUri, r1.profile.appVersion);
+            const appClass = await reg.getClass();
+            /* Create app instance */
+            ctx.app = new appClass({
                 name: r1.profile.displayName,
                 logger: ctx.options?.logger,
                 values: r1.profile.values ? clone(r1.profile.values) : {},
@@ -145,14 +146,14 @@ export var ProcessorFactory;
         else {
             /* Update values */
             if (!ctx.stackExecutor.execute('values', () => {
-                _patchValues(ctx, ctx.processor, ctx.processor.values, '', r1.profile.values, r1.metadata.variables || {}, oldProfile?.values, oldMetadata.variables);
+                _patchValues(ctx, ctx.app, ctx.app.values, '', r1.profile.values, r1.metadata.variables || {}, oldProfile?.values, oldMetadata.variables);
             })) {
                 return false;
             }
         }
         const cmpCtx = {
             ...ctx,
-            owner: ctx.processor,
+            owner: ctx.app,
             curPath: '',
             newMetadataComponents: r1.metadata.components,
             newProfileComponents: r1.profile.components,
@@ -162,8 +163,9 @@ export var ProcessorFactory;
         if (!(_validateComponents(cmpCtx) && (await _configureComponents(cmpCtx)))) {
             return false;
         }
-        ctx.processor[ProcessorFactory.METADATA_KEY] = r1.metadata;
-        ctx.processor[ProcessorFactory.PROFILE_KEY] = r1.profile;
+        _configureLogChannels(ctx.app, r1.metadata.logChannels, r1.profile.settings?.logs?.channels, '', ctx.options?.logSink);
+        ctx.app[AppFactory.METADATA_KEY] = r1.metadata;
+        ctx.app[AppFactory.PROFILE_KEY] = r1.profile;
         return true;
     }
     function _validateComponents(ctx) {
@@ -199,7 +201,7 @@ export var ProcessorFactory;
         });
     }
     async function _configureComponents(ctx) {
-        const { newMetadataComponents, newProfileComponents, oldMetadataComponents, oldProfileComponents, curPath, owner, stackExecutor, processor, } = ctx;
+        const { newMetadataComponents, newProfileComponents, oldMetadataComponents, oldProfileComponents, curPath, owner, stackExecutor, app, } = ctx;
         if (!newMetadataComponents)
             return true;
         owner.components = owner.components || {};
@@ -224,7 +226,7 @@ export var ProcessorFactory;
                             const compClass = await compReg.getClass();
                             const values = { ...newChildProfile.values };
                             componentInstance = new compClass({
-                                processor: processor,
+                                app: app,
                                 parent: owner,
                                 name: key,
                                 path: componentPath,
@@ -238,6 +240,7 @@ export var ProcessorFactory;
                             componentInstance.values = {};
                             _patchValues(ctx, componentInstance, componentInstance.values, '', newChildProfile.values || {}, newChildMetadata.variables || {}, oldChildProfile?.values, oldChildMetadata?.variables);
                         }
+                        _configureLogChannels(componentInstance, newChildMetadata.logChannels, newChildProfile.settings?.logs?.channels, componentPath, ctx.options?.logSink);
                         /** Create the child logger */
                         componentInstance.logger = owner.logger?.child({
                             component: componentPath,
@@ -286,5 +289,21 @@ export var ProcessorFactory;
             }
         }
     }
-})(ProcessorFactory || (ProcessorFactory = {}));
-//# sourceMappingURL=processor-factory.js.map
+    /**
+     * Creates an element's log channels on first configuration - assigning
+     * each to its property - and applies the profile's settings to them on
+     * every one
+     */
+    function _configureLogChannels(element, definitions, settings, source, sink) {
+        for (const [name, definition] of Object.entries(definitions || {})) {
+            let channel = element.logChannels[name];
+            if (!channel) {
+                channel = new LogChannelWriter(definition, source, sink);
+                element.logChannels[name] = channel;
+                if (definition.propertyKey)
+                    element[definition.propertyKey] = channel;
+            }
+            channel.configure(settings?.[name], sink);
+        }
+    }
+})(AppFactory || (AppFactory = {}));

package/classes/{processor-base.d.ts → app-base.d.ts}

@@ -1,12 +1,12 @@
 import { BaseElement } from './base-element.js';
-export declare abstract class ProcessorBase<TEvents extends ProcessorBase.Events = ProcessorBase.Events> extends BaseElement<TEvents> {
+export declare abstract class AppBase<TEvents extends AppBase.Events = AppBase.Events> extends BaseElement<TEvents> {
     dataDirectory?: string;
-    constructor(init: ProcessorBase.InitArgs);
+    constructor(init: AppBase.InitArgs);
 }
 /**
  * @namespace
  */
-export declare namespace ProcessorBase {
+export declare namespace AppBase {
     interface Events extends BaseElement.Events {
     }
     interface InitArgs extends BaseElement.InitArgs {

package/classes/app-base.js

@@ -0,0 +1,10 @@
+import { BaseElement } from './base-element.js';
+export class AppBase extends BaseElement {
+    dataDirectory;
+    constructor(init) {
+        super(init);
+        this.dataDirectory = init.dataDirectory;
+    }
+}
+const APP_BASE_TOKEN = Symbol.for(AppBase.name);
+AppBase.prototype[APP_BASE_TOKEN] = true;

package/classes/base-element.d.ts

@@ -1,3 +1,4 @@
+import type { LogChannel } from '../decorators/log-channel.decorator.js';
 import type { ILogger } from '../interfaces/index.js';
 import { ServiceStatus } from '../models/index.js';
 import type { ComponentBase } from './component-base.js';
@@ -11,6 +12,8 @@ export declare abstract class BaseElement<TEvents extends BaseElement.Events = B
     readonly name: string;
     logger?: ILogger;
     components: Record<string, ComponentBase>;
+    /** The element's log channels by name; see `@LogChannel` */
+    readonly logChannels: Record<string, LogChannel>;
     values: Record<string, any>;
     constructor(init: BaseElement.InitArgs);
     get status(): ServiceStatus;

package/classes/base-element.js

@@ -8,6 +8,8 @@ export class BaseElement extends Runnable {
     name;
     logger;
     components = {};
+    /** The element's log channels by name; see `@LogChannel` */
+    logChannels = {};
     values;
     constructor(init) {
         super(init);
@@ -88,4 +90,3 @@ export class BaseElement extends Runnable {
         super.onStatusChange();
     }
 }
-//# sourceMappingURL=base-element.js.map

package/classes/component-base.d.ts

@@ -1,9 +1,9 @@
+import type { AppBase } from './app-base.js';
 import { BaseElement } from './base-element.js';
-import type { ProcessorBase } from './processor-base.js';
 export declare class ComponentBase<TEvents extends ComponentBase.Events = ComponentBase.Events> extends BaseElement<TEvents> {
     protected _context: ComponentBase.Context;
-    readonly processor: ProcessorBase;
-    readonly parent: ProcessorBase | ComponentBase;
+    readonly app: AppBase;
+    readonly parent: AppBase | ComponentBase;
     readonly path: string;
     constructor(init: ComponentBase.InitArgs);
 }
@@ -14,12 +14,12 @@ export declare namespace ComponentBase {
     interface Events extends BaseElement.Events {
     }
     interface InitArgs extends BaseElement.InitArgs {
-        processor: ProcessorBase;
-        parent: ProcessorBase | ComponentBase;
+        app: AppBase;
+        parent: AppBase | ComponentBase;
         path: string;
     }
     interface Context extends BaseElement.Context {
-        parent: ProcessorBase | ComponentBase;
+        parent: AppBase | ComponentBase;
         name: string;
         path: string;
     }

package/classes/component-base.js

@@ -1,15 +1,14 @@
 import { BaseElement } from './base-element.js';
 export class ComponentBase extends BaseElement {
-    processor;
+    app;
     parent;
     path;
     constructor(init) {
         super(init);
-        this.processor = init.processor;
+        this.app = init.app;
         this.parent = init.parent;
         this.path = init.path;
     }
 }
 const COMPONENT_BASE_TOKEN = Symbol.for(ComponentBase.name);
 ComponentBase.prototype[COMPONENT_BASE_TOKEN] = true;
-//# sourceMappingURL=component-base.js.map

package/classes/console-logger.js

@@ -35,4 +35,3 @@ export class ConsoleLogger {
         return undefined;
     }
 }
-//# sourceMappingURL=console-logger.js.map

package/classes/frame-stream.js

@@ -138,4 +138,3 @@ export class FrameStream extends Transform {
         this.push(combined);
     }
 }
-//# sourceMappingURL=frame-stream.js.map

package/classes/log-channel-writer.d.ts

@@ -0,0 +1,32 @@
+import type { LogChannel } from '../decorators/log-channel.decorator.js';
+import { LogChannelKind, type LogChannelMetadata, type LogChannelSettings, LogLevel } from '../models/index.js';
+/**
+ * The LogChannel a `@LogChannel` property holds: it applies the channel's
+ * settings and hands what passes them to the worker's sink.
+ */
+export declare class LogChannelWriter implements LogChannel {
+    readonly metadata: LogChannelMetadata;
+    /** The path of the element it belongs to; '' for the app */
+    readonly source: string;
+    protected _sink?: LogChannel.Sink | undefined;
+    enabled: boolean;
+    level?: LogLevel;
+    /** The events written; all when not set */
+    events?: Set<string>;
+    constructor(metadata: LogChannelMetadata, 
+    /** The path of the element it belongs to; '' for the app */
+    source: string, _sink?: LogChannel.Sink | undefined);
+    get name(): string;
+    get fullName(): string;
+    get kind(): LogChannelKind;
+    /** Applies the profile's settings over the definition's defaults */
+    configure(settings?: LogChannelSettings, sink?: LogChannel.Sink | undefined): void;
+    write(record: LogChannel.Record): void;
+    fatal(message: string, fields?: Record<string, any>): void;
+    error(message: string, fields?: Record<string, any>): void;
+    warn(message: string, fields?: Record<string, any>): void;
+    info(message: string, fields?: Record<string, any>): void;
+    verbose(message: string, fields?: Record<string, any>): void;
+    debug(message: string, fields?: Record<string, any>): void;
+    trace(message: string, fields?: Record<string, any>): void;
+}