@lakutata/entrypoint 3.0.0-beta.0

package/dist/esm/adapter/schedule/ScheduleEntrypoint.js

@@ -0,0 +1,272 @@
+import { ScheduleContext } from '../../context/ScheduleContext.js';
+import { ScheduleChannel } from '../../channel/BuiltinChannels.js';
+import { Cron } from '../../lib/schedule/Cron.js';
+/**
+ * The longest time a lock of a run is kept after it (the other instances whose clocks are late skip it)
+ */
+const MAX_HOLD = 30000;
+/**
+ * The longest delay of a timer
+ */
+const MAX_DELAY = 2 ** 31 - 1;
+/**
+ * Create the schedule adapter of an entrypoint: it runs the controller actions declared with `@Schedule`, which never
+ * run without it. It needs no optional dependency.
+ *
+ * The runs begin once the application has launched (all its objects, its bootstrap and the other adapters are ready).
+ * Each run is dispatched like a request: a new controller in its own scope, the middlewares and the access control, a
+ * {@link ScheduleContext} giving the schedule, the time the run was due and its number. An interval keeps its pace:
+ * the runs missed while the process was suspended are skipped, not caught up. An action whose previous run is still in
+ * progress skips its run unless it allows `overlap`.
+ *
+ * An `exclusive` action runs in one instance of the application at a time: each run first tries to acquire a lock
+ * named `schedule:<key>` (the `key` of its `exclusive` option, the action name by default) from the mutex component
+ * (the `Mutex` of `lakutata/com/mutex`, named `mutex` by default), and is skipped when another
+ * instance holds it; the lock is kept after the run for half of its period (30 seconds at most) so that the instances
+ * whose clocks are late skip it too. An exclusive action whose mutex component cannot be resolved never runs (the
+ * error is logged).
+ *
+ * When the entrypoint stops, no new run starts, the kept locks are released and the entrypoint waits for the runs in
+ * progress (aborting them after its `shutdownTimeout`).
+ * @param options The adapter options.
+ * @returns The adapter, to give to the `schedule` option of `buildEntrypoints`.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller, ScheduleContext, scheduleEntrypoint} from 'lakutata/com/entrypoint'
+ * import {Schedule} from 'lakutata/decorator/ctrl'
+ *
+ * class MaintenanceController extends Controller {
+ *     //Every 5 minutes, and once the application launched
+ *     @Schedule({every: '5m', immediate: true})
+ *     public async purge(): Promise<void> {
+ *         const context: ScheduleContext = this.context as ScheduleContext
+ *         console.log(`Run ${context.run}, due at ${context.scheduledAt.toISOString()}`)
+ *     }
+ *
+ *     //Every day at 03:00 in Shanghai
+ *     @Schedule({cron: '0 3 * * *', timezone: 'Asia/Shanghai'})
+ *     public async report(): Promise<void> {
+ *     }
+ * }
+ *
+ * Application.run({
+ *     id: 'worker.app',
+ *     name: 'Worker',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [MaintenanceController],
+ *             schedule: scheduleEntrypoint({
+ *                 onError: (error, action): void => console.error(`${action.name} failed`, error),
+ *                 onSkip: (action, scheduledAt, reason): void => console.warn(`${action.name} skipped (${reason})`)
+ *             })
+ *         })
+ *     }
+ * })
+ * ```
+ */
+export function scheduleEntrypoint(options = {}) {
+    const timers = new Set();
+    let stopped = false;
+    //The locks of the runs ended, kept a while: released at once when the adapter stops
+    const keptLocks = new Map();
+    const releaseKept = (lock) => {
+        clearTimeout(keptLocks.get(lock));
+        keptLocks.delete(lock);
+        lock.release().catch(() => undefined);
+    };
+    /**
+     * Run a function at a time
+     * @param at
+     * @param run
+     */
+    const at = (time, run) => {
+        if (stopped)
+            return;
+        const delay = time - Date.now();
+        const timer = setTimeout(() => {
+            timers.delete(timer);
+            //The delays longer than a timer allows are waited in several times
+            delay > MAX_DELAY ? at(time, run) : run();
+        }, Math.max(0, Math.min(delay, MAX_DELAY)));
+        timers.add(timer);
+    };
+    /**
+     * Write a failed run to the log of the application
+     * @param runtime
+     * @param error
+     * @param action
+     * @param context
+     */
+    const report = async (runtime, error, action, context) => {
+        if (options.onError)
+            return await options.onError(error, action, context);
+        await log(runtime, error, `The scheduled action ${action.name} (${context.schedule}) failed`);
+    };
+    /**
+     * Write an error to the log of the application
+     * @param runtime
+     * @param error
+     * @param message
+     */
+    const log = async (runtime, error, message) => {
+        try {
+            const logger = await runtime.getObject('log');
+            logger.error(error, message);
+        }
+        catch {
+            console.error(`${message}:`, error);
+        }
+    };
+    return {
+        channel: 'schedule',
+        definition: ScheduleChannel,
+        name: options.name,
+        middlewares: options.middlewares,
+        start: (runtime) => {
+            const states = new Map();
+            //The components of the locks of the exclusive actions
+            const locks = new Map();
+            /**
+             * The time between a run of an action and its next one
+             * @param action
+             * @param scheduledAt
+             */
+            const period = (action, scheduledAt) => {
+                if (action.address.every !== undefined)
+                    return action.address.every;
+                const next = new Cron(action.address.cron, action.address.timezone).next(scheduledAt);
+                return next ? next.getTime() - scheduledAt : MAX_HOLD * 2;
+            };
+            /**
+             * Tell a run skipped: an error of the handler is written to the log, the schedule goes on
+             * @param action
+             * @param scheduledAt
+             * @param reason
+             */
+            const skip = (action, scheduledAt, reason) => {
+                try {
+                    options.onSkip?.(action, new Date(scheduledAt), reason);
+                }
+                catch (error) {
+                    void log(runtime, error, `The onSkip handler of the scheduled action ${action.name} failed`);
+                }
+            };
+            /**
+             * Run an action
+             * @param action
+             * @param scheduledAt
+             */
+            const fire = (action, scheduledAt) => {
+                if (stopped)
+                    return;
+                const state = states.get(action);
+                if (state.running && !action.address.overlap)
+                    return skip(action, scheduledAt, 'overlap');
+                state.running++;
+                const exclusive = locks.get(action);
+                void (async () => {
+                    let lock;
+                    try {
+                        if (exclusive) {
+                            lock = await exclusive.tryAcquire(`schedule:${action.address.exclusiveKey ?? action.name}`);
+                            //Run by another instance
+                            if (!lock)
+                                return skip(action, scheduledAt, 'exclusive');
+                        }
+                        state.runs++;
+                        const context = new ScheduleContext({ schedule: action.address.schedule, scheduledAt: new Date(scheduledAt), run: state.runs, data: {} });
+                        await runtime.dispatchTo(action, context).catch((error) => report(runtime, error, action, context));
+                    }
+                    catch (error) {
+                        await log(runtime, error, `The lock of the scheduled action ${action.name} failed`);
+                    }
+                    finally {
+                        state.running--;
+                        if (lock) {
+                            //Kept until the half of its period (30 s at most): the instances whose clocks are late skip
+                            //the run too
+                            const held = lock;
+                            const remaining = scheduledAt + Math.min(period(action, scheduledAt) / 2, MAX_HOLD) - Date.now();
+                            if (remaining <= 0 || stopped) {
+                                held.release().catch(() => undefined);
+                            }
+                            else {
+                                const timer = setTimeout(() => releaseKept(held), remaining);
+                                keptLocks.set(held, timer);
+                            }
+                        }
+                    }
+                })().catch(() => undefined);
+            };
+            /**
+             * Plan the runs of an action
+             * @param action
+             */
+            const plan = (action) => {
+                if (action.address.every !== undefined) {
+                    const interval = action.address.every;
+                    //The exclusive ones aligned on the multiples of their interval: the same times in every instance
+                    let next = action.address.exclusive ? Math.ceil((Date.now() + 1) / interval) * interval : Date.now() + interval;
+                    const tick = () => {
+                        fire(action, next);
+                        //The runs keep their pace: the times missed (the process was suspended) are skipped
+                        next += interval;
+                        const now = Date.now();
+                        if (next <= now)
+                            next += Math.ceil((now - next + 1) / interval) * interval;
+                        at(next, tick);
+                    };
+                    at(next, tick);
+                }
+                else {
+                    const cron = new Cron(action.address.cron, action.address.timezone);
+                    const schedule = (after) => {
+                        const time = cron.next(after);
+                        if (!time)
+                            return;
+                        at(time.getTime(), () => {
+                            fire(action, time.getTime());
+                            schedule(Math.max(Date.now(), time.getTime()));
+                        });
+                    };
+                    schedule(Date.now());
+                }
+            };
+            //The runs begin once the application launched: its objects and the other adapters are ready
+            //Only resolved, fire() reports the errors of the runs
+            void runtime.ready.then(async () => {
+                if (stopped)
+                    return;
+                for (const action of runtime.actions) {
+                    if (action.address.exclusive) {
+                        //Its locks: without them, it does not run (rather than in every instance)
+                        try {
+                            const component = await runtime.getObject(action.address.exclusive);
+                            if (typeof component?.tryAcquire !== 'function')
+                                throw new Error(`The object ${action.address.exclusive} is not a component of the locks (the Mutex of @lakutata/mutex)`);
+                            locks.set(action, component);
+                        }
+                        catch (error) {
+                            await log(runtime, error, `The exclusive scheduled action ${action.name} does not run: its component of the locks ${action.address.exclusive} is not there`);
+                            continue;
+                        }
+                    }
+                    if (stopped)
+                        return;
+                    states.set(action, { running: 0, runs: 0 });
+                    if (action.address.immediate)
+                        fire(action, Date.now());
+                    plan(action);
+                }
+            });
+        },
+        stop: () => {
+            //No new run, the runs in progress are waited for by the entrypoint
+            stopped = true;
+            timers.forEach((timer) => clearTimeout(timer));
+            timers.clear();
+            [...keptLocks.keys()].forEach(releaseKept);
+        }
+    };
+}

package/dist/esm/adapter/socket.io/SocketIOServiceEntrypoint.js

@@ -0,0 +1,212 @@
+import { Server as SocketIOServer } from 'socket.io';
+import { createServer } from 'node:http';
+import { ServiceContext } from '../../context/ServiceContext.js';
+import { ServiceChannel } from '../../channel/BuiltinChannels.js';
+import { ServiceResponseCodec } from '../../lib/ServiceResponseCodec.js';
+import { EntrypointStoppedException } from '../../exceptions/EntrypointStoppedException.js';
+/**
+ * Get the socket.io socket that sent a service action's request, when {@link socketIOServiceEntrypoint} serves it (to
+ * read its handshake, join it to rooms, emit to it…).
+ * @param context The service action's context (`this.context` in a controller).
+ * @returns The socket, or `undefined` when another adapter serves the request.
+ * @example
+ * ```typescript
+ * import {Controller, ServiceContext} from 'lakutata/com/entrypoint'
+ * import {ServiceAction} from 'lakutata/decorator/ctrl'
+ * import {socketOfContext} from 'lakutata/adapter/socket.io'
+ *
+ * class RoomController extends Controller {
+ *     //socket.emit('message', {cmd: 'room.join', room: 'lobby'}, (response) => …)
+ *     @ServiceAction({cmd: 'room.join'})
+ *     public async join(input: {room: string}): Promise<void> {
+ *         await socketOfContext(this.context as ServiceContext)?.join(input.room)
+ *     }
+ * }
+ * ```
+ */
+export function socketOfContext(context) {
+    return context.socket;
+}
+/**
+ * The id of the client of a socket: the one it gives when it connects (its auth.id, its id header, its id query), its
+ * own id otherwise
+ * @param socket
+ */
+function clientIdOf(socket) {
+    const given = socket.handshake.auth?.id ?? socket.handshake.headers.id ?? socket.handshake.query.id;
+    const id = Array.isArray(given) ? given[0] : given;
+    return typeof id === 'string' && id && id.length <= 200 ? id : socket.id;
+}
+/**
+ * Create a service adapter of an entrypoint served by socket.io. It needs the optional peer dependency `socket.io`
+ * (and `socket.io-client` on the clients).
+ *
+ * A request is an emit of the request event (`'message'` by default) whose data holds the action's pattern and input,
+ * with an acknowledgement callback receiving the response `{success, error, payload}` (see `ServiceResponseCodec`):
+ * `payload` is the result, or `error` the whole error object when the action failed (no matching action, validation…).
+ * An emit without an acknowledgement still runs the action.
+ *
+ * Each socket belongs to a client, identified by the id it gives when it connects (`auth.id`, else the `id` header,
+ * else the `id` query parameter; at most 200 characters), else by its socket id; its requests carry it as
+ * `ServiceContext.clientId`. The events pushed by `Entrypoint.notify` are emitted to every socket of the client, those
+ * of `Entrypoint.broadcast` to every socket of the namespace, with the event's arguments as the emit's arguments.
+ *
+ * When a socket disconnects, its requests in progress are aborted (their abort signal fires). When the entrypoint
+ * stops, the new requests are answered with an `EntrypointStoppedException` error; once the requests in progress end,
+ * the socket.io server is closed (the sockets disconnected, with the attached HTTP server left open).
+ * @param options The adapter options; by default it listens on port 3000 of all the interfaces with a server of its own.
+ * @returns The adapter, to give to the `service` option of `buildEntrypoints`.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {ServiceAction} from 'lakutata/decorator/ctrl'
+ * import {socketIOServiceEntrypoint} from 'lakutata/adapter/socket.io'
+ * import {io} from 'socket.io-client'
+ *
+ * class EchoController extends Controller {
+ *     @ServiceAction({cmd: 'echo'})
+ *     public async echo(input: {text: string}): Promise<string> {
+ *         return input.text
+ *     }
+ * }
+ *
+ * Application.run({
+ *     id: 'echo.service',
+ *     name: 'Echo',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [EchoController],
+ *             service: socketIOServiceEntrypoint({port: 3000, options: {cors: {origin: '*'}}})
+ *         })
+ *     }
+ * })
+ *
+ * //A client, identified as client-1 (the events pushed by entrypoint.notify('client-1', 'progress', 50) reach it)
+ * const socket = io('http://localhost:3000', {auth: {id: 'client-1'}})
+ * socket.on('progress', (percent: number): void => console.log(`${percent}%`))
+ * socket.emit('message', {cmd: 'echo', text: 'hi'}, (response: {success: boolean, error: unknown, payload: unknown}): void => {
+ *     //{success: true, error: null, payload: 'hi'}
+ *     console.log(response)
+ * })
+ * ```
+ */
+export function socketIOServiceEntrypoint(options = {}) {
+    const event = options.event ?? 'message';
+    let io;
+    let namespace;
+    let ownServer;
+    let sharedServer = false;
+    let stopping = false;
+    let onConnection;
+    //The sockets of each client (a client may connect several times)
+    const clients = new Map();
+    //The removal of the listeners the adapter added to each socket (the sockets of a given io outlive the adapter)
+    const detachers = new Map();
+    return {
+        channel: 'service',
+        definition: ServiceChannel,
+        name: options.name,
+        middlewares: options.middlewares,
+        start: async (runtime) => {
+            const attachTo = typeof options.server === 'function' ? options.server() : options.server;
+            if (options.io) {
+                io = options.io;
+            }
+            else if (attachTo) {
+                io = new SocketIOServer(attachTo, options.options);
+                sharedServer = true;
+            }
+            else {
+                ownServer = createServer();
+                io = new SocketIOServer(ownServer, options.options);
+            }
+            namespace = io.of(options.namespace ?? '/');
+            onConnection = (socket) => {
+                const clientId = clientIdOf(socket);
+                if (!clients.has(clientId))
+                    clients.set(clientId, new Set());
+                clients.get(clientId).add(socket);
+                //The requests of a socket in progress, aborted when it disconnects
+                const requests = new Set();
+                const onDisconnect = () => {
+                    requests.forEach((request) => request.abort());
+                    clients.get(clientId)?.delete(socket);
+                    if (!clients.get(clientId)?.size)
+                        clients.delete(clientId);
+                    detachers.delete(socket);
+                };
+                const onRequest = async (data, acknowledge) => {
+                    const reply = (response) => {
+                        if (typeof acknowledge === 'function')
+                            acknowledge(response);
+                    };
+                    if (stopping)
+                        return reply(ServiceResponseCodec.encodeError(new EntrypointStoppedException('The entrypoint is stopping')));
+                    const request = new AbortController();
+                    requests.add(request);
+                    try {
+                        const context = new ServiceContext({ data: data && typeof data === 'object' ? data : {}, socket: socket, clientId: clientId });
+                        reply(ServiceResponseCodec.encode(await runtime.dispatch(context, { signal: request.signal }), false));
+                    }
+                    catch (error) {
+                        reply(ServiceResponseCodec.encodeError(error));
+                    }
+                    finally {
+                        requests.delete(request);
+                    }
+                };
+                socket.once('disconnect', onDisconnect);
+                const onEvent = (data, acknowledge) => void onRequest(data, acknowledge);
+                socket.on(event, onEvent);
+                detachers.set(socket, () => {
+                    socket.off('disconnect', onDisconnect);
+                    socket.off(event, onEvent);
+                });
+            };
+            namespace.on('connection', onConnection);
+            if (ownServer) {
+                //The adapter starts once its server listens (an occupied port fails the start)
+                await new Promise((resolve, reject) => {
+                    ownServer.once('error', reject).listen(options.port ?? 3000, options.host, () => {
+                        ownServer.off('error', reject);
+                        resolve();
+                    });
+                });
+            }
+            await options.listening?.(io, ownServer ?? attachTo);
+        },
+        stop: () => {
+            //The new requests are refused, the requests in progress end
+            stopping = true;
+        },
+        notify: (clientId, name, args) => {
+            const sockets = clients.get(clientId);
+            sockets?.forEach((socket) => socket.emit(name, ...args));
+            return !!sockets?.size;
+        },
+        broadcast: (name, args) => {
+            if (!namespace)
+                return 0;
+            namespace.emit(name, ...args);
+            return clients.size;
+        },
+        close: async () => {
+            clients.clear();
+            if (namespace && onConnection)
+                namespace.off('connection', onConnection);
+            //The sockets connected keep no listener of the adapter (they stay connected to a given io)
+            detachers.forEach((detach) => detach());
+            detachers.clear();
+            if (!io || options.io)
+                return;
+            if (sharedServer) {
+                //The server is closed by its owner: the clients are disconnected and the transports closed
+                io.disconnectSockets(true);
+                io.engine.close();
+                return;
+            }
+            await new Promise((resolve) => void io.close(() => resolve()));
+        }
+    };
+}

package/dist/esm/channel/BuiltinChannels.js

@@ -0,0 +1,125 @@
+import { getObjectPropertyPaths, uniqueArray } from '@lakutata/utils';
+import { defineChannel } from './Channel.js';
+import { PatternManager } from '../lib/pattern/PatternManager.js';
+import { stringifyPattern } from '../lib/StringifyPattern.js';
+import { prefixCommand, prefixPattern, prefixRoute } from '../lib/Prefix.js';
+import { ContextType } from '../context/BaseContext.js';
+import { ControllerActionNotFoundException } from '../exceptions/ControllerActionNotFoundException.js';
+import { unsetValue } from '../lib/UnsetValue.js';
+/**
+ * A lookup by exact key, falling back to the glob patterns
+ * @param entries
+ * @param key
+ * @param subject
+ */
+function exactMatcher(entries, key, subject) {
+    const exact = new Map();
+    const patterns = new PatternManager();
+    for (const entry of entries) {
+        exact.set(key(entry.details.pattern), entry);
+        patterns.add(entry.details.pattern, entry);
+    }
+    return {
+        match: (context) => {
+            const pattern = subject(context);
+            const entry = exact.get(key(pattern)) ?? patterns.find(pattern);
+            return entry ? { entry: entry } : undefined;
+        }
+    };
+}
+/**
+ * The key of an HTTP action
+ * @param pattern
+ */
+function httpKey(pattern) {
+    return `${pattern.method}\u0000${pattern.route}`;
+}
+/**
+ * The HTTP channel, addressed by route and method
+ */
+export const HTTPChannel = defineChannel({
+    name: 'http',
+    kind: 'request',
+    contextType: ContextType.HTTP,
+    identify: (pattern) => pattern.route,
+    describe: (pattern) => ({ route: pattern.route }),
+    prefix: (prefix, pattern) => prefix.route === undefined ? undefined : { ...pattern, route: prefixRoute(prefix.route, pattern.route) },
+    createMatcher: (entries) => exactMatcher(entries, httpKey, (context) => ({
+        route: context.route,
+        method: context.method
+    })),
+    notFound: (context) => new ControllerActionNotFoundException('Route \'{route}\' not found', context)
+});
+/**
+ * The CLI channel, addressed by command
+ */
+export const CLIChannel = defineChannel({
+    name: 'cli',
+    kind: 'request',
+    contextType: ContextType.CLI,
+    identify: (pattern) => pattern.command,
+    describe: (pattern) => ({ command: pattern.command }),
+    prefix: (prefix, pattern) => prefix.command === undefined ? undefined : { command: prefixCommand(prefix.command, pattern.command) },
+    createMatcher: (entries) => exactMatcher(entries, (pattern) => pattern.command, (context) => ({ command: context.command })),
+    notFound: () => new ControllerActionNotFoundException('Command not found')
+});
+/**
+ * The service channel, addressed by pattern
+ */
+export const ServiceChannel = defineChannel({
+    name: 'service',
+    kind: 'request',
+    contextType: ContextType.SERVICE,
+    identify: (pattern) => stringifyPattern(pattern),
+    describe: (pattern) => ({ pattern: pattern }),
+    prefix: (prefix, pattern) => prefix.pattern === undefined ? undefined : prefixPattern(prefix.pattern, pattern),
+    createMatcher: (entries) => {
+        const patterns = new PatternManager();
+        for (const entry of entries)
+            patterns.add(entry.details.pattern, entry);
+        return {
+            match: (context) => {
+                const entry = patterns.find(context.input);
+                return entry ? { entry: entry } : undefined;
+            }
+        };
+    },
+    //The keys of the pattern are not a part of the action input
+    prepare: (entry, context) => {
+        const patternPaths = getObjectPropertyPaths(entry.details.pattern);
+        patternPaths.forEach((path) => unsetValue(context.data, path));
+        const checkPatternPaths = uniqueArray(patternPaths
+            .map((path) => path.substring(0, path.lastIndexOf('.')))
+            .filter((path) => !!path));
+        checkPatternPaths.forEach((path) => {
+            let target = context.data;
+            path.split('.').forEach((key) => target = target[key] ? target[key] : undefined);
+            if (target && !Object.keys(target).length)
+                unsetValue(context.data, path);
+        });
+    },
+    notFound: () => new ControllerActionNotFoundException('Controller action not found')
+});
+/**
+ * The schedule channel: no external caller, each action is run by the timers of the schedule adapter.
+ * The address of an action is its schedule, with the key telling apart the actions of a same schedule
+ */
+export const ScheduleChannel = defineChannel({
+    name: 'schedule',
+    kind: 'trigger',
+    contextType: ContextType.SCHEDULE,
+    identify: (pattern) => `${pattern.schedule}#${pattern.key}`,
+    describe: (pattern) => {
+        const { key, ...schedule } = pattern;
+        void key;
+        return schedule;
+    },
+    createMatcher: (entries) => ({
+        //The runs are dispatched to their action: a context is matched by its schedule
+        match: (context) => {
+            const entry = entries.find((candidate) => candidate.details.pattern.schedule === context.schedule);
+            return entry ? { entry: entry } : undefined;
+        }
+    }),
+    notFound: (context) => new ControllerActionNotFoundException('No action is scheduled {schedule}', { schedule: context.schedule })
+});