@tmlmobilidade/fastify 20251202.1817.5

package/dist/authorization-middleware.d.ts

@@ -0,0 +1,17 @@
+import { FastifyReply, type FastifyRequest } from './fastify-service.js';
+import { type ActionsOf, type Organization, type Permission, type User } from '@tmlmobilidade/types';
+declare module 'fastify' {
+    interface FastifyRequest {
+        me: User;
+        organization: Organization;
+        permissions: Permission[];
+    }
+}
+/**
+ * Creates an authorization middleware that validates user authentication and permissions.
+ * @param scope The permission scope to check (optional).
+ * @param action The permission action(s) to check (optional).
+ * @param requireAll Whether all actions must be true or at least one must be true.
+ * @returns Fastify middleware function.
+ */
+export declare function authorizationMiddleware<S extends Permission['scope']>(scope?: S, actions?: ActionsOf<S>[], requireAll?: boolean): (request: FastifyRequest, reply: FastifyReply<string>) => Promise<void>;

package/dist/authorization-middleware.js

@@ -0,0 +1,59 @@
+/* * */
+import { HttpException, HttpStatus } from '@tmlmobilidade/consts';
+import { AUTH_SESSION_COOKIE_NAME, authProvider } from '@tmlmobilidade/interfaces';
+import { PermissionCatalog } from '@tmlmobilidade/types';
+/**
+ * Creates an authorization middleware that validates user authentication and permissions.
+ * @param scope The permission scope to check (optional).
+ * @param action The permission action(s) to check (optional).
+ * @param requireAll Whether all actions must be true or at least one must be true.
+ * @returns Fastify middleware function.
+ */
+export function authorizationMiddleware(scope, actions, requireAll = false) {
+    return async (request, reply) => {
+        //
+        //
+        // Extract the session token from request cookies
+        const sessionToken = request.cookies.session_token;
+        if (!sessionToken) {
+            return reply
+                .setCookie(AUTH_SESSION_COOKIE_NAME, '', { httpOnly: true, maxAge: 0, path: '/', sameSite: 'lax', secure: true })
+                .send({ data: 'Session token is missing', error: null, statusCode: HttpStatus.UNAUTHORIZED });
+        }
+        //
+        // Get user and permissions from cache or auth provider.
+        // Cache is per session token, and valid for 5 minutes.
+        // This reduces the number of calls to the auth provider.
+        try {
+            const userData = await authProvider.getUserFromSessionToken(sessionToken);
+            const permissionsData = await authProvider.getPermissionsFromSessionToken(sessionToken);
+            const organizationData = await authProvider.getOrganizationFromSessionToken(sessionToken);
+            if (!userData || !permissionsData || !organizationData) {
+                return reply
+                    .setCookie(AUTH_SESSION_COOKIE_NAME, '', { httpOnly: true, maxAge: 0, path: '/', sameSite: 'lax', secure: true })
+                    .send({ data: 'Session token is missing', error: null, statusCode: HttpStatus.UNAUTHORIZED });
+            }
+            request.me = userData;
+            request.permissions = permissionsData;
+            request.organization = organizationData;
+        }
+        catch (error) {
+            console.error('Authorization Middleware Error:', error);
+            return reply
+                .setCookie(AUTH_SESSION_COOKIE_NAME, '', { httpOnly: true, maxAge: 0, path: '/', sameSite: 'lax', secure: true })
+                .send({ data: 'Session token is missing', error: null, statusCode: HttpStatus.UNAUTHORIZED });
+        }
+        //
+        // Evaluate the retrieved permissions,
+        // if scope and actions are provided.
+        if (!scope)
+            return;
+        const permissionChecks = actions.map(action => PermissionCatalog.hasPermission(request.permissions, scope, action));
+        const isAllowed = requireAll
+            ? permissionChecks.every(Boolean) // all must be true
+            : permissionChecks.some(Boolean); // at least one must be true
+        if (!isAllowed)
+            throw new HttpException(HttpStatus.FORBIDDEN, `Insufficient permissions | User: ${request.me._id} | Scope: "${scope}" | Actions: [${actions.join(',')}]`);
+        //
+    };
+}

package/dist/fastify-service.d.ts

@@ -0,0 +1,84 @@
+import '@fastify/cors';
+import '@fastify/cookie';
+import '@fastify/multipart';
+import { HttpResponse, WithPagination } from '@tmlmobilidade/utils';
+import { type FastifyInstance as FastifyInstanceType, type FastifyReply as FastifyReplyType } from 'fastify';
+import { type ContextConfigDefault, type FastifyBaseLogger, type FastifySchema, type FastifyServerOptions, type FastifyTypeProviderDefault, type RawReplyDefaultExpression, type RawRequestDefaultExpression, type RawServerBase, type RawServerDefault, type RouteGenericInterface } from 'fastify';
+export { type FastifyRequest } from 'fastify';
+export type FastifyReply<T> = FastifyReplyType<RouteGenericInterface, RawServerBase, RawRequestDefaultExpression<RawServerBase>, RawReplyDefaultExpression<RawServerBase>, ContextConfigDefault, FastifySchema, FastifyTypeProviderDefault, HttpResponse<T> | ReadableStream | WithPagination<HttpResponse<T>>>;
+export type FastifyResponse<T> = FastifyReplyType<RouteGenericInterface & {
+    Reply: HttpResponse<T> | WithPagination<HttpResponse<T>>;
+}, RawServerBase, RawRequestDefaultExpression<RawServerBase>, RawReplyDefaultExpression<RawServerBase>, ContextConfigDefault, FastifySchema, FastifyTypeProviderDefault, HttpResponse<T> | WithPagination<HttpResponse<T>>>;
+export type FastifyInstance = FastifyInstanceType<RawServerDefault, RawRequestDefaultExpression, RawReplyDefaultExpression, FastifyBaseLogger, FastifyTypeProviderDefault>;
+/**
+ * FastifyServiceOptions interface defines the options for the Fastify server.
+ * It extends FastifyServerOptions and adds optional properties for origin and port.
+ */
+export interface FastifyServiceOptions extends FastifyServerOptions {
+    /**
+     * The host on which the Fastify server will listen.
+     * If not provided, it defaults to '0.0.0.0'.
+     * @default '0.0.0.0'
+     */
+    host?: string;
+    /**
+     * The origin for CORS requests.
+     * Defaults to `true` if not provided.
+     * @default true
+     * @example 'https://example.com'
+     */
+    origin?: RegExp | string | true;
+    /**
+     * The port on which the Fastify server will listen.
+     * If not provided, it defaults to 5050.
+     * @default 5050
+     */
+    port?: number;
+}
+/**
+ * FastifyService is a singleton class that provides a Fastify server instance.
+ * It allows for setting up routes, plugins, and starting/stopping the server.
+ * This class is designed to be used as a service in a Node.js application.
+ * It uses the Fastify framework for building web applications and APIs.
+ */
+export declare class FastifyService {
+    private static _instance;
+    readonly server: FastifyInstance;
+    private readonly options;
+    /**
+     * Creates an instance of FastifyService.
+     * @param options The options for the Fastify server.
+     */
+    private constructor();
+    /**
+     * Gets the singleton instance of FastifyService.
+     * @param options The options for the Fastify server.
+     * @return The singleton instance of FastifyService.
+     */
+    static getInstance(options?: FastifyServiceOptions): FastifyService;
+    /**
+     * Starts the Fastify server.
+     * @return A promise that resolves to the URL of the Fastify server.
+     * @throws Will throw an error if the server fails to start.
+     */
+    start(): Promise<string>;
+    /**
+     * Stops the Fastify server.
+     * @return A promise that resolves when the server is stopped.
+     */
+    stop(): Promise<void>;
+    /**
+     * Sets the URL of the Fastify server.
+     * @return The URL of the Fastify server.
+     */
+    private _setupDefaultRoutes;
+    /**
+     * Sets up hooks for the Fastify server including error handling and response processing.
+     */
+    private _setupHooks;
+    /**
+     * Sets up the plugins for the Fastify server.
+     * @return A promise that resolves when the plugins are set up.
+     */
+    private _setupPlugins;
+}

package/dist/fastify-service.js

@@ -0,0 +1,251 @@
+/* * */
+import '@fastify/cors';
+import '@fastify/cookie';
+import '@fastify/multipart';
+/* * */
+import fastifyCookie from '@fastify/cookie';
+import fastifyCors from '@fastify/cors';
+import oneLineLogger from '@fastify/one-line-logger';
+import { HttpException, HttpStatus } from '@tmlmobilidade/consts';
+import fastify from 'fastify';
+const defaultFastifyServiceOptions = {
+    bodyLimit: 1024 * 1024 * 10, // 10MB
+    host: '0.0.0.0',
+    logger: true,
+    origin: true,
+    port: 5050,
+    routerOptions: {
+        ignoreTrailingSlash: true,
+    },
+};
+const loggerOptions = {
+    level: 'debug',
+    stream: oneLineLogger({
+        colorize: true, // nice colors,
+        colorizeObjects: true,
+        messageFormat(log, messageKey, _, extras) {
+            const c = extras.colors;
+            const palette = {
+                error: c.redBright,
+                highlight: c.yellowBright, // URLs / routes
+                message: c.whiteBright,
+                method: c.greenBright,
+                methodLabel: c.gray,
+                pipe: c.cyanBright,
+                reqId: c.cyanBright,
+                reqIdLabel: c.gray,
+                stack: c.red,
+                status: c.yellowBright,
+                statusLabel: c.gray,
+                timestamp: c.cyanBright,
+            };
+            const colorize = (text) => {
+                const urlPattern = /(https?:\/\/[^\s]+)/g;
+                const routePattern = /Route "(.+?)"/g;
+                const pathPattern = /([A-Z]+):\/[^\s]+/g;
+                return text
+                    .replace(urlPattern, palette.highlight('$&'))
+                    .replace(routePattern, (_, r) => palette.highlight(`Route "${r}"`))
+                    .replace(pathPattern, palette.highlight('$&'));
+            };
+            const safe = (val, fallback = '') => typeof val === 'string' || typeof val === 'number' ? String(val) : fallback;
+            const formatMethod = (method) => {
+                if (!method)
+                    return '-----';
+                if (method === 'GET' || method === 'PUT')
+                    return `${method}  `;
+                return method.padEnd(5, '-');
+            };
+            const timestamp = new Date(log.time).toLocaleString('pt-PT', {
+                day: '2-digit',
+                hour: '2-digit',
+                minute: '2-digit',
+                month: '2-digit',
+                second: '2-digit',
+                year: 'numeric',
+            });
+            const reqId = log.reqId ? safe(log.reqId).padEnd(10, ' ') : Array(10).fill('-').join('');
+            const statusCode = typeof log.res === 'object' && log.res && 'statusCode' in log.res ? safe(log.res.statusCode).padEnd(3, '-') : '---';
+            const method = typeof log.req === 'object' && log.req && 'method' in log.req ? formatMethod(log.req.method ?? '') : '-----';
+            // Extract error information
+            // Pino serializes errors, so log.err is an object with type, message, stack, etc.
+            const errorObj = log.err || log.error;
+            let errorMessage = safe(log[messageKey]);
+            let errorStack;
+            if (errorObj) {
+                // Pino serialized error object
+                errorMessage = errorObj.message || errorMessage;
+                errorStack = errorObj.stack;
+            }
+            else if (log[messageKey] instanceof Error) {
+                // Direct Error instance (shouldn't happen with Pino, but just in case)
+                errorMessage = log[messageKey].message || errorMessage;
+                errorStack = log[messageKey].stack;
+            }
+            const message = palette.message(colorize(errorMessage));
+            // Add stack trace on new lines, indented for readability
+            const stackTrace = errorStack ? `\n${palette.stack(errorStack.split('\n').map(line => `  ${line}`).join('\n'))}` : '';
+            const parts = [
+                palette.timestamp(timestamp),
+                palette.reqIdLabel(`reqId: ${palette.reqId(reqId)}`),
+                palette.statusLabel(`statusCode: ${palette.status(statusCode)}`),
+                palette.methodLabel(`Method: ${palette.method(method)}`),
+                message,
+            ];
+            return palette.pipe(parts.join(' | ')) + stackTrace;
+        },
+    }),
+};
+/**
+ * FastifyService is a singleton class that provides a Fastify server instance.
+ * It allows for setting up routes, plugins, and starting/stopping the server.
+ * This class is designed to be used as a service in a Node.js application.
+ * It uses the Fastify framework for building web applications and APIs.
+ */
+export class FastifyService {
+    //
+    static _instance;
+    server;
+    options;
+    /**
+     * Creates an instance of FastifyService.
+     * @param options The options for the Fastify server.
+     */
+    constructor(options) {
+        const mergedOptions = { ...defaultFastifyServiceOptions, ...options };
+        this.server = fastify({ ...mergedOptions, logger: loggerOptions });
+        this.options = mergedOptions;
+        this._setupDefaultRoutes();
+        this._setupPlugins();
+    }
+    /**
+     * Gets the singleton instance of FastifyService.
+     * @param options The options for the Fastify server.
+     * @return The singleton instance of FastifyService.
+     */
+    static getInstance(options) {
+        if (!FastifyService._instance) {
+            // Create a new instance if it doesn't exist yet
+            FastifyService._instance = new FastifyService(options || {});
+            FastifyService._instance._setupHooks();
+        }
+        // Return the existing instance
+        return FastifyService._instance;
+    }
+    /**
+     * Starts the Fastify server.
+     * @return A promise that resolves to the URL of the Fastify server.
+     * @throws Will throw an error if the server fails to start.
+     */
+    async start() {
+        try {
+            const serverUrl = await this.server.listen({ host: this.options.host, port: this.options.port });
+            this.server.log.info(`Server is running at ${serverUrl}`);
+            this.server.log.info(`CORS enabled for origin: ${this.options.origin}`);
+            this.server.log.info(`Listening on ${this.options.host}:${this.options.port}`);
+            return serverUrl;
+        }
+        catch (error) {
+            this.server.log.error({ error, message: 'Error starting server.' });
+            process.exit(1);
+        }
+    }
+    /**
+     * Stops the Fastify server.
+     * @return A promise that resolves when the server is stopped.
+     */
+    async stop() {
+        try {
+            await this.server.close();
+            console.log('Fastify server stopped.');
+        }
+        catch (error) {
+            this.server.log.error({ err: error }, error instanceof Error ? error.message : 'Error stopping server');
+            process.exit(1);
+        }
+    }
+    /**
+     * Sets the URL of the Fastify server.
+     * @return The URL of the Fastify server.
+     */
+    _setupDefaultRoutes() {
+        this.server.get('/', (req, res) => {
+            res.send('Jusi was here!');
+        });
+    }
+    /**
+     * Sets up hooks for the Fastify server including error handling and response processing.
+     */
+    _setupHooks() {
+        /**
+         * Sets a global error handler for the Fastify server instance.
+         * This handler checks if the error is an instance of HttpException.
+         * If so, it sends a response with the appropriate status code and error message.
+         * This ensures consistent error responses for HTTP exceptions throughout the application.
+         */
+        this.server.setErrorHandler((error, _, reply) => {
+            // Log the error with full stack trace
+            const errorMessage = error instanceof Error ? error.message : 'Unhandled error';
+            this.server.log.error({ err: error }, errorMessage);
+            // Handle HttpException errors
+            if (error instanceof HttpException) {
+                reply
+                    .status(error.statusCode)
+                    .send({
+                    data: undefined,
+                    error: error.message,
+                    statusCode: error.statusCode,
+                });
+            }
+            else {
+                reply
+                    .status(HttpStatus.INTERNAL_SERVER_ERROR)
+                    .send({
+                    data: undefined,
+                    error: 'Internal server error',
+                    statusCode: HttpStatus.INTERNAL_SERVER_ERROR,
+                });
+            }
+        });
+        /**
+         * Adds an 'onSend' hook to the Fastify server instance.
+         * This hook intercepts every outgoing response before it is sent.
+         * It parses the payload as a JSON object (assuming it matches the HttpResponse<T> structure),
+         * and sets the HTTP status code of the reply to the value of 'statusCode' in the payload,
+         * defaulting to HttpStatus.OK if not present.
+         * This ensures that the HTTP status code in the response matches the statusCode property
+         * in the application's response payload, providing consistent status handling.
+         */
+        this.server.addHook('onSend', (_, reply, payload, done) => {
+            try {
+                const payloadJson = JSON.parse(payload);
+                reply.code(payloadJson.statusCode ?? HttpStatus.OK);
+            }
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            catch (error) {
+                // Do nothing
+            }
+            finally {
+                done();
+            }
+        });
+    }
+    /**
+     * Sets up the plugins for the Fastify server.
+     * @return A promise that resolves when the plugins are set up.
+     */
+    async _setupPlugins() {
+        // CORS plugin
+        await this.server.register(fastifyCors, {
+            credentials: true,
+            methods: ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'OPTIONS', 'DELETE'],
+            origin: this.options.origin,
+        });
+        // Cookie plugin
+        await this.server.register(fastifyCookie);
+        // Multipart plugin
+        // await this.server.register(fastifyMultipart, {
+        // 	limits: { fileSize: this.options.bodyLimit },
+        // });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './authorization-middleware.js';
+export * from './fastify-service.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './authorization-middleware.js';
+export * from './fastify-service.js';

package/package.json

@@ -0,0 +1,58 @@
+{
+	"name": "@tmlmobilidade/fastify",
+	"version": "20251202.1817.5",
+	"author": {
+		"email": "iso@tmlmobilidade.pt",
+		"name": "TML-ISO"
+	},
+	"license": "AGPL-3.0-or-later",
+	"homepage": "https://github.com/tmlmobilidade/go#readme",
+	"bugs": {
+		"url": "https://github.com/tmlmobilidade/go/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/tmlmobilidade/go.git"
+	},
+	"keywords": [
+		"public transit",
+		"tml",
+		"transportes metropolitanos de lisboa",
+		"go"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"files": [
+		"dist"
+	],
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsc && resolve-tspaths",
+		"lint": "eslint ./src && tsc --noEmit",
+		"lint:fix": "eslint . --fix",
+		"watch": "tsc-watch --onSuccess 'resolve-tspaths'"
+	},
+	"dependencies": {
+		"@fastify/cookie": "11.0.2",
+		"@fastify/cors": "11.1.0",
+		"@fastify/multipart": "9.3.0",
+		"@fastify/one-line-logger": "^2.0.2",
+		"@tmlmobilidade/consts": "*",
+		"@tmlmobilidade/interfaces": "*",
+		"@tmlmobilidade/utils": "*",
+		"fastify": "5.6.2",
+		"pino": "^10.1.0",
+		"pino-pretty": "^13.1.3"
+	},
+	"devDependencies": {
+		"@tmlmobilidade/tsconfig": "*",
+		"@tmlmobilidade/types": "*",
+		"@types/node": "24.10.1",
+		"resolve-tspaths": "0.8.23",
+		"tsc-watch": "7.2.0",
+		"typescript": "5.9.3"
+	}
+}