@syncbridge/common 2.5.0 → 2.7.0

package/README.md

@@ -141,6 +141,13 @@ property's TypeScript type when not given. Some options:
 | `hotPlug` | A change applies while running, without a restart |
 | `index` | Its order in the UI |
 
+A worker's configuration may name a value its server or its workspace
+keeps, set once in SyncBridge Console, instead of holding it:
+`${{ vars.HBYS_URL }}/api`. SyncBridge puts the value in before the app
+starts and checks it as any value, so the app sees a plain value of the
+variable's type. `parseValueRefs`, `resolveValueRefs` and
+`profileValueRefs` read such references; `$${{` writes `${{` itself.
+
 ## Lifecycle
 
 Apps and components are `Runnable`s. Override the protected methods, and

package/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const version = "2.5.0";
+export declare const version = "2.7.0";
 export declare const CLASS_METADATA: unique symbol;
 export declare const CLASS_TYPE: unique symbol;
 export declare const VARIABLE_CONTAINER: unique symbol;

package/constants.js

@@ -1,4 +1,4 @@
-export const version = '2.5.0';
+export const version = '2.7.0';
 export const CLASS_METADATA = Symbol.for('CLASS_METADATA');
 export const CLASS_TYPE = Symbol.for('CLASS_TYPE');
 export const VARIABLE_CONTAINER = Symbol.for('VARIABLE_CONTAINER');

package/host-link/host-values.d.ts

@@ -0,0 +1,38 @@
+/** Where, under Console's API, a host asks for its values */
+export declare const HOST_VALUES_PATH = "host/values";
+/**
+ * Where, under the host's API, Console tells it that its values changed:
+ * POST, no body; the host then asks for them
+ */
+export declare const HOST_VALUES_CHANGED_PATH = "settings/values/changed";
+/** The names a host's workers use, qualified ("vars.HBYS_URL") */
+export interface HostValuesUses {
+    /** Every name its workers' profiles make, each once */
+    variables: string[];
+    /** Those of them neither the host nor its workspace defines */
+    missing: string[];
+}
+export interface HostValuesRequest {
+    /** The revision of the values it has: none, it has none */
+    revision?: number;
+    /** What its workers use: kept by Console, replaced whole each time */
+    uses?: HostValuesUses;
+}
+/** A workspace's variables and a host's own, by name */
+export interface HostVariables {
+    workspace: Record<string, string>;
+    host: Record<string, string>;
+}
+export interface HostValuesResponse {
+    /**
+     * The workspace's revision: one counter, raised by any change of its
+     * values or of any of its hosts' values
+     */
+    revision: number;
+    /** Whether the values changed since the revision the host told */
+    changed: boolean;
+    /** Changed: both trees, whole */
+    variables?: HostVariables;
+}
+/** A variable as a host takes it: its own definition, else the workspace's */
+export declare function hostVariable(variables: HostVariables | undefined, name: string): string | undefined;

package/host-link/host-values.js

@@ -0,0 +1,25 @@
+/*
+ * The values a host's workers name in their profiles (`${{ vars.NAME }}`,
+ * value-refs): kept by Console for a workspace and for each of its hosts,
+ * a host's own definition of a name over the workspace's. The host asks
+ * for them when its link connects and when Console tells it they changed
+ * (HOST_VALUES_CHANGED_PATH); and tells which names its workers use, which
+ * of them it lacks, whenever that changes. Asked by the host, with a token
+ * it signs (HOST_TOKEN_HEADER).
+ */
+/** Where, under Console's API, a host asks for its values */
+export const HOST_VALUES_PATH = 'host/values';
+/**
+ * Where, under the host's API, Console tells it that its values changed:
+ * POST, no body; the host then asks for them
+ */
+export const HOST_VALUES_CHANGED_PATH = 'settings/values/changed';
+/** A variable as a host takes it: its own definition, else the workspace's */
+export function hostVariable(variables, name) {
+    if (!variables)
+        return;
+    if (Object.prototype.hasOwnProperty.call(variables.host, name))
+        return variables.host[name];
+    if (Object.prototype.hasOwnProperty.call(variables.workspace, name))
+        return variables.workspace[name];
+}

package/index.d.ts

@@ -17,6 +17,7 @@ export * from './host-link/host-identity.js';
 export * from './host-link/host-link.js';
 export * from './host-link/host-packages.js';
 export * from './host-link/host-permissions.js';
+export * from './host-link/host-values.js';
 export * from './host-link/host-workers.js';
 export * from './host-link/multiplexer.js';
 export * from './host-link/sealed-box.js';
@@ -39,4 +40,5 @@ export * from './utils/registry-names.js';
 export * from './utils/slot-interfaces.js';
 export * from './utils/type-guards.js';
 export * from './utils/uri-to-id.js';
+export * from './utils/value-refs.js';
 export * from './utils/worker-permissions.js';

package/index.js

@@ -17,6 +17,7 @@ export * from './host-link/host-identity.js';
 export * from './host-link/host-link.js';
 export * from './host-link/host-packages.js';
 export * from './host-link/host-permissions.js';
+export * from './host-link/host-values.js';
 export * from './host-link/host-workers.js';
 export * from './host-link/multiplexer.js';
 export * from './host-link/sealed-box.js';
@@ -39,4 +40,5 @@ export * from './utils/registry-names.js';
 export * from './utils/slot-interfaces.js';
 export * from './utils/type-guards.js';
 export * from './utils/uri-to-id.js';
+export * from './utils/value-refs.js';
 export * from './utils/worker-permissions.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncbridge/common",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "SyncBridge Common utilities",
   "author": "Panates Inc",
   "license": "MIT",

package/utils/decode-profile.d.ts

@@ -3,6 +3,13 @@ import { AppMetadata, Profile, VariableMetadataRecord } from '../models/index.js
 export interface CodecOptions {
     setDefaultValues?: boolean;
     cryptoSecretKey?: string;
+    /**
+     * The profile's references not resolved yet (`${{ vars.NAME }}`, see
+     * value-refs): a value holding one is kept as written, unchecked, of
+     * whatever type its variable is - checked once resolved. A profile
+     * edited or stored; never one a worker runs with.
+     */
+    unresolved?: boolean;
 }
 /**
  * Decodes profile

package/utils/decode-profile.js

@@ -5,6 +5,7 @@ import { AppMetadata, ElementComponentMetadata, Profile, ProfileComponent, Varia
 import { getModelsDocument } from '../models-document.js';
 import { secretDecryptor, secretEncryptor } from './encrypt-helpers.js';
 import { materializeMetadataSilent } from './materialize-metadata.js';
+import { hasValueRef } from './value-refs.js';
 /**
  * Decodes profile
  */
@@ -200,6 +201,14 @@ function _codecValues(stackExecutor, codec, variables, oldValues, options) {
             stackExecutor.execute(k, () => {
                 if (defVariable == null)
                     return;
+                /* A reference not resolved yet: kept as written */
+                const given = oldVals?.[k];
+                if (options?.unresolved &&
+                    (hasValueRef(given) ||
+                        (Array.isArray(given) && given.some(hasValueRef)))) {
+                    target[k] = given;
+                    return;
+                }
                 let valueFn = isAny;
                 /* If variable is ignored and no default value is set, field should be undefined  */
                 if (defVariable.ignored && defVariable.default === undefined) {

package/utils/registry-names.js

@@ -20,6 +20,7 @@ export const SDK_PACKAGES = [
     '@syncbridge/syncbuild',
     '@syncbridge/testing',
     '@syncbridge/plugin-api',
+    '@syncbridge/pnpm-config',
 ];
 /** Whether a name is one of the SDK's packages, which come from npm */
 export const isSdkPackage = (name) => SDK_PACKAGES.includes(name);

package/utils/value-refs.d.ts

@@ -0,0 +1,46 @@
+import type { Profile } from '../models/index.js';
+/** The name of a variable or a secret: UPPER_SNAKE, at most 64 characters */
+export declare const VALUE_REF_NAME: RegExp;
+/** What a reference names: a variable, or a secret */
+export type ValueRefKind = 'vars' | 'secrets';
+export interface ValueRef {
+    kind: ValueRefKind;
+    name: string;
+}
+/** A reference as told: "vars.NAME" */
+export declare const qualifiedRef: (ref: ValueRef) => string;
+/** A reference as written in a value: "${{ vars.NAME }}" */
+export declare const formatValueRef: (kind: ValueRefKind, name: string) => string;
+/**
+ * Whether a value holds a reference - or writes `${{` itself - so that it
+ * is not its final value until resolved
+ */
+export declare function hasValueRef(value: unknown): value is string;
+/** The references of a text, in order, and what is wrong in it */
+export declare function parseValueRefs(text: string): {
+    refs: ValueRef[];
+    errors: string[];
+};
+/**
+ * A text with its references replaced by what `lookup` answers - `$${{`
+ * by `${{` - and the references it does not answer, qualified
+ */
+export declare function resolveValueText(text: string, lookup: (kind: ValueRefKind, name: string) => string | undefined): {
+    value: string;
+    missing: string[];
+    errors: string[];
+};
+/**
+ * A profile with the references of its values resolved - the app's and
+ * each component's, nothing else of it - by `lookup`; the references it
+ * does not answer, qualified ("vars.HBYS_URL"), and the expressions that
+ * are not references, each with where it is. The profile given is left as
+ * it is.
+ */
+export declare function resolveValueRefs<T extends Profile>(profile: T, lookup: (kind: ValueRefKind, name: string) => string | undefined): {
+    profile: T;
+    missing: string[];
+    errors: string[];
+};
+/** The references a profile's values make, qualified, each once, sorted */
+export declare function profileValueRefs(profile: Profile): string[];

package/utils/value-refs.js

@@ -0,0 +1,166 @@
+/*
+ * References in a worker's values: `${{ vars.NAME }}` names a variable its
+ * host or its workspace keeps, anywhere in a string value and more than
+ * once; `${{ secrets.NAME }}` a secret. `$${{` writes `${{` itself. A
+ * profile keeps the references as written - stored, synced to Console,
+ * restored - and the host resolves them before the profile is decoded, so
+ * a resolved value is checked as any value is.
+ */
+/** The name of a variable or a secret: UPPER_SNAKE, at most 64 characters */
+export const VALUE_REF_NAME = /^[A-Z][A-Z0-9_]{0,63}$/;
+/** A reference as told: "vars.NAME" */
+export const qualifiedRef = (ref) => `${ref.kind}.${ref.name}`;
+/** A reference as written in a value: "${{ vars.NAME }}" */
+export const formatValueRef = (kind, name) => '${{ ' + kind + '.' + name + ' }}';
+const OPEN = '${{';
+const CLOSE = '}}';
+/**
+ * Whether a value holds a reference - or writes `${{` itself - so that it
+ * is not its final value until resolved
+ */
+export function hasValueRef(value) {
+    return typeof value === 'string' && value.includes(OPEN);
+}
+/**
+ * Goes through a text: its pieces of plain text, and its references. An
+ * expression that is not one - another kind than vars or secrets, a name
+ * not UPPER_SNAKE, no closing braces - is an error, not text: a slip is
+ * not kept as written.
+ */
+function scan(text, on) {
+    const errors = [];
+    let at = 0;
+    for (;;) {
+        const open = text.indexOf(OPEN, at);
+        if (open < 0)
+            break;
+        /* `$${{`: the text `${{` */
+        if (open > 0 && text[open - 1] === '$') {
+            on.text(text.slice(at, open - 1) + OPEN);
+            at = open + OPEN.length;
+            continue;
+        }
+        on.text(text.slice(at, open));
+        const close = text.indexOf(CLOSE, open + OPEN.length);
+        if (close < 0) {
+            errors.push(`"${text.slice(open)}" is not closed with "${CLOSE}"`);
+            on.text(text.slice(open));
+            return errors;
+        }
+        const inner = text.slice(open + OPEN.length, close).trim();
+        const m = /^(vars|secrets)\.(\S+)$/.exec(inner);
+        if (m && VALUE_REF_NAME.test(m[2]))
+            on.ref({ kind: m[1], name: m[2] });
+        else {
+            errors.push(`"${OPEN} ${inner} ${CLOSE}" is not a reference: write ` +
+                `${formatValueRef('vars', 'NAME')} or ${formatValueRef('secrets', 'NAME')}, ` +
+                `NAME in capitals, digits and "_"; "$${OPEN}" for the text "${OPEN}"`);
+            on.text(text.slice(open, close + CLOSE.length));
+        }
+        at = close + CLOSE.length;
+    }
+    on.text(text.slice(at));
+    return errors;
+}
+/** The references of a text, in order, and what is wrong in it */
+export function parseValueRefs(text) {
+    const refs = [];
+    const errors = scan(text, { text: () => undefined, ref: r => refs.push(r) });
+    return { refs, errors };
+}
+/**
+ * A text with its references replaced by what `lookup` answers - `$${{`
+ * by `${{` - and the references it does not answer, qualified
+ */
+export function resolveValueText(text, lookup) {
+    let value = '';
+    const missing = [];
+    const errors = scan(text, {
+        text: piece => (value += piece),
+        ref: ref => {
+            const found = lookup(ref.kind, ref.name);
+            if (found === undefined)
+                missing.push(qualifiedRef(ref));
+            else
+                value += found;
+        },
+    });
+    return { value, missing, errors };
+}
+/**
+ * Each value tree of a profile - the app's, each component's down the
+ * components - with where it is: "values", "components/server/values"
+ */
+function eachValues(profile, fn) {
+    if (profile.values)
+        fn(profile.values, 'values');
+    const walk = (components, at) => {
+        for (const [key, component] of Object.entries(components || {})) {
+            if (!component)
+                continue;
+            const here = `${at}/${key}`;
+            if (component.values)
+                fn(component.values, `${here}/values`);
+            walk(component.components, `${here}/components`);
+        }
+    };
+    walk(profile.components, 'components');
+}
+/** Each string of a value tree, down its objects and arrays: replaced by `fn` */
+function mapStrings(tree, location, fn) {
+    if (typeof tree === 'string')
+        return fn(tree, location);
+    if (Array.isArray(tree))
+        return tree.map((v, i) => mapStrings(v, `${location}/${i}`, fn));
+    if (tree && typeof tree === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(tree))
+            out[k] = mapStrings(v, `${location}/${k}`, fn);
+        return out;
+    }
+    return tree;
+}
+/**
+ * A profile with the references of its values resolved - the app's and
+ * each component's, nothing else of it - by `lookup`; the references it
+ * does not answer, qualified ("vars.HBYS_URL"), and the expressions that
+ * are not references, each with where it is. The profile given is left as
+ * it is.
+ */
+export function resolveValueRefs(profile, lookup) {
+    const out = structuredClone(profile);
+    const missing = new Set();
+    const errors = [];
+    const resolve = (values, location) => mapStrings(values, location, (text, at) => {
+        if (!hasValueRef(text))
+            return text;
+        const r = resolveValueText(text, lookup);
+        r.missing.forEach(m => missing.add(m));
+        errors.push(...r.errors.map(e => `${at}: ${e}`));
+        return r.value;
+    });
+    if (out.values)
+        out.values = resolve(out.values, 'values');
+    const walk = (components, at) => {
+        for (const [key, component] of Object.entries(components || {})) {
+            if (!component)
+                continue;
+            const here = `${at}/${key}`;
+            if (component.values)
+                component.values = resolve(component.values, `${here}/values`);
+            walk(component.components, `${here}/components`);
+        }
+    };
+    walk(out.components, 'components');
+    return { profile: out, missing: [...missing], errors };
+}
+/** The references a profile's values make, qualified, each once, sorted */
+export function profileValueRefs(profile) {
+    const names = new Set();
+    eachValues(profile, values => mapStrings(values, '', text => {
+        if (hasValueRef(text))
+            parseValueRefs(text).refs.forEach(r => names.add(qualifiedRef(r)));
+        return text;
+    }));
+    return [...names].sort();
+}