@hypit/hypit 0.0.1 → 0.1.0

package/packages/build-result-kit/src/index.ts

@@ -0,0 +1,144 @@
+import type { BuildResultRepository } from "@hypit/build-result";
+import type { HostFacet } from "@hypit/host";
+import type { CanonicalValue } from "@hypit/protocol";
+
+export const buildResultRepositoryHostAbi = "hypit.build-result-repository-host@1";
+
+export type BuildResultRepositorySelection = {
+  readonly use: string;
+  readonly config?: CanonicalValue;
+};
+
+/** Serializable address carried by a queued Build so a detached Worker can reopen its Repository. */
+export type BuildResultRepositoryLocation = {
+  readonly root: string;
+  readonly selection: BuildResultRepositorySelection;
+};
+
+export type BuildResultRepositoryContext = {
+  /** Directory containing the configuration that selected this Repository. */
+  readonly root: string;
+  readonly config: CanonicalValue;
+};
+
+export type BuildResultRepositoryOpened = {
+  readonly repository: BuildResultRepository;
+  readonly close?: () => void | Promise<void>;
+};
+
+export type BuildResultRepositoryDiagnostic = {
+  readonly severity: "error" | "warning" | "info";
+  readonly code: string;
+  readonly message: string;
+  readonly subject?: string;
+};
+
+export type BuildResultRepositoryAdapter = {
+  validate(context: BuildResultRepositoryContext): void;
+  open(context: BuildResultRepositoryContext): BuildResultRepositoryOpened | Promise<BuildResultRepositoryOpened>;
+  /** Active, read-only reachability/permission diagnosis for the selected backing store. */
+  doctor?(context: BuildResultRepositoryContext): readonly BuildResultRepositoryDiagnostic[] | Promise<readonly BuildResultRepositoryDiagnostic[]>;
+};
+
+export type BuildResultRepositoryHostFacet = HostFacet & {
+  readonly abi: typeof buildResultRepositoryHostAbi;
+  readonly offers: readonly [string];
+  readonly implementation: BuildResultRepositoryAdapter;
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+export function createBuildResultRepositoryHostFacet(options: {
+  readonly use: string;
+  readonly validate: BuildResultRepositoryAdapter["validate"];
+  readonly open: BuildResultRepositoryAdapter["open"];
+  readonly doctor?: BuildResultRepositoryAdapter["doctor"];
+}): BuildResultRepositoryHostFacet {
+  assert(options.use.trim().length > 0, "Build Result Repository use name is empty");
+  return {
+    abi: buildResultRepositoryHostAbi,
+    offers: [options.use],
+    implementation: {
+      validate: options.validate,
+      open: options.open,
+      ...(options.doctor === undefined ? {} : { doctor: options.doctor }),
+    },
+  };
+}
+
+export function isBuildResultRepositoryHostFacet(value: HostFacet): value is BuildResultRepositoryHostFacet {
+  if (value.abi !== buildResultRepositoryHostAbi || value.offers?.length !== 1) return false;
+  const implementation = value.implementation as Partial<BuildResultRepositoryAdapter> | null;
+  return (
+    implementation !== null && typeof implementation === "object"
+      && typeof implementation.validate === "function"
+      && typeof implementation.open === "function"
+      && (implementation.doctor === undefined || typeof implementation.doctor === "function")
+  );
+}
+
+export class BuildResultRepositoryRegistry {
+  readonly #adapters = new Map<string, BuildResultRepositoryAdapter>();
+
+  registerFacet(facet: HostFacet): void {
+    assert(isBuildResultRepositoryHostFacet(facet), `Host facet ${facet.abi} is not a Build Result Repository`);
+    const use = facet.offers[0];
+    assert(!this.#adapters.has(use), `Build Result Repository ${use} is already registered`);
+    this.#adapters.set(use, facet.implementation);
+  }
+
+  has(use: string): boolean {
+    return this.#adapters.has(use);
+  }
+
+  validate(selection: BuildResultRepositorySelection, root: string): void {
+    const adapter = this.#adapters.get(selection.use);
+    assert(adapter !== undefined, `Build Result Repository ${selection.use} is not installed`);
+    adapter.validate({ root, config: selection.config ?? {} });
+  }
+
+  async open(selection: BuildResultRepositorySelection, root: string): Promise<BuildResultRepositoryOpened> {
+    const adapter = this.#adapters.get(selection.use);
+    assert(adapter !== undefined, `Build Result Repository ${selection.use} is not installed`);
+    const context = { root, config: selection.config ?? {} };
+    adapter.validate(context);
+    return await adapter.open(context);
+  }
+
+  async doctor(
+    selection: BuildResultRepositorySelection,
+    root: string,
+  ): Promise<readonly BuildResultRepositoryDiagnostic[]> {
+    const adapter = this.#adapters.get(selection.use);
+    assert(adapter !== undefined, `Build Result Repository ${selection.use} is not installed`);
+    const context = { root, config: selection.config ?? {} };
+    adapter.validate(context);
+    return await adapter.doctor?.(context) ?? [];
+  }
+}
+
+export function buildResultConfigObject(value: CanonicalValue, subject: string): Record<string, CanonicalValue> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${subject} config must be an object`);
+  }
+  return value as Record<string, CanonicalValue>;
+}
+
+export function buildResultConfigExact(value: Readonly<Record<string, CanonicalValue>>, allowed: readonly string[], subject: string): void {
+  const unknown = Object.keys(value).find((key) => !allowed.includes(key));
+  if (unknown !== undefined) throw new Error(`${subject} config does not accept ${unknown}`);
+}
+
+export function buildResultConfigString(value: CanonicalValue | undefined, subject: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${subject} must be a non-empty string`);
+  return value;
+}
+
+export function buildResultConfigBoolean(value: CanonicalValue | undefined, subject: string): boolean | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "boolean") throw new Error(`${subject} must be a boolean`);
+  return value;
+}

package/packages/build-result-s3/README.md

@@ -0,0 +1,49 @@
+# `@hypit/build-result-s3`
+
+Opt-in S3-compatible repository for complete project Build Results. It stores Build manifests,
+Composite Value Documents and public Resource files under one project prefix; an active Build's
+temporary Resources remain with the selected Runtime implementation.
+
+```json
+{
+  "format": "hypit.build-results@1",
+  "use": "@hypit/build-result-s3",
+  "config": {
+    "bucket": "my-video-results",
+    "prefix": "projects/episode-12",
+    "region": "us-east-1"
+  }
+}
+```
+
+`bucket` is required. `prefix`, `expectedBucketOwner`, `region`, `endpoint` and `forcePathStyle` are
+optional. The AWS SDK uses its normal credential chain, so credentials stay outside the Profile.
+`endpoint` and `forcePathStyle` support compatible object stores.
+
+The repository exposes the same logical shape as the filesystem adapter:
+
+```text
+<prefix>/
+  <build-id>/
+    result.json
+    files/...
+    values/...
+```
+
+Filesystem and S3 use the same Record-to-Result encoder. The adapter only writes the selected
+relative document or byte path; it does not interpret domain values. A Value Document keeps canonical
+domain data separate from the paths of nested Resources.
+
+Physical object prefixes use a reversible descending-time form derived from the ordered Build id, so
+S3 can return a newest-first delimiter page directly. This is only adapter key layout: callers still
+address `build + output`, and no index object or global Build table exists. A reused historical Output is a
+small forward reference to the finished Result that owns its value. New references are reduced to that
+terminal address as they are written, so repeated reuse still reads the original file without uploading
+another copy or maintaining a reverse dependency index. While a Build is running, a private writer
+file records only the state needed to continue publishing completed public Outputs and is removed when
+the Result receives its outcome.
+
+Object listing uses a bounded cursor page. File reads accept normalized byte ranges, allowing Studio to
+stream remote video and audio without buffering the complete object. The adapter's active doctor uses
+one bounded prefix listing to verify credentials, bucket access and endpoint reachability; it creates
+no probe object and reads no Result manifest.

package/packages/build-result-s3/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@hypit/build-result-s3",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "3.1103.0",
+    "@hypit/build-result": "workspace:*",
+    "@hypit/build-result-kit": "workspace:*",
+    "@hypit/protocol": "workspace:*"
+  }
+}

package/packages/build-result-s3/src/activation.ts

@@ -0,0 +1,71 @@
+import {
+  buildResultConfigBoolean,
+  buildResultConfigExact,
+  buildResultConfigObject,
+  buildResultConfigString,
+  createBuildResultRepositoryHostFacet,
+} from "@hypit/build-result-kit";
+
+import { S3BuildResultRepository } from "./repository.js";
+
+function repositoryFromConfig(configValue: Parameters<typeof buildResultConfigObject>[0]): S3BuildResultRepository {
+  const config = buildResultConfigObject(configValue, "S3 Build Result Repository");
+  const bucket = buildResultConfigString(config.bucket, "S3 bucket");
+  if (bucket === undefined) throw new Error("S3 bucket is required");
+  const prefix = buildResultConfigString(config.prefix, "S3 prefix");
+  const expectedBucketOwner = buildResultConfigString(config.expectedBucketOwner, "S3 expectedBucketOwner");
+  const region = buildResultConfigString(config.region, "S3 region");
+  const endpoint = buildResultConfigString(config.endpoint, "S3 endpoint");
+  const forcePathStyle = buildResultConfigBoolean(config.forcePathStyle, "S3 forcePathStyle");
+  return new S3BuildResultRepository({
+    bucket,
+    ...(prefix === undefined ? {} : { prefix }),
+    ...(expectedBucketOwner === undefined ? {} : { expectedBucketOwner }),
+    ...(region === undefined ? {} : { region }),
+    ...(endpoint === undefined ? {} : { endpoint }),
+    ...(forcePathStyle === undefined ? {} : { forcePathStyle }),
+  });
+}
+
+const s3BuildResultRepository = createBuildResultRepositoryHostFacet({
+  use: "@hypit/build-result-s3",
+  validate(context) {
+    const config = buildResultConfigObject(context.config, "S3 Build Result Repository");
+    buildResultConfigExact(config, ["bucket", "prefix", "expectedBucketOwner", "region", "endpoint", "forcePathStyle"], "S3 Build Result Repository");
+    if (buildResultConfigString(config.bucket, "S3 bucket") === undefined) throw new Error("S3 bucket is required");
+    buildResultConfigString(config.prefix, "S3 prefix");
+    buildResultConfigString(config.expectedBucketOwner, "S3 expectedBucketOwner");
+    buildResultConfigString(config.region, "S3 region");
+    buildResultConfigString(config.endpoint, "S3 endpoint");
+    buildResultConfigBoolean(config.forcePathStyle, "S3 forcePathStyle");
+  },
+  open(context) {
+    const repository = repositoryFromConfig(context.config);
+    return { repository, close: async () => await repository.close() };
+  },
+  async doctor(context) {
+    const repository = repositoryFromConfig(context.config);
+    try {
+      await repository.diagnose();
+      return [];
+    } catch (error) {
+      const config = buildResultConfigObject(context.config, "S3 Build Result Repository");
+      const bucket = buildResultConfigString(config.bucket, "S3 bucket") ?? "unknown";
+      return [{
+        severity: "error" as const,
+        code: "RESULT_REPOSITORY_UNAVAILABLE",
+        message: error instanceof Error ? error.message : String(error),
+        subject: `s3://${bucket}`,
+      }];
+    } finally {
+      await repository.close();
+    }
+  },
+});
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [s3BuildResultRepository],
+};
+
+export default hypitPackage;

package/packages/build-result-s3/src/client.ts

@@ -0,0 +1,254 @@
+import {
+  AbortMultipartUploadCommand,
+  CompleteMultipartUploadCommand,
+  CreateMultipartUploadCommand,
+  DeleteObjectCommand,
+  GetObjectCommand,
+  ListObjectsV2Command,
+  PutObjectCommand,
+  S3Client,
+  UploadPartCommand,
+} from "@aws-sdk/client-s3";
+import type { S3ClientConfig } from "@aws-sdk/client-s3";
+import type { BuildResultFileRange } from "@hypit/build-result";
+
+export type BuildResultS3Client = {
+  put(key: string, bytes: Uint8Array, mediaType: string): Promise<void>;
+  putStream(key: string, chunks: AsyncIterable<Uint8Array>, mediaType: string): Promise<void>;
+  get(key: string): Promise<Uint8Array | undefined>;
+  open(key: string, range?: BuildResultFileRange): Promise<AsyncIterable<Uint8Array> | undefined>;
+  list(prefix: string, options?: {
+    readonly limit?: number;
+    readonly after?: string;
+    readonly delimiter?: string;
+  }): Promise<readonly string[]>;
+  delete(key: string): Promise<void>;
+  close?(): void | Promise<void>;
+};
+
+function statusCode(error: unknown): number | undefined {
+  if (typeof error !== "object" || error === null || !("$metadata" in error)) return undefined;
+  const metadata = error.$metadata;
+  if (typeof metadata !== "object" || metadata === null || !("httpStatusCode" in metadata)) return undefined;
+  return typeof metadata.httpStatusCode === "number" ? metadata.httpStatusCode : undefined;
+}
+
+function absent(error: unknown): boolean {
+  return statusCode(error) === 404 || (error instanceof Error && (error.name === "NoSuchKey" || error.name === "NotFound"));
+}
+
+export type AwsBuildResultS3ClientOptions = {
+  readonly bucket: string;
+  readonly expectedBucketOwner?: string;
+  readonly partSizeBytes?: number;
+  readonly region?: string;
+  readonly endpoint?: string;
+  readonly forcePathStyle?: boolean;
+};
+
+export class AwsBuildResultS3Client implements BuildResultS3Client {
+  readonly #client: S3Client;
+  readonly #bucket: string;
+  readonly #expectedBucketOwner: string | undefined;
+  readonly #partSizeBytes: number;
+
+  constructor(options: AwsBuildResultS3ClientOptions) {
+    this.#bucket = options.bucket;
+    this.#expectedBucketOwner = options.expectedBucketOwner;
+    this.#partSizeBytes = options.partSizeBytes ?? 16 * 1024 * 1024;
+    this.#client = new S3Client({
+      ...(options.region === undefined ? {} : { region: options.region }),
+      ...(options.endpoint === undefined ? {} : { endpoint: options.endpoint }),
+      ...(options.forcePathStyle === undefined ? {} : { forcePathStyle: options.forcePathStyle }),
+    } satisfies S3ClientConfig);
+  }
+
+  #owner(): { readonly ExpectedBucketOwner?: string } {
+    return this.#expectedBucketOwner === undefined ? {} : { ExpectedBucketOwner: this.#expectedBucketOwner };
+  }
+
+  async put(key: string, bytes: Uint8Array, mediaType: string): Promise<void> {
+    await this.#client.send(
+      new PutObjectCommand({
+        Bucket: this.#bucket,
+        Key: key,
+        Body: bytes,
+        ContentLength: bytes.byteLength,
+        ContentType: mediaType,
+        ...this.#owner(),
+      }),
+    );
+  }
+
+  async putStream(key: string, chunks: AsyncIterable<Uint8Array>, mediaType: string): Promise<void> {
+    const created = await this.#client.send(
+      new CreateMultipartUploadCommand({
+        Bucket: this.#bucket,
+        Key: key,
+        ContentType: mediaType,
+        ...this.#owner(),
+      }),
+    );
+    if (created.UploadId === undefined) throw new Error(`S3 did not start upload for ${key}`);
+    const uploadId = created.UploadId;
+    const parts: { PartNumber: number; ETag: string }[] = [];
+    let pending: Uint8Array[] = [];
+    let pendingBytes = 0;
+    const flush = async (): Promise<void> => {
+      if (pendingBytes === 0) return;
+      const body = new Uint8Array(pendingBytes);
+      let offset = 0;
+      for (const piece of pending) {
+        body.set(piece, offset);
+        offset += piece.byteLength;
+      }
+      pending = [];
+      pendingBytes = 0;
+      const partNumber = parts.length + 1;
+      const uploaded = await this.#client.send(
+        new UploadPartCommand({
+          Bucket: this.#bucket,
+          Key: key,
+          UploadId: uploadId,
+          PartNumber: partNumber,
+          Body: body,
+          ContentLength: body.byteLength,
+          ...this.#owner(),
+        }),
+      );
+      if (uploaded.ETag === undefined) throw new Error(`S3 did not return part ${partNumber} for ${key}`);
+      parts.push({ PartNumber: partNumber, ETag: uploaded.ETag });
+    };
+    try {
+      for await (const value of chunks) {
+        const chunk = Uint8Array.from(value);
+        let offset = 0;
+        while (offset < chunk.byteLength) {
+          const take = Math.min(this.#partSizeBytes - pendingBytes, chunk.byteLength - offset);
+          pending.push(chunk.slice(offset, offset + take));
+          pendingBytes += take;
+          offset += take;
+          if (pendingBytes === this.#partSizeBytes) await flush();
+        }
+      }
+      await flush();
+      if (parts.length === 0) {
+        await this.#client.send(
+          new AbortMultipartUploadCommand({
+            Bucket: this.#bucket,
+            Key: key,
+            UploadId: uploadId,
+            ...this.#owner(),
+          }),
+        );
+        await this.put(key, new Uint8Array(), mediaType);
+        return;
+      }
+      await this.#client.send(
+        new CompleteMultipartUploadCommand({
+          Bucket: this.#bucket,
+          Key: key,
+          UploadId: uploadId,
+          MultipartUpload: { Parts: parts },
+          ...this.#owner(),
+        }),
+      );
+    } catch (error) {
+      await this.#client
+        .send(
+          new AbortMultipartUploadCommand({
+            Bucket: this.#bucket,
+            Key: key,
+            UploadId: uploadId,
+            ...this.#owner(),
+          }),
+        )
+        .catch(() => undefined);
+      throw error;
+    }
+  }
+
+  async get(key: string): Promise<Uint8Array | undefined> {
+    try {
+      const response = await this.#client.send(
+        new GetObjectCommand({
+          Bucket: this.#bucket,
+          Key: key,
+          ...this.#owner(),
+        }),
+      );
+      if (response.Body === undefined) throw new Error(`S3 object ${key} has no body`);
+      return Uint8Array.from(await response.Body.transformToByteArray());
+    } catch (error) {
+      if (absent(error)) return undefined;
+      throw error;
+    }
+  }
+
+  async open(key: string, range?: BuildResultFileRange): Promise<AsyncIterable<Uint8Array> | undefined> {
+    try {
+      const response = await this.#client.send(
+        new GetObjectCommand({
+          Bucket: this.#bucket,
+          Key: key,
+          ...(range === undefined ? {} : { Range: `bytes=${range.start}-${range.endExclusive - 1}` }),
+          ...this.#owner(),
+        }),
+      );
+      if (response.Body === undefined) throw new Error(`S3 object ${key} has no body`);
+      const body = response.Body as unknown as AsyncIterable<Uint8Array>;
+      return (async function* () {
+        for await (const chunk of body) yield Uint8Array.from(chunk);
+      })();
+    } catch (error) {
+      if (absent(error)) return undefined;
+      throw error;
+    }
+  }
+
+  async list(prefix: string, options: {
+    readonly limit?: number;
+    readonly after?: string;
+    readonly delimiter?: string;
+  } = {}): Promise<readonly string[]> {
+    if (options.limit !== undefined && (!Number.isSafeInteger(options.limit) || options.limit < 1)) {
+      throw new Error("S3 list limit must be a positive safe integer");
+    }
+    const keys: string[] = [];
+    let continuationToken: string | undefined;
+    do {
+      const response = await this.#client.send(
+        new ListObjectsV2Command({
+          Bucket: this.#bucket,
+          Prefix: prefix,
+          ...(options.after === undefined ? {} : { StartAfter: options.after }),
+          ...(options.delimiter === undefined ? {} : { Delimiter: options.delimiter }),
+          ...(options.limit === undefined ? {} : { MaxKeys: Math.min(1_000, options.limit - keys.length) }),
+          ...(continuationToken === undefined ? {} : { ContinuationToken: continuationToken }),
+          ...this.#owner(),
+        }),
+      );
+      keys.push(
+        ...(response.CommonPrefixes ?? []).flatMap((item) => item.Prefix === undefined ? [] : [item.Prefix]),
+        ...(response.Contents ?? []).flatMap((item) => item.Key === undefined ? [] : [item.Key]),
+      );
+      if (options.limit !== undefined && keys.length >= options.limit) return keys.slice(0, options.limit);
+      continuationToken = response.IsTruncated === true ? response.NextContinuationToken : undefined;
+    } while (continuationToken !== undefined);
+    return keys;
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.#client.send(
+      new DeleteObjectCommand({
+        Bucket: this.#bucket,
+        Key: key,
+        ...this.#owner(),
+      }),
+    );
+  }
+
+  close(): void {
+    this.#client.destroy();
+  }
+}

package/packages/build-result-s3/src/index.ts

@@ -0,0 +1,4 @@
+export { AwsBuildResultS3Client } from "./client.js";
+export type { AwsBuildResultS3ClientOptions, BuildResultS3Client } from "./client.js";
+export { S3BuildResultRepository } from "./repository.js";
+export type { S3BuildResultRepositoryOptions } from "./repository.js";