Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
7.6 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-or-later

import assert from 'node:assert/strict';
import {convertPathToOpenAPI} from '@fluxer/openapi/src/extractors/PathParameters';
import {discoverControllerFiles, extractRoutesFromControllers} from '@fluxer/openapi/src/extractors/RouteExtractor';
import {isExcludedRoutePath, OpenAPIGeneratorCatalog} from '@fluxer/openapi/src/generator/OpenAPIGeneratorCatalog';
import {OpenAPIOperationBuilder} from '@fluxer/openapi/src/generator/OpenAPIOperationBuilder';
import {collectReferencedSchemaNames} from '@fluxer/openapi/src/generator/OpenAPISchemaReferenceCollector';
import {loadSchemasIntoRegistry} from '@fluxer/openapi/src/generator/OpenAPISchemaRegistryLoader';
import type {
	OpenAPIGenerationResult,
	OpenAPIGeneratorOptions,
	OpenAPIRouteScope,
	OpenAPISchemaTarget,
	SkippedRoute,
} from '@fluxer/openapi/src/OpenAPIGenerationTypes';
import type {ExtractedRoute, OpenAPIDocument, OpenAPIPathItem, OpenAPISchema} from '@fluxer/openapi/src/OpenAPITypes';
import {SchemaRegistry} from '@fluxer/openapi/src/registry/SchemaRegistry';

interface PathBuildResult {
	readonly paths: Record<string, OpenAPIPathItem>;
	readonly operationCount: number;
	readonly skippedRoutes: ReadonlyArray<SkippedRoute>;
	readonly untemplatableRoutes: ReadonlyArray<SkippedRoute>;
}
function hasOpenAPIPathTemplate(routePath: string): boolean {
	return !routePath.includes('*') && !routePath.includes('{');
}
interface GeneratorSettings {
	readonly basePath: string;
	readonly title: string;
	readonly version: string;
	readonly description: string;
	readonly serverUrl: string;
	readonly routeScope: OpenAPIRouteScope;
	readonly schemaTarget: OpenAPISchemaTarget;
}
function createGeneratorSettings(options: OpenAPIGeneratorOptions): GeneratorSettings {
	return {
		basePath: options.basePath,
		title: options.title ?? 'Fluxer API',
		version: options.version ?? '1.0.0',
		description: options.description ?? 'The Fluxer API',
		serverUrl: options.serverUrl ?? 'https://api.fluxer.app',
		routeScope: options.routeScope ?? 'public',
		schemaTarget: options.schemaTarget ?? 'draft-2020-12',
	};
}
function describeRoute(route: ExtractedRoute, reason: string): SkippedRoute {
	return {
		method: route.method.toUpperCase(),
		path: route.path,
		source: `${route.controllerFile}:${route.lineNumber.toString()}`,
		reason,
	};
}
function isAdminRoute(route: ExtractedRoute): boolean {
	return route.path === '/admin' || route.path.startsWith('/admin/');
}
export class OpenAPIGenerator {
	private readonly settings: GeneratorSettings;
	constructor(options: OpenAPIGeneratorOptions) {
		this.settings = createGeneratorSettings(options);
	}
	public async generate(): Promise<OpenAPIDocument> {
		const result = await this.generateWithStats();
		return result.document;
	}
	public async generateWithStats(): Promise<OpenAPIGenerationResult> {
		const schemaRegistry = new SchemaRegistry(this.settings.schemaTarget, this.settings.routeScope !== 'admin');
		const controllerFiles = discoverControllerFiles(`${this.settings.basePath}/fluxer_api`);
		const routes = this.filterRoutesForScope(extractRoutesFromControllers(controllerFiles));
		await loadSchemasIntoRegistry(this.settings.basePath, schemaRegistry);
		const registeredSchemaCount = schemaRegistry.size;
		const operationBuilder = new OpenAPIOperationBuilder({
			schemaRegistry,
			usedOperationIds: new Set(),
		});
		const pathBuildResult = this.buildPaths(routes, operationBuilder);
		const allSchemas = schemaRegistry.getAllSchemas();
		const referencedSchemas = collectReferencedSchemaNames(pathBuildResult.paths, allSchemas);
		const publishedSchemas = this.filterPublishedSchemas(allSchemas, referencedSchemas);
		const tags = this.buildTags(routes);
		const document: OpenAPIDocument = {
			openapi: this.settings.schemaTarget === 'openapi-3.0' ? '3.0.3' : '3.1.0',
			security: [],
			info: {
				title: this.settings.title,
				version: this.settings.version,
				description: this.settings.description,
				contact: {
					name: 'Fluxer Platform AB',
					email: '[email protected]',
				},
				license: {
					name: 'AGPL-3.0',
					url: 'https://www.gnu.org/licenses/agpl-3.0.html',
				},
			},
			servers: [{url: this.settings.serverUrl, description: 'Production API'}],
			paths: pathBuildResult.paths,
			components: {
				schemas: publishedSchemas,
				securitySchemes: OpenAPIGeneratorCatalog.securitySchemes,
			},
			tags,
		};
		schemaRegistry.normalizeComponents(document);
		return {
			document,
			stats: {
				controllerCount: controllerFiles.length,
				routeCount: routes.length,
				operationCount: pathBuildResult.operationCount,
				skippedRouteCount: pathBuildResult.skippedRoutes.length,
				skippedRoutes: pathBuildResult.skippedRoutes,
				untemplatableRoutes: pathBuildResult.untemplatableRoutes,
				registeredSchemaCount,
				publishedSchemaCount: Object.keys(document.components.schemas).length,
				tagCount: tags.length,
			},
		};
	}
	private filterRoutesForScope(routes: Array<ExtractedRoute>): Array<ExtractedRoute> {
		switch (this.settings.routeScope) {
			case 'all':
				return routes;
			case 'admin':
				return routes.filter(isAdminRoute);
			case 'public':
				return routes.filter((route) => !isAdminRoute(route));
		}
	}
	private buildPaths(routes: Array<ExtractedRoute>, operationBuilder: OpenAPIOperationBuilder): PathBuildResult {
		const paths: Record<string, OpenAPIPathItem> = {};
		let operationCount = 0;
		const skippedRoutes: Array<SkippedRoute> = [];
		const untemplatableRoutes: Array<SkippedRoute> = [];
		for (const route of routes) {
			if (isExcludedRoutePath(route.path)) {
				continue;
			}
			if (!route.responseSchemaName && !route.hasNoContent) {
				skippedRoutes.push(describeRoute(route, 'no responseSchema'));
				continue;
			}
			if (!hasOpenAPIPathTemplate(route.path)) {
				untemplatableRoutes.push(describeRoute(route, 'the Hono path has no OpenAPI path template'));
				continue;
			}
			const openApiPath = convertPathToOpenAPI(route.path);
			paths[openApiPath] ??= {};
			if (paths[openApiPath][route.method]) {
				throw new Error(`Duplicate OpenAPI operation: ${route.method.toUpperCase()} ${openApiPath}`);
			}
			paths[openApiPath][route.method] = operationBuilder.buildOperation(route);
			operationCount++;
		}
		const sortedPaths: Record<string, OpenAPIPathItem> = {};
		for (const key of Object.keys(paths).sort()) {
			sortedPaths[key] = paths[key];
		}
		return {
			paths: sortedPaths,
			operationCount,
			skippedRoutes,
			untemplatableRoutes,
		};
	}
	private filterPublishedSchemas(
		allSchemas: Record<string, OpenAPISchema>,
		referencedSchemas: Set<string>,
	): Record<string, OpenAPISchema> {
		const publishedSchemas = new Map<string, OpenAPISchema>();
		for (const name of [...referencedSchemas, ...OpenAPIGeneratorCatalog.alwaysPublishedSchemas]) {
			assert(Object.hasOwn(allSchemas, name), `Referenced OpenAPI schema is missing: ${name}`);
			publishedSchemas.set(name, allSchemas[name]);
		}
		return Object.fromEntries(publishedSchemas);
	}
	private buildTags(routes: Array<ExtractedRoute>): Array<{
		name: string;
		description?: string;
	}> {
		const usedTags = new Set<string>();
		for (const route of routes) {
			if (isExcludedRoutePath(route.path)) {
				continue;
			}
			if (!route.explicitTags) {
				continue;
			}
			for (const tag of route.explicitTags) {
				usedTags.add(tag);
			}
		}
		const orderIndex = new Map<string, number>();
		for (const [index, tag] of OpenAPIGeneratorCatalog.tags.order.entries()) {
			orderIndex.set(tag, index);
		}
		return Array.from(usedTags)
			.sort((a, b) => (orderIndex.get(a) ?? 1000000) - (orderIndex.get(b) ?? 1000000))
			.map((name) => ({
				name,
				description: OpenAPIGeneratorCatalog.tags.descriptions[name],
			}));
	}
}