@lakutata/dbus 2.3.1 → 3.0.0-beta.1

package/dist/cjs/adapters/DBusEntrypoint.js

@@ -0,0 +1,280 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dbusEntrypoint = dbusEntrypoint;
+const node_events_1 = __importDefault(require("node:events"));
+const dtos_1 = require("@lakutata/core/dtos");
+const dbus_sdk_1 = require("dbus-sdk");
+const DBusChannel_js_1 = require("../channel/DBusChannel.js");
+const DBusContext_js_1 = require("../context/DBusContext.js");
+const DBusObjectManager_js_1 = require("../components/DBusObjectManager.js");
+const Declarations_js_1 = require("../lib/Declarations.js");
+const Names_js_1 = require("../lib/Names.js");
+const Signature_js_1 = require("../lib/Signature.js");
+/**
+ * The connection options of a bus
+ * @param bus
+ */
+function connectOptions(bus) {
+    if (bus === 'session')
+        return { busAddress: process.env.DBUS_SESSION_BUS_ADDRESS };
+    if (bus === 'system')
+        return { busAddress: process.env.DBUS_SYSTEM_BUS_ADDRESS ?? 'unix:path=/var/run/dbus/system_bus_socket' };
+    if (/^[a-z]+:/.test(bus))
+        return { busAddress: bus };
+    return { socket: bus };
+}
+/**
+ * The error given to the caller of a method
+ * @param error
+ */
+function toMethodError(error) {
+    const { errMsg, message } = (error && typeof error === 'object' ? error : {});
+    const methodError = new Error(typeof errMsg === 'string' && errMsg ? errMsg : typeof message === 'string' ? message : String(error));
+    methodError.name = (0, Names_js_1.errorName)(error);
+    return methodError;
+}
+/**
+ * Build the D-Bus adapter of the entrypoint (its `dbus` option): the application owns a service name on a bus and
+ * serves the controllers declared with `@DBusInterface` as the interfaces of its objects, their `@DBusMethod` actions
+ * as the methods. The objects of the paths without variables are exported when the adapter starts, until it stops
+ * ({@link DBusObjectManager.removeObject} does not remove them); the objects of the path templates are exported when
+ * they are added with {@link DBusObjectManager.addObject}, before or after the start.
+ *
+ * Starting connects to the bus and requests the name. The adapter stops gracefully with the entrypoint: it releases the
+ * name (no new call reaches it), the calls in progress end, then the connection closes. It needs a D-Bus daemon, as on
+ * Linux: the system bus, a session bus, or a private `dbus-daemon`.
+ * @param options The bus, the service name and how it is owned, the adapter's middlewares.
+ * @returns The adapter, to give to the `dbus` option of `buildEntrypoints()`.
+ * @throws {TypeError} At once, when the service name is invalid; when the adapter starts, when an action declared with
+ * `@DBusMethod` belongs to a controller without `@DBusInterface`.
+ * @throws {Error} When the adapter starts, if the bus cannot be reached, or if another connection owns the name
+ * (`The DBus name … is owned by another service`): the entrypoint fails to start.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {dbusEntrypoint, DBusInterface, DBusMethod} from '@lakutata/dbus'
+ *
+ * @DBusInterface('com.example.Manager', {path: '/com/example/Manager'})
+ * class ManagerController extends Controller {
+ *     @DBusMethod('Ping', {returns: 's'})
+ *     public async ping(): Promise<string> {
+ *         return 'pong'
+ *     }
+ * }
+ *
+ * //busctl --system call com.example.DeviceService /com/example/Manager com.example.Manager Ping
+ * Application.run(() => ({
+ *     id: 'devices.app',
+ *     name: 'Devices',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [ManagerController],
+ *             dbus: dbusEntrypoint({bus: 'system', service: 'com.example.DeviceService'})
+ *         })
+ *     },
+ *     bootstrap: ['entrypoint']
+ * }))
+ * ```
+ */
+function dbusEntrypoint(options) {
+    (0, Names_js_1.checkInterfaceName)(options.service);
+    let service;
+    let detach;
+    const exported = new Map();
+    /**
+     * The interfaces of the controllers and of the actions, by path template
+     * @param runtime
+     */
+    const collect = (runtime) => {
+        const templates = new Map();
+        const interfacesAt = (path, name) => {
+            let template = templates.get(path);
+            if (!template) {
+                template = { template: (0, Names_js_1.compilePathTemplate)(path), interfaces: new Map() };
+                templates.set(path, template);
+            }
+            let interfaces = template.interfaces.get(name);
+            if (!interfaces) {
+                interfaces = { methods: [] };
+                template.interfaces.set(name, interfaces);
+            }
+            return interfaces;
+        };
+        for (const controller of runtime.controllers) {
+            const declaration = (0, Declarations_js_1.getDBusInterfaceDeclaration)(controller);
+            if (declaration)
+                interfacesAt(declaration.path, declaration.interface).declaration = declaration;
+        }
+        for (const action of runtime.actions) {
+            const { path, interface: interfaceName, member } = action.address;
+            if (path === undefined || interfaceName === undefined)
+                throw new TypeError(`The DBus method ${member} of ${action.controller} has no interface: declare its controller with @DBusInterface`);
+            interfacesAt(path, interfaceName).methods.push(action);
+        }
+        return templates;
+    };
+    /**
+     * The signature of the result of a method: its returns option, or the schema of @Return
+     * @param action
+     */
+    const resultSignature = (action) => {
+        if (action.address.returns !== undefined)
+            return action.address.returns;
+        return action.returnSchema ? (0, Signature_js_1.schemaSignature)(action.returnSchema) : undefined;
+    };
+    return {
+        channel: 'dbus',
+        definition: DBusChannel_js_1.DBusChannel,
+        name: options.name,
+        middlewares: options.middlewares,
+        start: async (runtime) => {
+            const templates = collect(runtime);
+            const manager = await runtime.getObject(DBusObjectManager_js_1.DBusObjectManager);
+            const localService = new dbus_sdk_1.LocalService(options.service);
+            service = localService;
+            /**
+             * Build the interface of an object
+             * @param path
+             * @param name
+             * @param served
+             * @param variables
+             * @param object
+             */
+            const buildInterface = (path, name, served, variables, object) => {
+                const localInterface = new dbus_sdk_1.LocalInterface(name);
+                for (const action of served.methods) {
+                    const returns = resultSignature(action);
+                    const hasInput = action.dto !== dtos_1.FlexibleDTO;
+                    localInterface.defineMethod({
+                        name: action.address.member,
+                        inputArgs: hasInput ? [{ name: 'input', type: 'a{sv}' }] : [],
+                        outputArgs: returns ? [{ name: 'output', type: returns }] : [],
+                        method: async (input) => {
+                            const context = new DBusContext_js_1.DBusContext({ path: path, interface: name, member: action.address.member, data: input && typeof input === 'object' ? input : {} });
+                            let result;
+                            try {
+                                result = await runtime.dispatchTo(action, context, { params: variables });
+                            }
+                            catch (error) {
+                                throw toMethodError(error);
+                            }
+                            if (!returns)
+                                return undefined;
+                            return (0, Signature_js_1.toEncodable)(returns === 'a{sv}' && (result === undefined || result === null) ? {} : result);
+                        }
+                    });
+                }
+                for (const property of served.declaration?.properties ?? []) {
+                    localInterface.defineProperty({
+                        name: property.name,
+                        type: property.type,
+                        getter: () => (0, Signature_js_1.toEncodable)(manager.getPropertyValue(path, property)),
+                        //A value written by a client is validated synchronously: its errors are given to the client
+                        setter: property.writable ? (value) => {
+                            let validated;
+                            try {
+                                validated = property.validate(value);
+                            }
+                            catch (error) {
+                                //The errors given to DBus are plain errors (the name of an exception is read only)
+                                throw toMethodError(error);
+                            }
+                            manager[DBusObjectManager_js_1.STORE]({ path: path, interface: name, property: property, value: validated });
+                        } : undefined,
+                        emitPropertiesChanged: property.writable
+                    });
+                    object.properties.set(property, [...(object.properties.get(property) ?? []), name]);
+                }
+                for (const signal of served.declaration?.signals ?? []) {
+                    const emitter = new node_events_1.default();
+                    localInterface.defineSignal({ name: signal.name, args: [{ name: 'data', type: signal.type }], eventEmitter: emitter });
+                    const signals = object.signals.get(signal.name) ?? [];
+                    signals.push({ signal: signal, emitter: emitter });
+                    object.signals.set(signal.name, signals);
+                }
+                return localInterface;
+            };
+            /**
+             * Export an object
+             * @param path
+             */
+            const addObject = (path) => {
+                if (exported.has(path))
+                    return true;
+                const object = { object: new dbus_sdk_1.LocalObject(path), signals: new Map(), properties: new Map() };
+                let served = false;
+                for (const { template, interfaces } of templates.values()) {
+                    const variables = template.match(path);
+                    if (!variables)
+                        continue;
+                    interfaces.forEach((interfaceServed, name) => object.object.addInterface(buildInterface(path, name, interfaceServed, variables, object)));
+                    served = true;
+                }
+                if (!served)
+                    return false;
+                exported.set(path, object);
+                localService.addObject(object.object);
+                return true;
+            };
+            //The objects of the paths without variables are exported at once, and kept until the adapter closes
+            const fixed = new Set();
+            for (const { template } of templates.values()) {
+                if (!template.static)
+                    continue;
+                fixed.add(template.template);
+                addObject(template.template);
+            }
+            const connect = connectOptions(options.bus ?? 'session');
+            let flags = dbus_sdk_1.RequestNameFlags.DBUS_NAME_FLAG_DO_NOT_QUEUE;
+            if (options.replaceExisting)
+                flags |= dbus_sdk_1.RequestNameFlags.DBUS_NAME_FLAG_REPLACE_EXISTING;
+            if (options.allowReplacement)
+                flags |= dbus_sdk_1.RequestNameFlags.DBUS_NAME_FLAG_ALLOW_REPLACEMENT;
+            const result = await localService.run({ ...connect, flags: flags });
+            if (result !== dbus_sdk_1.RequestNameResultCode.DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER && result !== dbus_sdk_1.RequestNameResultCode.DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER) {
+                await localService.stop().catch(() => undefined);
+                throw new Error(`The DBus name ${options.service} is owned by another service`);
+            }
+            const sink = {
+                addObject: addObject,
+                removeObject: (path) => {
+                    if (fixed.has(path) || !exported.delete(path))
+                        return false;
+                    return localService.removeObject(path);
+                },
+                isFixed: (path) => fixed.has(path),
+                emitSignal: (path, signal, data) => {
+                    const emitters = exported.get(path)?.signals.get(signal.name)?.filter((candidate) => candidate.signal === signal);
+                    if (!emitters?.length)
+                        return false;
+                    emitters.forEach(({ emitter }) => emitter.emit(signal.name, (0, Signature_js_1.toEncodable)(data)));
+                    return true;
+                },
+                propertyChanged: (path, property) => {
+                    const object = exported.get(path);
+                    const interfaces = object?.properties.get(property);
+                    if (!object || !interfaces)
+                        return;
+                    //The interfaces read the new value with their getters (the manager stored it), typed by the property
+                    interfaces.forEach((name) => object.object.getInterface(name)?.emitPropertiesChanged(property.name));
+                }
+            };
+            detach = manager[DBusObjectManager_js_1.ATTACH](sink);
+        },
+        stop: async () => {
+            //The name is released: no new call reaches the service, the calls in progress end
+            detach?.();
+            detach = undefined;
+            await service?.dbus?.releaseName(options.service).catch(() => undefined);
+        },
+        close: async () => {
+            await service?.dbus?.disconnect().catch(() => undefined);
+            exported.clear();
+            service = undefined;
+        }
+    };
+}

package/dist/cjs/channel/DBusChannel.d.ts

@@ -0,0 +1,36 @@
+import { type EntrypointAdapter } from '@lakutata/entrypoint';
+import { type ChannelDefinition } from '@lakutata/entrypoint/channel';
+import { DBusContext } from '../context/DBusContext.js';
+declare module '@lakutata/entrypoint' {
+    interface EntrypointOptions {
+        /**
+         * The D-Bus adapters, built by `dbusEntrypoint()`: one, or several for several buses or service names.
+         * @default undefined (no D-Bus adapter)
+         */
+        dbus?: EntrypointAdapter<DBusContext> | EntrypointAdapter<DBusContext>[];
+    }
+    interface PrefixOptions {
+        /**
+         * The object path (or path template) and the interface of a controller's D-Bus methods. `@DBusInterface` sets
+         * it; an application does not set it itself.
+         */
+        dbus?: {
+            /**
+             * The object path, or path template, of the methods.
+             */
+            path?: string;
+            /**
+             * The name of the methods' interface.
+             */
+            interface?: string;
+        };
+    }
+}
+/**
+ * The definition of the D-Bus channel of the entrypoint, named `dbus`: its actions are the methods of D-Bus interfaces,
+ * addressed by `{member, interface, path}` (the method name from `@DBusMethod`, the interface and the path template from
+ * `@DBusInterface`). A call matches an action by its interface, its method and its object path; a call matching none
+ * fails with `ControllerActionNotFoundException`. `@DBusMethod` and {@link dbusEntrypoint} use it: an application only
+ * needs it to write an adapter of its own.
+ */
+export declare const DBusChannel: ChannelDefinition;

package/dist/cjs/channel/DBusChannel.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DBusChannel = void 0;
+const entrypoint_1 = require("@lakutata/entrypoint");
+const channel_1 = require("@lakutata/entrypoint/channel");
+const DBusContext_js_1 = require("../context/DBusContext.js");
+const Names_js_1 = require("../lib/Names.js");
+/**
+ * The key of the address of a method
+ * @param interfaceName
+ * @param member
+ * @param path
+ */
+function addressKey(interfaceName, member, path) {
+    return `${interfaceName}.${member}@${path}`;
+}
+/**
+ * The definition of the D-Bus channel of the entrypoint, named `dbus`: its actions are the methods of D-Bus interfaces,
+ * addressed by `{member, interface, path}` (the method name from `@DBusMethod`, the interface and the path template from
+ * `@DBusInterface`). A call matches an action by its interface, its method and its object path; a call matching none
+ * fails with `ControllerActionNotFoundException`. `@DBusMethod` and {@link dbusEntrypoint} use it: an application only
+ * needs it to write an adapter of its own.
+ */
+exports.DBusChannel = (0, channel_1.hasChannel)('dbus') ? (0, channel_1.getChannel)('dbus') : (0, channel_1.defineChannel)({
+    name: 'dbus',
+    kind: 'request',
+    contextType: DBusContext_js_1.DBUS_CONTEXT_TYPE,
+    validate: (pattern) => {
+        (0, Names_js_1.checkMemberName)(pattern.member, 'method');
+        if (pattern.interface !== undefined)
+            (0, Names_js_1.checkInterfaceName)(pattern.interface);
+        if (pattern.path !== undefined)
+            (0, Names_js_1.checkPathTemplate)(pattern.path);
+        return pattern;
+    },
+    identify: (pattern) => addressKey(pattern.interface ?? '?', pattern.member, pattern.path ?? '?'),
+    describe: (pattern) => {
+        const { returns, ...address } = pattern;
+        return returns === undefined ? address : { ...address, returns: returns };
+    },
+    prefix: (prefix, pattern) => {
+        const dbus = prefix.dbus;
+        if (!dbus || (pattern.path !== undefined && pattern.interface !== undefined))
+            return undefined;
+        return { ...pattern, path: pattern.path ?? dbus.path, interface: pattern.interface ?? dbus.interface };
+    },
+    createMatcher: (entries) => {
+        const templates = entries
+            .filter((entry) => entry.details.pattern.path !== undefined)
+            .map((entry) => ({ entry: entry, template: (0, Names_js_1.compilePathTemplate)(entry.details.pattern.path) }));
+        return {
+            match: (context) => {
+                const { path, interface: interfaceName, member } = context;
+                for (const { entry, template } of templates) {
+                    if (entry.details.pattern.interface !== interfaceName || entry.details.pattern.member !== member)
+                        continue;
+                    const params = template.match(path);
+                    if (params)
+                        return { entry: entry, params: params };
+                }
+                return undefined;
+            }
+        };
+    },
+    notFound: (context) => new entrypoint_1.ControllerActionNotFoundException('The DBus method {member} of the interface {interface} of {path} is not found', {
+        member: context.member,
+        interface: context.interface,
+        path: context.path
+    })
+});