storybooker 0.19.4 → 0.22.0-canary.0

package/src/adapters/_internal/queue.ts

@@ -0,0 +1,151 @@
+import type { StoryBookerAdapterMetadata } from "../../utils/adapter-utils.ts";
+import type { LoggerAdapter } from "./logger.ts";
+
+/**
+ * Service adapter to interact with queueing service.
+ *
+ * @description
+ * The adapter should provide callbacks to perform operations
+ * to an existing queue like send and receive messages.
+ *
+ * - `topic`: A topic/queue to hold messages.
+ * - `message`: A single message in topic which contains data and metadata.
+ *    Each message has a unique identifier.
+ */
+export interface QueueAdapter {
+  /**
+   * Metadata about the adapter.
+   */
+  metadata: StoryBookerAdapterMetadata;
+
+  /**
+   * An optional method that is called on app boot-up
+   * to run async setup functions.
+   * @param options Common options like abortSignal.
+   * @throws if an error occur during initialisation.
+   */
+  init?: (options: QueueAdapterOptions) => Promise<void>;
+
+  // Topics (message queues)
+
+  /**
+   * List all topics available in the queue service.
+   * @param options Common options like abortSignal.
+   * @returns A list of names/IDs of the topics.
+   * @throws If the queue service is not connected.
+   */
+  listTopics: (options: QueueAdapterOptions) => Promise<string[]>;
+
+  /**
+   * Create a topic used for different message types.
+   * @param topicId ID of the topic
+   * @param options Common options like abortSignal.
+   * @throws if topic with ID already exists.
+   */
+  createTopic: (topicId: string, options: QueueAdapterOptions) => Promise<void>;
+
+  /**
+   * Delete an existing topic.
+   * @param topicId ID of the topic
+   * @param options Common options like abortSignal.
+   * @throws if topic with ID does not exist.
+   */
+  deleteTopic: (topicId: string, options: QueueAdapterOptions) => Promise<void>;
+
+  /**
+   * Check if topic exists.
+   * @param topicId ID of the topic
+   * @param options Common options like abortSignal.
+   * @returns if topic is available or not
+   * @throws never.
+   */
+  hasTopic: (topicId: string, options: QueueAdapterOptions) => Promise<boolean>;
+
+  // Messages
+
+  /**
+   * Send a message to the specified topic.
+   * @param topicId ID of the topic
+   * @param message Message data to be sent
+   * @param options Common options like abortSignal.
+   * @returns Message ID if successful
+   * @throws if the topic does not exist.
+   */
+  sendMessage: <Message extends StoryBookerQueueMessage>(
+    topicId: string,
+    message: Omit<Message, "id" | "timestamp">,
+    options: QueueAdapterOptions,
+  ) => Promise<string>;
+
+  /**
+   * Receive messages from the specified topic.
+   * @param topicId ID of the topic
+   * @param receiveOptions Options to configure message receiving
+   * @param options Common options like abortSignal.
+   * @returns List of messages
+   * @throws if the topic does not exist.
+   */
+  receiveMessages: <Message extends StoryBookerQueueMessage>(
+    topicId: string,
+    receiveOptions: QueueMessageReceiveOptions,
+    options: QueueAdapterOptions,
+  ) => Promise<Message[]>;
+
+  /**
+   * Acknowledge that a message has been processed.
+   * @param topicId ID of the topic
+   * @param messageId ID of the message
+   * @param options Common options like abortSignal.
+   * @throws if the topic or message does not exist.
+   */
+  acknowledgeMessage: (
+    topicId: string,
+    messageId: string,
+    options: QueueAdapterOptions,
+  ) => Promise<void>;
+
+  /**
+   * Get message count in a topic.
+   * @param topicId ID of the topic
+   * @param options Common options like abortSignal.
+   * @returns Number of messages in the topic
+   * @throws if the topic does not exist.
+   */
+  getMessageCount: (topicId: string, options: QueueAdapterOptions) => Promise<number>;
+
+  /**
+   * Purge all messages from a topic.
+   * @param topicId ID of the topic
+   * @param options Common options like abortSignal.
+   * @throws if the topic does not exist.
+   */
+  purgeMessages: (topicId: string, options: QueueAdapterOptions) => Promise<void>;
+}
+
+/**
+ * Base Message shape used in StoryBooker Queue.
+ * Should always contain fields 'id' and 'timestamp'.
+ */
+export interface StoryBookerQueueMessage {
+  id: string;
+  timestamp: number;
+  data: Record<string, unknown>;
+  attributes?: Record<string, string>;
+}
+
+/** Common Queue adapter options. */
+export interface QueueAdapterOptions {
+  /** A signal that can be used to cancel the request handling. */
+  abortSignal?: AbortSignal;
+  /** Logger */
+  logger: LoggerAdapter;
+}
+
+export interface QueueMessageReceiveOptions {
+  /** Maximum number of messages to receive */
+  maxMessages?: number;
+  /** Visibility timeout in seconds */
+  visibilityTimeout?: number;
+  /** Wait time for long polling in seconds */
+  waitTimeSeconds?: number;
+}

package/src/adapters/_internal/storage.ts

@@ -0,0 +1,197 @@
+// oxlint-disable max-classes-per-file
+
+import { HTTPException } from "hono/http-exception";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import type { StoryBookerAdapterMetadata } from "../../utils/adapter-utils.ts";
+import type { LoggerAdapter } from "./logger.ts";
+
+/**
+ * Service adapter to interact with file-storage.
+ *
+ * @description
+ * The adapter should provide callbacks to perform operations
+ * to an existing storage like upload and download files.
+ *
+ * - `container`: A container/group/bucket to hold files. Each project has one container.
+ * - `file`: A single binary that can individually stored and retrieved.
+ *
+ * @throws {StorageNotInitializedError} if the Storage service is not connected.
+ * @throws {ContainerAlreadyExistsError} if the container already exists.
+ * @throws {ContainerDoesNotExistError} if the container does not exist.
+ * @throws {FileDoesNotExistError} if the file does not exist in the container.
+ * @throws {CustomError} if some other error occurs.
+ */
+export interface StorageAdapter {
+  /**
+   * Metadata about the adapter.
+   */
+  metadata: StoryBookerAdapterMetadata;
+
+  /**
+   * An optional method that is called on app boot-up
+   * to run async setup functions.
+   * @param options Common options like abortSignal.
+   * @throws If the Storage service fails to initialize.
+   */
+  init?: (options: StorageAdapterOptions) => Promise<void>;
+
+  // Containers
+
+  /**
+   * List all containers available in the storage.
+   * @param options Common options like abortSignal.
+   * @returns A list of names/IDs of the containers.
+   * @throws {StorageNotInitializedError} if the Storage service is not connected.
+   */
+  listContainers: (options: StorageAdapterOptions) => Promise<string[]>;
+
+  /**
+   * Create a container used for different projects.
+   * @param containerId ID of the container
+   * @param options Common options like abortSignal.
+   * @throws if container with ID already exists.
+   */
+  createContainer: (containerId: string, options: StorageAdapterOptions) => Promise<void>;
+
+  /**
+   * Delete an existing container.
+   * @param containerId ID of the container
+   * @param options Common options like abortSignal.
+   * @throws if container with ID does not exist.
+   */
+  deleteContainer: (containerId: string, options: StorageAdapterOptions) => Promise<void>;
+
+  /**
+   * Check if container exists.
+   * @param containerId ID of the container
+   * @param options Common options like abortSignal.
+   * @returns if container is available of not
+   * @throws never.
+   */
+  hasContainer: (containerId: string, options: StorageAdapterOptions) => Promise<boolean>;
+
+  // Files
+
+  /**
+   * Upload multiple files to the storage container
+   * @param containerId ID of the container
+   * @param files List of files with path, data and metadata
+   * @param options Common options like abortSignal
+   * @throws if the the container does not exists
+   */
+  uploadFiles: (
+    containerId: string,
+    files: StoryBookerFile[],
+    options: StorageAdapterOptions,
+  ) => Promise<void>;
+
+  /**
+   * Delete multiple files by their paths or a shared prefix.
+   * @param containerId ID of the container
+   * @param filePathsOrPrefix
+   * Either a list of complete filepaths or
+   * a single string representing the shared path (prefix).
+   * @param options Common options like abortSignal
+   * @throws if the the container does not exists but NOT if file(s) does not exists
+   */
+  deleteFiles: (
+    containerId: string,
+    filePathsOrPrefix: string | string[],
+    options: StorageAdapterOptions,
+  ) => Promise<void>;
+
+  /**
+   * Check if a file exists in the storage container
+   * @param containerId ID of the container
+   * @param filepath Path of the file
+   * @param options Common options like abortSignal
+   * @returns if the file exists or not
+   * @throws if the the container does not exists
+   */
+  hasFile: (
+    containerId: string,
+    filepath: string,
+    options: StorageAdapterOptions,
+  ) => Promise<boolean>;
+
+  /**
+   * Download a single file from the storage container
+   * @param containerId ID of the container
+   * @param filepath Path of the file
+   * @param options Common options like abortSignal
+   * @returns StoryBooker file data
+   * @throws if the the container or file does not exists
+   */
+  downloadFile: (
+    containerId: string,
+    filepath: string,
+    options: StorageAdapterOptions,
+  ) => Promise<Partial<StoryBookerFile>>;
+}
+
+/** Common Storage adapter options.  */
+export interface StorageAdapterOptions {
+  /** A signal that can be used to cancel the request handling. */
+  abortSignal?: AbortSignal;
+  /** Logger */
+  logger: LoggerAdapter;
+}
+
+/** Shape of file/blob */
+export interface StoryBookerFile {
+  content: Blob | ReadableStream | string;
+  mimeType: string;
+  path: string;
+}
+
+/**
+ * Pre-defined Storage adapter errors
+ * that can be used across different adapters.
+ *
+ * Throws {HTTPException} with relevant status codes.
+ */
+export const StorageAdapterErrors = {
+  StorageNotInitializedError: class extends HTTPException {
+    constructor(cause?: unknown) {
+      super(500, { cause, message: "Storage adapter is not initialized." });
+    }
+  },
+  ContainerAlreadyExistsError: class extends HTTPException {
+    constructor(containerId: string, cause?: unknown) {
+      super(409, {
+        cause,
+        message: `Storage container '${containerId}' already exists.`,
+      });
+    }
+  },
+  ContainerDoesNotExistError: class extends HTTPException {
+    constructor(containerId: string, cause?: unknown) {
+      super(404, {
+        cause,
+        message: `Storage container '${containerId}' does not exist.`,
+      });
+    }
+  },
+  FileDoesNotExistError: class extends HTTPException {
+    constructor(containerId: string, filepath: string, cause?: unknown) {
+      super(404, {
+        cause,
+        message: `Storage file '${filepath}' does not exist in container '${containerId}'.`,
+      });
+    }
+  },
+  FileMalformedError: class extends HTTPException {
+    constructor(containerId: string, filepath: string, cause?: unknown) {
+      super(415, {
+        cause,
+        message: `Storage file '${filepath}' is malformed in container '${containerId}'.`,
+      });
+    }
+  },
+  CustomError: class extends HTTPException {
+    constructor(status: number | undefined, message: string, cause?: unknown) {
+      super(status as ContentfulStatusCode, { cause, message });
+    }
+  },
+  // oxlint-disable-next-line no-explicit-any
+} satisfies Record<string, new (...args: any[]) => HTTPException>;

package/src/adapters/_internal/ui.ts

@@ -0,0 +1,103 @@
+import type {
+  BuildStoryType,
+  BuildType,
+  BuildUploadVariant,
+  ParsedError,
+  ProjectType,
+  StoryBookerUser,
+  TagType,
+} from "../../types.ts";
+import type { UrlBuilder } from "../../urls.ts";
+import type { StoryBookerAdapterMetadata } from "../../utils/adapter-utils.ts";
+import type { LoggerAdapter } from "./logger.ts";
+
+export type RenderedContent = string | Promise<string>;
+export type UIResult = Response | Promise<Response> | RenderedContent;
+
+/**
+ * Adapter for creating UI for StoryBooker service.
+ *
+ * The render methods are called asynchronously and can return promise of HTML.
+ */
+export interface UIAdapter {
+  /**
+   * Metadata about the adapter.
+   */
+  metadata: StoryBookerAdapterMetadata;
+
+  /**
+   * A special handler that is invoked when no existing StoryBooker route is matched.
+   *
+   * This can be used to serve special routes and/or static files from disk.
+   */
+  handleUnhandledRoute?(filepath: string, options: UIAdapterOptions): Response | Promise<Response>;
+
+  renderHomePage?(props: { projects: ProjectType[] }, options: UIAdapterOptions): UIResult;
+  renderErrorPage?(props: ParsedError, options: UIAdapterOptions): UIResult;
+  renderAccountsPage?(props: { children: string | undefined }, options: UIAdapterOptions): UIResult;
+
+  // Projects
+  renderProjectsListPage?(props: { projects: ProjectType[] }, options: UIAdapterOptions): UIResult;
+  renderProjectDetailsPage?(
+    props: { project: ProjectType; recentBuilds: BuildType[]; recentTags: TagType[] },
+    options: UIAdapterOptions,
+  ): UIResult;
+  renderProjectCreatePage?(props: unknown, options: UIAdapterOptions): UIResult;
+  renderProjectUpdatePage?(props: { project: ProjectType }, options: UIAdapterOptions): UIResult;
+
+  // Tags
+  renderTagsListPage?(
+    props: { tags: TagType[]; project: ProjectType; defaultType?: string | null },
+    options: UIAdapterOptions,
+  ): UIResult;
+  renderTagDetailsPage?(
+    props: { tag: TagType; project: ProjectType; builds: BuildType[] },
+    options: UIAdapterOptions,
+  ): UIResult;
+  renderTagCreatePage?(props: { project: ProjectType }, options: UIAdapterOptions): UIResult;
+  renderTagUpdatePage?(
+    props: { tag: TagType; project: ProjectType },
+    options: UIAdapterOptions,
+  ): UIResult;
+
+  // Builds
+  renderBuildsListPage?(
+    props: { builds: BuildType[]; project: ProjectType },
+    options: UIAdapterOptions,
+  ): UIResult;
+  renderBuildDetailsPage?(
+    props: { build: BuildType; project: ProjectType; stories: BuildStoryType[] | null },
+    options: UIAdapterOptions,
+  ): UIResult;
+  renderBuildCreatePage?(
+    props: { project: ProjectType; tagId?: string },
+    options: UIAdapterOptions,
+  ): UIResult;
+  renderBuildUploadPage?(
+    props: { build: BuildType; project: ProjectType; uploadVariant?: BuildUploadVariant },
+    options: UIAdapterOptions,
+  ): UIResult;
+}
+
+/** Common UI adapter options.  */
+export interface UIAdapterOptions {
+  isAuthEnabled: boolean;
+  /** Logger */
+  logger: LoggerAdapter;
+  /** Logged-in user */
+  user: StoryBookerUser | null | undefined;
+  /** Current url */
+  url: string;
+  /** Current locale */
+  locale: string;
+  /** URL builder */
+  urlBuilder: UrlBuilder;
+  /** Metadata about all adapters */
+  adaptersMetadata: {
+    auth?: StoryBookerAdapterMetadata;
+    database?: StoryBookerAdapterMetadata;
+    logger?: StoryBookerAdapterMetadata;
+    storage?: StoryBookerAdapterMetadata;
+    ui?: StoryBookerAdapterMetadata;
+  };
+}

package/src/adapters/aws-dynamodb.ts

@@ -0,0 +1,201 @@
+// oxlint-disable id-length
+
+import * as Dynamo from "@aws-sdk/client-dynamodb";
+import {
+  DatabaseAdapterErrors,
+  type DatabaseAdapter,
+  type DatabaseAdapterOptions,
+  type DatabaseDocumentListOptions,
+  type StoryBookerDatabaseDocument,
+} from "./_internal/database.ts";
+
+export class AwsDynamoDatabaseService implements DatabaseAdapter {
+  #client: Dynamo.DynamoDBClient;
+
+  constructor(client: Dynamo.DynamoDBClient) {
+    this.#client = client;
+  }
+
+  metadata: DatabaseAdapter["metadata"] = { name: "AWS DynamoDB" };
+
+  listCollections: DatabaseAdapter["listCollections"] = async (options) => {
+    const response = await this.#client.send(new Dynamo.ListTablesCommand({}), {
+      abortSignal: options.abortSignal,
+    });
+    return response.TableNames ?? [];
+  };
+
+  createCollection: DatabaseAdapter["createCollection"] = async (collectionId, options) => {
+    try {
+      await this.#client.send(
+        new Dynamo.CreateTableCommand({
+          AttributeDefinitions: [{ AttributeName: "id", AttributeType: "S" }],
+          BillingMode: "PAY_PER_REQUEST",
+          KeySchema: [{ AttributeName: "id", KeyType: "HASH" }],
+          TableName: collectionId,
+        }),
+        { abortSignal: options.abortSignal },
+      );
+    } catch (error) {
+      throw new DatabaseAdapterErrors.CollectionAlreadyExistsError(collectionId, error);
+    }
+  };
+
+  hasCollection: DatabaseAdapter["hasCollection"] = async (collectionId, options) => {
+    try {
+      const response = await this.#client.send(
+        new Dynamo.DescribeTableCommand({ TableName: collectionId }),
+        { abortSignal: options.abortSignal },
+      );
+      return Boolean(response.Table);
+    } catch {
+      return false;
+    }
+  };
+
+  deleteCollection: DatabaseAdapter["deleteCollection"] = async (collectionId, options) => {
+    try {
+      await this.#client.send(new Dynamo.DeleteTableCommand({ TableName: collectionId }), {
+        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,
+  ) => {
+    const response = await this.#client.send(new Dynamo.ScanCommand({ TableName: collectionId }), {
+      abortSignal: options.abortSignal,
+    });
+    return (response.Items ?? []).map((item) => {
+      const doc: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(item)) {
+        doc[key] = value.S ?? value.N ?? value.BOOL ?? value.NULL ?? value;
+      }
+
+      return doc as Document;
+    });
+  };
+
+  getDocument: DatabaseAdapter["getDocument"] = async <
+    Document extends StoryBookerDatabaseDocument,
+  >(
+    collectionId: string,
+    documentId: string,
+    options: DatabaseAdapterOptions,
+  ): Promise<Document> => {
+    try {
+      const response = await this.#client.send(
+        new Dynamo.GetItemCommand({
+          Key: { id: { S: documentId } },
+          TableName: collectionId,
+        }),
+        { abortSignal: options.abortSignal },
+      );
+      const document = response.Item
+        ? (Object.fromEntries(
+            Object.entries(response.Item).map(([key, value]) => [
+              key,
+              value.S ?? value.N ?? value.BOOL ?? value.NULL ?? value,
+            ]),
+          ) as Record<string, unknown>)
+        : undefined;
+
+      if (!document) {
+        throw new Error("Document not found");
+      }
+
+      document["id"] = documentId;
+      return document as Document;
+    } catch (error) {
+      throw new DatabaseAdapterErrors.DocumentDoesNotExistError(collectionId, documentId, error);
+    }
+  };
+
+  createDocument: DatabaseAdapter["createDocument"] = async (
+    collectionId,
+    documentData,
+    options,
+  ) => {
+    try {
+      await this.#client.send(
+        new Dynamo.PutItemCommand({
+          Item: Object.fromEntries(
+            Object.entries(documentData).map(([key, value]) => [key, { S: String(value) }]),
+          ),
+          TableName: collectionId,
+        }),
+        { abortSignal: options.abortSignal },
+      );
+    } catch (error) {
+      throw new DatabaseAdapterErrors.DocumentAlreadyExistsError(
+        collectionId,
+        documentData.id,
+        error,
+      );
+    }
+  };
+
+  hasDocument: DatabaseAdapter["hasDocument"] = async (collectionId, documentId, options) => {
+    const response = await this.#client.send(
+      new Dynamo.GetItemCommand({
+        Key: { id: { S: documentId } },
+        TableName: collectionId,
+      }),
+      { abortSignal: options.abortSignal },
+    );
+    return Boolean(response.Item);
+  };
+
+  deleteDocument: DatabaseAdapter["deleteDocument"] = async (collectionId, documentId, options) => {
+    try {
+      await this.#client.send(
+        new Dynamo.DeleteItemCommand({
+          Key: { id: { S: documentId } },
+          TableName: collectionId,
+        }),
+        { 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,
+  ) => {
+    const updateExpr: string[] = [];
+    const exprAttrValues: Record<string, Dynamo.AttributeValue> = {};
+    for (const [key, value] of Object.entries(documentData)) {
+      updateExpr.push(`#${key} = :${key}`);
+      exprAttrValues[`:${key}`] = { S: String(value) };
+    }
+
+    try {
+      await this.#client.send(
+        new Dynamo.UpdateItemCommand({
+          ExpressionAttributeNames: Object.fromEntries(
+            Object.keys(documentData).map((k) => [`#${k}`, k]),
+          ),
+          ExpressionAttributeValues: exprAttrValues,
+          Key: { id: { S: documentId } },
+          TableName: collectionId,
+          UpdateExpression: `SET ${updateExpr.join(", ")}`,
+        }),
+        { abortSignal: options.abortSignal },
+      );
+    } catch (error) {
+      throw new DatabaseAdapterErrors.DocumentDoesNotExistError(collectionId, documentId, error);
+    }
+  };
+}