@tymber/common 0.0.1-alpha.0 → 0.1.0

package/src/App.ts

@@ -0,0 +1,319 @@
+import { type HttpMethod, Router } from "./Router.js";
+import {
+  type Module,
+  type ModuleDefinition,
+  ModuleDefinitions,
+} from "./Module.js";
+import { Middleware } from "./Middleware.js";
+import { parseCookieHeader } from "./contrib/cookie.js";
+import { type HttpContext, HttpRedirectCode } from "./HttpContext.js";
+import { computeBaseUrl } from "./utils/computeBaseUrl.js";
+import { ViewRenderer } from "./ViewRenderer.js";
+import { computeContentType } from "./utils/computeContentType.js";
+import { loadModules } from "./utils/loadModules.js";
+import { BaseI18nService } from "./I18nService.js";
+import { BaseTemplateService } from "./TemplateService.js";
+import { runMigrations } from "./utils/runMigrations.js";
+import { createDebug } from "./utils/createDebug.js";
+import { DB } from "./DB.js";
+import { isProduction } from "./utils/isProduction.js";
+import { Component, ComponentFactory } from "./Component.js";
+import { PubSubService } from "./PubSubService.js";
+import { FS } from "./utils/fs.js";
+import { EnvironmentBasedConfigService } from "./ConfigService.js";
+import { snakeToCamelCase } from "./utils/snakeToCamelCase.js";
+
+const debug = createDebug("App");
+
+function createRouter(modules: ModuleDefinition[]) {
+  const router = new Router();
+
+  for (const module of modules) {
+    for (const { method, path, handler } of module.endpoints) {
+      router.registerRoute(method, path, handler);
+    }
+
+    for (const { method, path, handler } of module.views) {
+      router.registerRoute(method, path, handler);
+    }
+
+    for (const { method, path, handler } of module.adminEndpoints) {
+      router.registerRoute(method, path, handler);
+    }
+
+    for (const { method, path, handler } of module.adminViews) {
+      router.registerRoute(method, path, handler);
+    }
+  }
+
+  return router;
+}
+
+function parseQueryParams(url: URL) {
+  const query = Object.create(null);
+
+  url.searchParams.forEach((value, key) => {
+    query[snakeToCamelCase(key)] = value;
+  });
+
+  return query;
+}
+
+export class App {
+  private readonly router: Router;
+  private readonly middlewares: Middleware[] = [];
+
+  private constructor(
+    modules: ModuleDefinition[],
+    private readonly assets: Map<string, string>,
+    private readonly viewRenderer: ViewRenderer,
+  ) {
+    this.router = createRouter(modules);
+    for (const module of modules) {
+      this.middlewares.push(...module.middlewares);
+    }
+    this.fetch = this.fetch.bind(this);
+  }
+
+  static async create({
+    components,
+    modules,
+  }: {
+    components: Component[];
+    modules: Module[];
+  }) {
+    const db = components.find((c) => {
+      return c instanceof DB;
+    });
+
+    if (!db) {
+      throw new Error("no DB component found");
+    }
+
+    debug(
+      "starting app in %s mode",
+      isProduction ? "production" : "development",
+    );
+
+    const componentFactory = new ComponentFactory();
+
+    let viewRenderer: ViewRenderer;
+
+    componentFactory.register(PubSubService);
+    componentFactory.register(EnvironmentBasedConfigService);
+    componentFactory.register(BaseI18nService);
+    componentFactory.register(BaseTemplateService);
+    componentFactory.register(ViewRenderer, (instance) => {
+      viewRenderer = instance;
+    });
+
+    debug("loading modules");
+    const moduleDefinitions = await loadModules(componentFactory, modules);
+    const allComponents = componentFactory.build(
+      new ModuleDefinitions(moduleDefinitions),
+      ...components,
+    );
+
+    debug("running migrations");
+    await runMigrations(db, moduleDefinitions);
+
+    debug("initializing all components");
+    await Promise.all(allComponents.map((component) => component.init()));
+
+    const assets = new Map<string, string>();
+
+    for (const module of modules) {
+      if (!module.assetsDir) {
+        continue;
+      }
+
+      try {
+        for (const filename of await FS.readDirRecursively(
+          FS.join(module.assetsDir, "static"),
+        )) {
+          assets.set(
+            "/static/" + filename,
+            FS.join(module.assetsDir, "static", filename),
+          );
+        }
+      } catch (e) {}
+    }
+
+    const app = new App(moduleDefinitions, assets, viewRenderer!);
+
+    app.close = () => {
+      debug("closing all components");
+      return Promise.all(
+        components.map((component) => component.close()),
+      ).then();
+    };
+
+    return app;
+  }
+
+  public async fetch(req: Request): Promise<Response> {
+    const url = new URL(req.url, "http://localhost");
+
+    const locale = this.viewRenderer.computeLocale(req);
+
+    const ctx = {
+      startedAt: new Date(),
+      method: req.method as HttpMethod,
+      path: url.pathname,
+      query: parseQueryParams(url),
+      headers: req.headers,
+      cookies: parseCookieHeader(req.headers.get("cookie") || ""),
+      abortSignal: req.signal,
+      locale,
+      responseHeaders: new Headers(),
+
+      render: async (view, data = {}) => {
+        try {
+          return this.viewRenderer.render(ctx, view, data);
+        } catch (e) {
+          return this.renderHttp500Error(ctx, e as Error);
+        }
+      },
+
+      redirect(
+        path: string,
+        code: HttpRedirectCode = HttpRedirectCode.HTTP_302_FOUND,
+      ) {
+        const baseUrl = computeBaseUrl(ctx.headers);
+        // note: `Response.redirect()` does not allow to specify additional headers
+        return new Response(null, {
+          status: code,
+          headers: {
+            Location: `${baseUrl}${path}`,
+          },
+        });
+      },
+    } as HttpContext;
+
+    if (ctx.path.startsWith("/static")) {
+      if (!this.assets.has(ctx.path)) {
+        return this.renderHttp404Error(ctx);
+      }
+      const contentType = computeContentType(ctx.path);
+      const absolutePath = this.assets.get(ctx.path)!;
+
+      debug("serving %s with content type %s", ctx.path, contentType);
+      return new Response(FS.createReadStream(absolutePath), {
+        headers: {
+          "content-type": contentType,
+          "cache-control": isProduction
+            ? "public, max-age=31536000, immutable"
+            : "no-cache",
+        },
+      });
+    }
+
+    // make a copy in case a middleware is removed
+    const middlewares = this.middlewares.slice();
+
+    for (const middleware of middlewares) {
+      try {
+        const httpRes = await middleware.handle(ctx);
+
+        if (httpRes) {
+          ctx.responseHeaders.forEach((value, key) => {
+            httpRes.headers.set(key, value);
+          });
+
+          return httpRes;
+        }
+      } catch (e) {
+        return this.renderHttp500Error(ctx, e as Error);
+      }
+    }
+
+    const route = this.router.findRoute(req.method as HttpMethod, url.pathname);
+
+    if (!route) {
+      return this.renderHttp404Error(ctx);
+    }
+
+    ctx.pathParams = route.pathParams;
+
+    const contentType = req.headers.get("content-type");
+
+    if (contentType) {
+      if (contentType !== "application/json") {
+        // TODO support other content types
+        return Response.json(
+          {
+            message: "unsupported media type",
+          },
+          {
+            status: 415,
+          },
+        );
+      }
+
+      try {
+        ctx.payload = await req.json();
+      } catch {
+        return Response.json(
+          {
+            message: "invalid request body",
+          },
+          {
+            status: 400,
+          },
+        );
+      }
+    }
+
+    try {
+      const httpRes = await route.handler.doHandle(ctx);
+
+      ctx.responseHeaders.forEach((value, key) => {
+        httpRes.headers.set(key, value);
+      });
+
+      return httpRes;
+    } catch (e) {
+      return this.renderHttp500Error(ctx, e as Error);
+    }
+  }
+
+  private renderHttp404Error(ctx: HttpContext) {
+    const acceptHeader = ctx.headers.get("accept");
+
+    if (acceptHeader?.includes("text/html")) {
+      return this.viewRenderer.render(ctx, "404");
+    } else {
+      return Response.json(
+        {
+          message: "resource not found",
+        },
+        {
+          status: 404,
+        },
+      );
+    }
+  }
+
+  private renderHttp500Error(ctx: HttpContext, error: Error) {
+    const acceptHeader = ctx.headers.get("accept");
+
+    if (acceptHeader?.includes("text/html")) {
+      return this.viewRenderer.render(ctx, "500", {
+        error,
+      });
+    } else {
+      return Response.json(
+        {
+          message: "an unexpected error occurred",
+        },
+        {
+          status: 500,
+        },
+      );
+    }
+  }
+
+  public close() {
+    return Promise.resolve();
+  }
+}

package/src/Component.ts

@@ -0,0 +1,166 @@
+import { type Context, type Span } from "./Context.js";
+
+export const INJECT = Symbol("dependencies");
+
+export type Ctor<T> = new (...args: any[]) => T;
+type AbstractCtor<T> = abstract new (...args: any[]) => T;
+
+type Dependency = Ctor<Component> | AbstractCtor<Component>;
+
+export abstract class Component {
+  private __isComponent!: void; // nominal typing
+
+  static [INJECT]: Dependency[] = [];
+
+  init(): void | Promise<void> {}
+  close(): void | Promise<void> {}
+}
+
+interface Node {
+  ctor: Ctor<Component>;
+  dependencies: Ctor<Component>[];
+  level: number;
+}
+
+function isSubclass(subclass: any, superclass: any): boolean {
+  return superclass.prototype.isPrototypeOf(subclass.prototype);
+}
+
+function customConstructor<T extends { new (...args: any[]): any }>(
+  ctor: T,
+  onCreation: (instance: any) => void,
+): T {
+  return class extends ctor {
+    constructor(...args: any[]) {
+      super(...args);
+      onCreation(this);
+    }
+  };
+}
+
+export class ComponentFactory {
+  private readonly componentTree: Node[] = [];
+
+  public register<T extends Component>(
+    ctor: Ctor<T>,
+    onCreation?: (instance: T) => void,
+  ) {
+    if (onCreation) {
+      ctor = customConstructor(ctor, onCreation);
+    }
+
+    let level = 0;
+
+    // find place in the tree
+    for (const node of this.componentTree) {
+      for (const dependency of node.dependencies) {
+        if (ctor === dependency || isSubclass(ctor, dependency)) {
+          level = Math.max(level, node.level + 1);
+        }
+      }
+    }
+
+    // move dependencies at the bottom
+    // @ts-expect-error
+    const dependencies = (ctor[INJECT] || []) as Ctor<Component>[];
+    for (const node of this.componentTree) {
+      for (const dependency of dependencies) {
+        if (node.ctor === dependency || isSubclass(node.ctor, dependency)) {
+          node.level = Math.max(node.level, level + 1);
+        }
+      }
+    }
+
+    this.componentTree.push({
+      ctor,
+      dependencies,
+      level,
+    });
+  }
+
+  public build(...baseComponents: Component[]) {
+    const components: Component[] = [...baseComponents];
+
+    const proxyHandler: ProxyHandler<any> = {
+      get(target, prop) {
+        const method = target[prop];
+
+        if (typeof method !== "function") {
+          return method;
+        }
+
+        return function (...args: any[]) {
+          const isTracingEnabled = args.length > 0 && args[0].tracing?.enabled;
+          if (!isTracingEnabled) {
+            return method.apply(target, args);
+          }
+
+          const ctx = args[0] as Context;
+
+          const span: Span = {
+            component: target.constructor.name,
+            method: prop as string,
+            startedAt: Date.now(),
+            duration: -1,
+            isSuccess: false,
+          };
+
+          ctx.tracing?.spans.push(span);
+
+          function completeSpan() {
+            span.duration = Date.now() - span.startedAt;
+          }
+
+          try {
+            const result = method.apply(target, args);
+
+            if (isPromise(result)) {
+              return result
+                .then((output: any) => {
+                  span.isSuccess = true;
+                  return output;
+                })
+                .finally(() => completeSpan());
+            }
+
+            span.isSuccess = true;
+            return result;
+          } finally {
+            completeSpan();
+          }
+        };
+      },
+    };
+
+    this.componentTree.sort((a, b) => b.level - a.level);
+
+    // TODO do not instantiate components that are not used in the tree
+    for (const node of this.componentTree) {
+      const deps = node.dependencies.map((ctor) => {
+        const availableDeps = components.filter(
+          (component) => component instanceof ctor,
+        );
+
+        if (availableDeps.length === 0) {
+          throw `unresolved dependency ${ctor.name} for ${node.ctor.name}`;
+        }
+
+        return availableDeps[availableDeps.length - 1];
+      });
+
+      const component = new node.ctor(...deps);
+      components.push(new Proxy(component, proxyHandler));
+    }
+
+    return components;
+  }
+}
+
+function isPromise(obj: any) {
+  return (
+    !!obj &&
+    typeof obj === "object" &&
+    typeof obj.then === "function" &&
+    typeof obj.catch === "function"
+  );
+}

package/src/ConfigService.ts

@@ -0,0 +1,121 @@
+import { hash } from "node:crypto";
+import { Component } from "./Component.js";
+import { type Context, emptyContext } from "./Context.js";
+
+type ConfigType = "string" | "string[]" | "number" | "boolean";
+
+interface ConfigDefinition {
+  key: string;
+  type: ConfigType;
+  defaultValue?: any;
+  shouldObfuscate?: boolean;
+}
+
+interface ConfigDefinitionWithValue extends ConfigDefinition {
+  value: any;
+}
+
+type ConfigValues = Record<string, any>;
+
+interface ConfigHandler {
+  configDefinitions: ConfigDefinition[];
+  handler: (config: ConfigValues) => void | Promise<void>;
+  previousConfigHash: string;
+}
+
+export abstract class ConfigService extends Component {
+  protected handlers: ConfigHandler[] = [];
+
+  public subscribe(
+    configDefinitions: ConfigDefinition[],
+    handler: (config: ConfigValues) => void | Promise<void>,
+  ) {
+    this.handlers.push({
+      configDefinitions,
+      handler,
+      previousConfigHash: "",
+    });
+  }
+
+  override init() {
+    return this.notifyConsumers(emptyContext());
+  }
+
+  protected async notifyConsumers(ctx: Context) {
+    const values = await this.getCurrentValues(ctx);
+    for (const elem of this.handlers) {
+      const config: ConfigValues = {};
+
+      for (const { key, defaultValue } of elem.configDefinitions) {
+        config[key] = values[key] || defaultValue;
+      }
+
+      const configHash = hash("sha256", JSON.stringify(config));
+
+      if (configHash !== elem.previousConfigHash) {
+        elem.previousConfigHash = configHash;
+        await elem.handler(config);
+      }
+    }
+  }
+
+  public getDefinitions() {
+    return this.handlers.flatMap((elem) => elem.configDefinitions);
+  }
+
+  public async getCurrentConfig(ctx: Context) {
+    const values = await this.getCurrentValues(ctx);
+    const config: ConfigDefinitionWithValue[] = [];
+
+    for (const handler of this.handlers) {
+      for (const {
+        key,
+        type,
+        defaultValue,
+        shouldObfuscate,
+      } of handler.configDefinitions) {
+        config.push({
+          key,
+          type,
+          defaultValue,
+          value: values[key] ?? defaultValue,
+          shouldObfuscate,
+        });
+      }
+    }
+
+    return config;
+  }
+
+  protected abstract getCurrentValues(ctx: Context): Promise<ConfigValues>;
+}
+
+function formatValue(type: ConfigType, value: string) {
+  switch (type) {
+    case "string":
+      return value;
+    case "string[]":
+      return value.split(",");
+    case "number":
+      return parseInt(value, 10);
+    case "boolean":
+      return value === "1";
+  }
+}
+
+export class EnvironmentBasedConfigService extends ConfigService {
+  override getCurrentValues() {
+    const availableKeys = Object.keys(process.env);
+    const values: Record<string, any> = {};
+
+    for (const handler of this.handlers) {
+      for (const { key, type } of handler.configDefinitions) {
+        if (availableKeys.includes(key)) {
+          values[key] = formatValue(type, process.env[key] ?? "");
+        }
+      }
+    }
+
+    return Promise.resolve(values);
+  }
+}

package/src/Context.ts

@@ -0,0 +1,60 @@
+import { type Brand } from "./utils/types.js";
+
+export type InternalUserId = Brand<bigint, "InternalUserId">;
+export type UserId = Brand<string, "UserId">;
+export type InternalGroupId = Brand<bigint, "InternalGroupId">;
+export type GroupId = Brand<string, "GroupId">;
+export type Role = Brand<number, "Role">;
+export type AdminUserId = Brand<number, "AdminUserId">;
+
+export interface ConnectedUser {
+  internalId: InternalUserId;
+  id: UserId;
+
+  firstName: string;
+  lastName: string;
+  email: string;
+
+  groups: Array<{
+    internalId: InternalGroupId;
+    id: GroupId;
+    label: string;
+    role: Role;
+  }>;
+}
+
+export interface Admin {
+  id: AdminUserId;
+}
+
+export interface Span {
+  component: string;
+  method: string;
+  startedAt: number;
+  duration: number;
+  isSuccess: boolean;
+}
+
+export interface Context {
+  startedAt: Date;
+
+  tx?: any;
+
+  user?: ConnectedUser;
+  admin?: Admin;
+
+  tracing: {
+    enabled: boolean;
+    spans: Array<Span>;
+  };
+}
+
+export function emptyContext(): Context {
+  return {
+    startedAt: new Date(),
+    tracing: {
+      enabled: false,
+      spans: [],
+    },
+  };
+}

package/src/DB.ts

@@ -0,0 +1,28 @@
+import { Component } from "./Component.js";
+import { type Context } from "./Context.js";
+import { Statement } from "./utils/sql.js";
+
+export abstract class DB extends Component {
+  public abstract readonly name: string;
+
+  abstract query<T extends Record<string, any>>(
+    ctx: Context,
+    query: Statement,
+  ): Promise<T[]>;
+
+  abstract run(
+    ctx: Context,
+    query: Statement,
+  ): Promise<{ affectedRows: number }>;
+
+  abstract exec(ctx: Context, query: Statement): Promise<void>;
+
+  abstract startTransaction(
+    ctx: Context,
+    fn: () => Promise<void>,
+  ): void | Promise<void>;
+
+  abstract createMigrationsTable(ctx: Context): Promise<void>;
+}
+
+export class DuplicateKeyError extends Error {}