storybooker 0.19.4 → 0.22.0-canary.0

package/src/adapters/azure-data-tables.ts

@@ -0,0 +1,223 @@
+import type { TableClient, TableEntityResult, TableServiceClient } from "@azure/data-tables";
+import {
+  DatabaseAdapterErrors,
+  type DatabaseAdapter,
+  type DatabaseAdapterOptions,
+  type DatabaseDocumentListOptions,
+  type StoryBookerDatabaseDocument,
+} from "./_internal/database.ts";
+
+export type TableClientGenerator = (tableName: string) => TableClient;
+
+export class AzureDataTablesDatabaseService implements DatabaseAdapter {
+  #serviceClient: TableServiceClient;
+  #tableClientGenerator: TableClientGenerator;
+
+  constructor(serviceClient: TableServiceClient, tableClientGenerator: TableClientGenerator) {
+    this.#serviceClient = serviceClient;
+    this.#tableClientGenerator = tableClientGenerator;
+  }
+
+  metadata: DatabaseAdapter["metadata"] = { name: "Azure Tables" };
+
+  listCollections: DatabaseAdapter["listCollections"] = async (options) => {
+    const collections: string[] = [];
+    for await (const table of this.#serviceClient.listTables({
+      abortSignal: options.abortSignal,
+    })) {
+      if (table.name) {
+        collections.push(table.name);
+      }
+    }
+
+    return collections;
+  };
+
+  createCollection: DatabaseAdapter["createCollection"] = async (collectionId, options) => {
+    try {
+      const tableName = genTableNameFromCollectionId(collectionId);
+      await this.#serviceClient.createTable(tableName, {
+        abortSignal: options.abortSignal,
+      });
+    } catch (error) {
+      throw new DatabaseAdapterErrors.CollectionAlreadyExistsError(collectionId, error);
+    }
+  };
+
+  hasCollection: DatabaseAdapter["hasCollection"] = async (collectionId, options) => {
+    try {
+      const tableName = genTableNameFromCollectionId(collectionId);
+      const iterator = this.#serviceClient.listTables({
+        abortSignal: options.abortSignal,
+        queryOptions: { filter: `TableName eq '${tableName}'` },
+      });
+      for await (const table of iterator) {
+        if (table.name === collectionId) {
+          return true;
+        }
+      }
+
+      return false;
+    } catch {
+      return false;
+    }
+  };
+
+  deleteCollection: DatabaseAdapter["deleteCollection"] = async (collectionId, options) => {
+    try {
+      const tableName = genTableNameFromCollectionId(collectionId);
+      await this.#serviceClient.deleteTable(tableName, {
+        abortSignal: options.abortSignal,
+      });
+    } catch (error) {
+      throw new DatabaseAdapterErrors.CollectionDoesNotExistError(collectionId, error);
+    }
+  };
+
+  listDocuments: DatabaseAdapter["listDocuments"] = async <
+    Document extends StoryBookerDatabaseDocument,
+  >(
+    collectionId: string,
+    listOptions: DatabaseDocumentListOptions<Document>,
+    options: DatabaseAdapterOptions,
+  ): Promise<Document[]> => {
+    const { filter, limit, select, sort } = listOptions ?? {};
+
+    const tableName = genTableNameFromCollectionId(collectionId);
+    const tableClient = this.#tableClientGenerator(tableName);
+
+    const pageIterator = tableClient
+      .listEntities({
+        abortSignal: options.abortSignal,
+        queryOptions: {
+          filter: typeof filter === "string" ? filter : undefined,
+          select,
+        },
+      })
+      .byPage({ maxPageSize: limit });
+
+    const items: Document[] = [];
+    for await (const page of pageIterator) {
+      for (const entity of page) {
+        const item = entityToItem<Document>(entity);
+        if (filter && typeof filter === "function") {
+          if (filter(item)) {
+            items.push(item);
+          } else {
+            continue;
+          }
+        } else {
+          items.push(item);
+        }
+      }
+    }
+
+    if (sort && typeof sort === "function") {
+      items.sort(sort);
+    }
+
+    return items;
+  };
+
+  getDocument: DatabaseAdapter["getDocument"] = async <
+    Document extends StoryBookerDatabaseDocument,
+  >(
+    collectionId: string,
+    documentId: string,
+    options: DatabaseAdapterOptions,
+  ): Promise<Document> => {
+    try {
+      const tableName = genTableNameFromCollectionId(collectionId);
+      const tableClient = this.#tableClientGenerator(tableName);
+      const entity = await tableClient.getEntity(collectionId, documentId, {
+        abortSignal: options.abortSignal,
+      });
+
+      return entityToItem<Document>(entity);
+    } catch (error) {
+      throw new DatabaseAdapterErrors.DocumentDoesNotExistError(collectionId, documentId, error);
+    }
+  };
+
+  hasDocument: DatabaseAdapter["hasDocument"] = async (collectionId, documentId, options) => {
+    try {
+      return Boolean(await this.getDocument(collectionId, documentId, options));
+    } catch {
+      return false;
+    }
+  };
+
+  createDocument: DatabaseAdapter["createDocument"] = async (
+    collectionId,
+    documentData,
+    options,
+  ) => {
+    try {
+      const tableName = genTableNameFromCollectionId(collectionId);
+      const tableClient = this.#tableClientGenerator(tableName);
+      await tableClient.createEntity(
+        {
+          ...documentData,
+          partitionKey: collectionId,
+          rowKey: documentData.id,
+        },
+        { abortSignal: options.abortSignal },
+      );
+    } catch (error) {
+      throw new DatabaseAdapterErrors.DocumentAlreadyExistsError(
+        collectionId,
+        documentData.id,
+        error,
+      );
+    }
+  };
+
+  deleteDocument: DatabaseAdapter["deleteDocument"] = async (collectionId, documentId, options) => {
+    try {
+      const tableName = genTableNameFromCollectionId(collectionId);
+      const tableClient = this.#tableClientGenerator(tableName);
+      await tableClient.deleteEntity(collectionId, documentId, {
+        abortSignal: options.abortSignal,
+      });
+    } catch (error) {
+      throw new DatabaseAdapterErrors.DocumentDoesNotExistError(collectionId, documentId, error);
+    }
+  };
+
+  // oxlint-disable-next-line max-params
+  updateDocument: DatabaseAdapter["updateDocument"] = async (
+    collectionId,
+    documentId,
+    documentData,
+    options,
+  ) => {
+    try {
+      const tableName = genTableNameFromCollectionId(collectionId);
+      const tableClient = this.#tableClientGenerator(tableName);
+      await tableClient.updateEntity(
+        { ...documentData, partitionKey: collectionId, rowKey: documentId },
+        "Merge",
+        { abortSignal: options.abortSignal },
+      );
+    } catch (error) {
+      throw new DatabaseAdapterErrors.DocumentDoesNotExistError(collectionId, documentId, error);
+    }
+  };
+}
+
+function genTableNameFromCollectionId(collectionId: string): string {
+  if (/^[A-Za-z][A-Za-z0-9]{2,62}$/.test(collectionId)) {
+    return collectionId;
+  }
+
+  return collectionId.replaceAll(/\W/g, "").slice(0, 63).padEnd(3, "X");
+}
+
+function entityToItem<Item extends { id: string }>(
+  entity: TableEntityResult<Record<string, unknown>>,
+): Item {
+  return {
+    ...entity,
+    id: entity.rowKey ?? entity.partitionKey ?? entity.etag,
+  } as unknown as Item;
+}

package/src/adapters/azure-easy-auth.ts

@@ -0,0 +1,174 @@
+// oxlint-disable class-methods-use-this
+
+import { Buffer } from "node:buffer";
+import {
+  StoryBookerPermissionsList,
+  StoryBookerPermissionsAllEnabled,
+  type AuthAdapter,
+  type AuthAdapterOptions,
+  type StoryBookerPermissionAction,
+  type StoryBookerPermissionResource,
+  type StoryBookerPermissionWithKey,
+  type StoryBookerUser,
+} from "./_internal/auth.ts";
+
+export type {
+  StoryBookerPermission,
+  StoryBookerPermissionAction,
+  StoryBookerPermissionKey,
+  StoryBookerPermissionResource,
+  StoryBookerPermissionWithKey,
+} from "./_internal/auth.ts";
+
+export interface AzureEasyAuthClientPrincipal {
+  claims: { typ: string; val: string }[];
+  auth_typ: string;
+  name_typ: string;
+  role_typ: string;
+}
+
+export interface AzureEasyAuthUser extends StoryBookerUser {
+  roles: string[] | null;
+  type: "application" | "user";
+  clientPrincipal?: AzureEasyAuthClientPrincipal;
+}
+
+export type AuthAdapterAuthorise<AuthUser extends StoryBookerUser = StoryBookerUser> = (
+  permission: StoryBookerPermissionWithKey,
+  user: Omit<AuthUser, "permissions">,
+) => boolean;
+
+/**
+ * Modify the final user details object created from EasyAuth Client Principal.
+ */
+export type ModifyUserDetails = <User extends Omit<AzureEasyAuthUser, "permissions">>(
+  user: User,
+  options: AuthAdapterOptions,
+) => User | Promise<User>;
+
+const DEFAULT_AUTHORISE: AuthAdapterAuthorise<AzureEasyAuthUser> = (permission, user) => {
+  if (!user) {
+    return false;
+  }
+
+  if (permission.action === "read") {
+    return true;
+  }
+
+  return Boolean(user.roles && user.roles.length > 0);
+};
+
+const DEFAULT_MODIFY_USER: ModifyUserDetails = (user) => user;
+
+/**
+ * StoryBooker Auth adapter for Azure EasyAuth.
+ *
+ * @example
+ * ```ts
+ * const auth = new AzureEasyAuthService();
+ * ```
+ */
+export class AzureEasyAuthService implements AuthAdapter<AzureEasyAuthUser> {
+  #authorise: AuthAdapterAuthorise<AzureEasyAuthUser>;
+  #modifyUserDetails: ModifyUserDetails;
+
+  metadata: AuthAdapter["metadata"] = { name: "Azure Easy Auth" };
+
+  constructor(options?: {
+    /**
+     * Custom function to authorise permission for user
+     */
+    authorise?: AuthAdapterAuthorise<AzureEasyAuthUser>;
+    /**
+     * Modify the final user details object created from EasyAuth Client Principal.
+     */
+    modifyUserDetails?: ModifyUserDetails;
+  }) {
+    this.#authorise = options?.authorise ?? DEFAULT_AUTHORISE;
+    this.#modifyUserDetails = options?.modifyUserDetails ?? DEFAULT_MODIFY_USER;
+  }
+
+  getUserDetails: AuthAdapter<AzureEasyAuthUser>["getUserDetails"] = async (options) => {
+    const principalHeader = options.request.headers.get("x-ms-client-principal");
+    if (!principalHeader) {
+      throw new Response(`Unauthorized access. Please provide a valid EasyAuth principal header.`, {
+        status: 401,
+      });
+    }
+
+    // Decode and parse the claims
+    const decodedPrincipal = Buffer.from(principalHeader, "base64").toString("utf8");
+
+    const clientPrincipal: AzureEasyAuthClientPrincipal = JSON.parse(decodedPrincipal);
+    const claims = clientPrincipal?.claims ?? [];
+
+    const azpToken = claims.find((claim) => claim.typ === "azp")?.val;
+    if (azpToken) {
+      const user: AzureEasyAuthUser = {
+        clientPrincipal,
+        displayName: "App",
+        id: azpToken,
+        permissions: StoryBookerPermissionsAllEnabled,
+        roles: null,
+        type: "application",
+      };
+      return user;
+    }
+
+    const name = claims.find((claim) => claim.typ === "name")?.val;
+    const email = claims.find((claim) => claim.typ === clientPrincipal.name_typ)?.val;
+    const roles = claims
+      .filter((claim) => claim.typ === clientPrincipal.role_typ || claim.typ === "roles")
+      .map((claim) => claim.val);
+
+    const userWithoutPermissions: Omit<AzureEasyAuthUser, "permissions"> = {
+      clientPrincipal,
+      displayName: name ?? "",
+      id: email ?? "",
+      roles,
+      title: roles.join(", "),
+      type: "user",
+    };
+
+    return {
+      ...(await this.#modifyUserDetails(userWithoutPermissions, options)),
+      permissions: authoriseUserPermissions(this.#authorise, userWithoutPermissions),
+    };
+  };
+
+  login: AuthAdapter<AzureEasyAuthUser>["login"] = ({ request }) => {
+    const url = new URL("/.auth/login", request.url);
+
+    return new Response(null, {
+      headers: { Location: url.toString() },
+      status: 302,
+    });
+  };
+
+  logout: AuthAdapter<AzureEasyAuthUser>["logout"] = (_user, { request }) => {
+    const url = new URL("/.auth/logout", request.url);
+
+    return new Response(null, {
+      headers: { Location: url.toString() },
+      status: 302,
+    });
+  };
+}
+
+function authoriseUserPermissions(
+  authorise: AuthAdapterAuthorise<AzureEasyAuthUser>,
+  user: Omit<AzureEasyAuthUser, "permissions">,
+): AzureEasyAuthUser["permissions"] {
+  const permissions: AzureEasyAuthUser["permissions"] = {};
+
+  for (const key of StoryBookerPermissionsList) {
+    const [resource, action] = key.split(":") as [
+      StoryBookerPermissionResource,
+      StoryBookerPermissionAction,
+    ];
+    const permission: StoryBookerPermissionWithKey = { action, key, resource };
+    permissions[key] = authorise(permission, user);
+  }
+
+  return permissions;
+}

package/src/adapters/azure-functions.ts

@@ -0,0 +1,242 @@
+// oxlint-disable max-lines-per-function
+
+import type { RestError } from "@azure/core-rest-pipeline";
+import type {
+  Cookie,
+  HttpFunctionOptions,
+  HttpRequest,
+  HttpResponseInit,
+  HttpTriggerOptions,
+  InvocationContext,
+  SetupOptions,
+  TimerFunctionOptions,
+} from "@azure/functions";
+import { createHonoRouter, createPurgeHandler } from "../index.ts";
+import type { ErrorParser, RouterOptions, StoryBookerUser } from "../types.ts";
+import { generatePrefixFromBaseRoute, SERVICE_NAME, urlJoin } from "../utils/index.ts";
+import type { AuthAdapter } from "./_internal/auth.ts";
+import type { LoggerAdapter } from "./_internal/logger.ts";
+
+const DEFAULT_PURGE_SCHEDULE_CRON = "0 0 0 * * *";
+
+export type * from "storybooker/types";
+
+/**
+ * Minimal representation of Azure Functions App namespace
+ * to register HTTP and Timer functions.
+ */
+interface FunctionsApp {
+  http(name: string, options: HttpFunctionOptions): void;
+  setup?(options: SetupOptions): void;
+  timer?(name: string, options: TimerFunctionOptions): void;
+}
+
+/**
+ * Options to register the storybooker router
+ */
+export interface RegisterStorybookerRouterOptions<User extends StoryBookerUser> extends Omit<
+  RouterOptions<User>,
+  "auth"
+> {
+  /**
+   * For authenticating routes, either use an AuthAdapter or Functions auth-level property.
+   *
+   * - AuthAdapter allows full customization of authentication logic. This will set the function to "anonymous" auth-level.
+   * - Auth-level is a simpler way to set predefined authentication levels ("function", "admin").
+   *   This is a good option to set if the service is used in
+   *   Headless mode and requires single token authentication for all the requests.
+   *
+   * @see https://learn.microsoft.com/en-us/azure/azure-functions/functions-bindings-http-webhook-trigger?tabs=python-v2%2Cisolated-process%2Cnodejs-v4%2Cfunctionsv2&pivots=programming-language-javascript#http-auth (AuthLevels)
+   */
+  auth?: AuthAdapter<User> | Exclude<HttpTriggerOptions["authLevel"], "anonymous">;
+
+  /**
+   * Define the route on which all router is placed.
+   * Can be a sub-path of the main API route.
+   *
+   * @default ''
+   */
+  route?: string;
+
+  /**
+   * Modify the cron-schedule of timer function
+   * which purge outdated storybooks.
+   *
+   * Pass `null` to disable auto-purge functionality.
+   *
+   * @default "0 0 0 * * *" // Every midnight
+   */
+  purgeScheduleCron?: string | null;
+}
+
+/**
+ * Register the Storybooker router with the Azure Functions App.
+ *
+ * - It enabled streaming responses for HTTP functions.
+ * - It registers the HTTP function with provided route and auth-level.
+ * - It registers the Timer function for purge if `purgeScheduleCron` is not `null`.
+ *
+ * @param app Azure Functions App instance
+ * @param options Options for registering the router
+ */
+export function registerStoryBookerRouter<User extends StoryBookerUser>(
+  app: FunctionsApp,
+  options: RegisterStorybookerRouterOptions<User>,
+): void {
+  app.setup?.({ enableHttpStream: true });
+  const { auth, purgeScheduleCron, route, ...rest } = options;
+
+  const routerOptions: RouterOptions<User> = rest;
+  routerOptions.config ??= {};
+  routerOptions.config.errorParser ??= parseAzureRestError;
+
+  if (route) {
+    routerOptions.config.prefix = generatePrefixFromBaseRoute(route);
+  }
+  if (typeof auth === "object") {
+    routerOptions.auth = auth;
+  }
+
+  const router = createHonoRouter(routerOptions);
+
+  app.http(SERVICE_NAME, {
+    authLevel: typeof auth === "string" ? auth : "anonymous",
+    handler: async (httpRequest) => {
+      const request = newRequestFromAzureFunctions(httpRequest);
+      const response = await router.fetch(request);
+      return newAzureFunctionsResponse(response);
+    },
+    methods: ["GET", "POST", "DELETE", "HEAD", "PATCH", "PUT", "OPTIONS", "TRACE", "CONNECT"],
+    route: urlJoin(route ?? "", "{**path}"),
+  });
+
+  if (purgeScheduleCron !== null && app.timer) {
+    const schedule = purgeScheduleCron ?? DEFAULT_PURGE_SCHEDULE_CRON;
+    const purgeHandler = createPurgeHandler({
+      database: routerOptions.database,
+      storage: routerOptions.storage,
+    });
+
+    app.timer(`${SERVICE_NAME}-timer_purge`, {
+      // oxlint-disable-next-line require-await
+      handler: async (_timer, context) =>
+        purgeHandler({}, { logger: createAzureContextLogger(context) }),
+      runOnStartup: false,
+      schedule,
+    });
+  }
+}
+
+const parseAzureRestError: ErrorParser = (error) => {
+  if (error instanceof Error && error.name === "RestError") {
+    const restError = error as RestError;
+    const details = (restError.details ?? {}) as Record<string, string>;
+    const message: string = details["errorMessage"] ?? restError.message;
+
+    return {
+      errorMessage: `${details["errorCode"] ?? restError.name} (${
+        restError.code ?? restError.statusCode
+      }): ${message}`,
+      errorStatus: restError.statusCode,
+      errorType: "AzureRest",
+    };
+  }
+
+  // oxlint-disable-next-line no-useless-return
+  return;
+};
+
+function createAzureContextLogger(context: InvocationContext): LoggerAdapter {
+  return {
+    debug: context.debug.bind(context),
+    error: context.error.bind(context),
+    log: context.log.bind(context),
+    metadata: { name: "Azure Functions" },
+  };
+}
+
+/**
+ * Utils (@refer https://github.com/Marplex/hono-azurefunc-adapter/)
+ */
+
+/** */
+function newRequestFromAzureFunctions(request: HttpRequest): Request {
+  const hasBody = !["GET", "HEAD"].includes(request.method);
+
+  return new Request(request.url, {
+    headers: headersToObject(request.headers),
+    method: request.method,
+    ...(hasBody ? { body: request.body as ReadableStream, duplex: "half" } : {}),
+  });
+}
+
+function newAzureFunctionsResponse(response: Response): HttpResponseInit {
+  let headers = headersToObject(response.headers);
+  let cookies = cookiesFromHeaders(response.headers);
+
+  return {
+    body: streamToAsyncIterator(response.body),
+    cookies,
+    headers,
+    status: response.status,
+  };
+}
+
+function headersToObject(input: HttpRequest["headers"]): Record<string, string> {
+  const headers: Record<string, string> = {};
+  // oxlint-disable-next-line no-array-for-each
+  input.forEach((value, key) => (headers[key] = value));
+  return headers;
+}
+
+function cookiesFromHeaders(headers: Headers): Cookie[] | undefined {
+  const cookies = headers.getSetCookie();
+  if (cookies.length === 0) {
+    return undefined;
+  }
+
+  return cookies.map((cookie) => parseCookieString(cookie));
+}
+
+function parseCookieString(cookieString: string): Cookie {
+  const [first, ...attributesArray] = cookieString
+    .split(";")
+    .map((item) => item.split("="))
+    .map(([key, value]) => [key?.trim().toLowerCase(), value ?? "true"]);
+
+  const [name, encodedValue] = first ?? [];
+  const attrs: Record<string, string> = Object.fromEntries(attributesArray);
+
+  return {
+    domain: attrs["domain"],
+    expires: attrs["expires"] ? new Date(attrs["expires"]) : undefined,
+    httpOnly: attrs["httponly"] === "true",
+    maxAge: attrs["max-age"] ? Number.parseInt(attrs["max-age"], 10) : undefined,
+    name: name ?? "",
+    path: attrs["path"],
+    sameSite: attrs["samesite"] as "Strict" | "Lax" | "None" | undefined,
+    secure: attrs["secure"] === "true",
+    value: encodedValue ? decodeURIComponent(encodedValue) : "",
+  };
+}
+
+function streamToAsyncIterator(
+  readable: Response["body"],
+): AsyncIterableIterator<Uint8Array> | null {
+  if (readable === null || !readable) {
+    return null;
+  }
+
+  const reader = readable.getReader();
+  return {
+    async next() {
+      return await reader.read();
+    },
+    return() {
+      reader.releaseLock();
+    },
+    [Symbol.asyncIterator]() {
+      return this;
+    },
+  } as AsyncIterableIterator<Uint8Array>;
+}