@bcts/uniform-resources 1.0.0-alpha.10

package/src/multipart-decoder.ts

@@ -0,0 +1,204 @@
+import { decodeCbor } from "@bcts/dcbor";
+import { InvalidSchemeError, InvalidTypeError, UnexpectedTypeError, URError } from "./error.js";
+import { UR } from "./ur.js";
+import { URType } from "./ur-type.js";
+import { FountainDecoder, type FountainPart } from "./fountain.js";
+import { decodeBytewords, BytewordsStyle } from "./utils.js";
+
+/**
+ * Decodes multiple UR parts back into a single UR.
+ *
+ * This reassembles multipart URs that were encoded using fountain codes.
+ * The decoder can handle out-of-order reception and packet loss.
+ *
+ * @example
+ * ```typescript
+ * const decoder = new MultipartDecoder();
+ *
+ * for (const urPart of urParts) {
+ *   decoder.receive(urPart);
+ *   if (decoder.isComplete()) {
+ *     const ur = decoder.message();
+ *     break;
+ *   }
+ * }
+ * ```
+ */
+export class MultipartDecoder {
+  private _urType: URType | null = null;
+  private _fountainDecoder: FountainDecoder | null = null;
+  private _decodedMessage: UR | null = null;
+
+  /**
+   * Receives a UR part string.
+   *
+   * @param part - A UR part string (e.g., "ur:bytes/1-10/..." or "ur:bytes/...")
+   * @throws {InvalidSchemeError} If the part doesn't start with "ur:"
+   * @throws {UnexpectedTypeError} If the type doesn't match previous parts
+   */
+  receive(part: string): void {
+    const { urType, partInfo } = this._parsePart(part);
+
+    // Validate type consistency
+    if (this._urType === null) {
+      this._urType = urType;
+    } else if (!this._urType.equals(urType)) {
+      throw new UnexpectedTypeError(this._urType.string(), urType.string());
+    }
+
+    // Handle the part
+    if (partInfo.isSinglePart) {
+      // Single-part UR - decode immediately
+      this._decodedMessage = UR.fromURString(part);
+    } else {
+      // Multipart UR - use fountain decoder
+      this._fountainDecoder ??= new FountainDecoder();
+
+      const fountainPart = this._decodeFountainPart(partInfo);
+      this._fountainDecoder.receive(fountainPart);
+
+      // Try to get the complete message
+      if (this._fountainDecoder.isComplete()) {
+        const message = this._fountainDecoder.message();
+        if (message !== null) {
+          const cbor = decodeCbor(message);
+          this._decodedMessage = UR.new(this._urType, cbor);
+        }
+      }
+    }
+  }
+
+  /**
+   * Parses a UR part string to extract type and part info.
+   */
+  private _parsePart(part: string): { urType: URType; partInfo: PartInfo } {
+    const lowercased = part.toLowerCase();
+
+    if (!lowercased.startsWith("ur:")) {
+      throw new InvalidSchemeError();
+    }
+
+    const afterScheme = lowercased.substring(3);
+    const components = afterScheme.split("/");
+
+    if (components.length === 0 || components[0] === "") {
+      throw new InvalidTypeError();
+    }
+
+    const urType = new URType(components[0]);
+
+    // Check if this is a multipart UR (format: type/seqNum-seqLen/data)
+    if (components.length >= 3) {
+      const seqPart = components[1];
+      const seqMatch = /^(\d+)-(\d+)$/.exec(seqPart);
+
+      if (seqMatch !== null) {
+        const seqNum = parseInt(seqMatch[1], 10);
+        const seqLen = parseInt(seqMatch[2], 10);
+        const encodedData = components.slice(2).join("/");
+
+        return {
+          urType,
+          partInfo: {
+            isSinglePart: false,
+            seqNum,
+            seqLen,
+            encodedData,
+          },
+        };
+      }
+    }
+
+    // Single-part UR
+    return {
+      urType,
+      partInfo: { isSinglePart: true },
+    };
+  }
+
+  /**
+   * Decodes a multipart UR's fountain part data.
+   */
+  private _decodeFountainPart(partInfo: MultipartInfo): FountainPart {
+    // Decode bytewords
+    const rawData = decodeBytewords(partInfo.encodedData, BytewordsStyle.Minimal);
+
+    if (rawData.length < 8) {
+      throw new URError("Invalid multipart data: too short");
+    }
+
+    // Extract metadata
+    const messageLen =
+      ((rawData[0] << 24) | (rawData[1] << 16) | (rawData[2] << 8) | rawData[3]) >>> 0;
+
+    const checksum =
+      ((rawData[4] << 24) | (rawData[5] << 16) | (rawData[6] << 8) | rawData[7]) >>> 0;
+
+    const data = rawData.slice(8);
+
+    return {
+      seqNum: partInfo.seqNum,
+      seqLen: partInfo.seqLen,
+      messageLen,
+      checksum,
+      data,
+    };
+  }
+
+  /**
+   * Checks if the message is complete.
+   */
+  isComplete(): boolean {
+    return this._decodedMessage !== null;
+  }
+
+  /**
+   * Gets the decoded UR message.
+   *
+   * @returns The decoded UR, or null if not yet complete
+   */
+  message(): UR | null {
+    return this._decodedMessage;
+  }
+
+  /**
+   * Returns the decoding progress as a fraction (0 to 1).
+   */
+  progress(): number {
+    if (this._decodedMessage !== null) {
+      return 1;
+    }
+    if (this._fountainDecoder === null) {
+      return 0;
+    }
+    return this._fountainDecoder.progress();
+  }
+
+  /**
+   * Resets the decoder to receive a new message.
+   */
+  reset(): void {
+    this._urType = null;
+    this._fountainDecoder = null;
+    this._decodedMessage = null;
+  }
+}
+
+/**
+ * Part info for single-part URs.
+ */
+interface SinglePartInfo {
+  isSinglePart: true;
+}
+
+/**
+ * Part info for multipart URs.
+ */
+interface MultipartInfo {
+  isSinglePart: false;
+  seqNum: number;
+  seqLen: number;
+  encodedData: string;
+}
+
+type PartInfo = SinglePartInfo | MultipartInfo;

package/src/multipart-encoder.ts

@@ -0,0 +1,166 @@
+import type { UR } from "./ur.js";
+import { URError } from "./error.js";
+import { FountainEncoder, type FountainPart } from "./fountain.js";
+import { encodeBytewords, BytewordsStyle } from "./utils.js";
+
+/**
+ * Encodes a UR as multiple parts using fountain codes.
+ *
+ * This allows large CBOR structures to be split into multiple UR strings
+ * that can be transmitted separately and reassembled. The encoder uses
+ * fountain codes for resilient transmission over lossy channels.
+ *
+ * For single-part URs (small payloads), use the regular UR.string() method.
+ *
+ * @example
+ * ```typescript
+ * const ur = UR.new('bytes', cbor);
+ * const encoder = new MultipartEncoder(ur, 100);
+ *
+ * // Generate all pure parts
+ * while (!encoder.isComplete()) {
+ *   const part = encoder.nextPart();
+ *   console.log(part); // "ur:bytes/1-10/..."
+ * }
+ *
+ * // Generate additional rateless parts for redundancy
+ * for (let i = 0; i < 5; i++) {
+ *   const part = encoder.nextPart();
+ *   console.log(part); // "ur:bytes/11-10/..."
+ * }
+ * ```
+ */
+export class MultipartEncoder {
+  private readonly _ur: UR;
+  private readonly _fountainEncoder: FountainEncoder;
+  private _currentIndex = 0;
+
+  /**
+   * Creates a new multipart encoder for the given UR.
+   *
+   * @param ur - The UR to encode
+   * @param maxFragmentLen - Maximum length of each fragment in bytes
+   * @throws {URError} If encoding fails
+   *
+   * @example
+   * ```typescript
+   * const encoder = new MultipartEncoder(ur, 100);
+   * ```
+   */
+  constructor(ur: UR, maxFragmentLen: number) {
+    if (maxFragmentLen < 1) {
+      throw new URError("Max fragment length must be at least 1");
+    }
+    this._ur = ur;
+
+    // Create fountain encoder from CBOR data
+    const cborData = ur.cbor().toData();
+    this._fountainEncoder = new FountainEncoder(cborData, maxFragmentLen);
+  }
+
+  /**
+   * Returns whether the message fits in a single part.
+   *
+   * For single-part messages, consider using UR.string() directly.
+   */
+  isSinglePart(): boolean {
+    return this._fountainEncoder.isSinglePart();
+  }
+
+  /**
+   * Gets the next part of the encoding.
+   *
+   * Parts 1 through seqLen are "pure" fragments containing one piece each.
+   * Parts beyond seqLen are "mixed" fragments using fountain codes for redundancy.
+   *
+   * @returns The next UR string part
+   *
+   * @example
+   * ```typescript
+   * const part = encoder.nextPart();
+   * // Returns: "ur:bytes/1-3/lsadaoaxjygonesw"
+   * ```
+   */
+  nextPart(): string {
+    const part = this._fountainEncoder.nextPart();
+    this._currentIndex++;
+    return this._encodePart(part);
+  }
+
+  /**
+   * Encodes a fountain part as a UR string.
+   */
+  private _encodePart(part: FountainPart): string {
+    // For single-part messages, use simple format
+    if (part.seqLen === 1) {
+      return this._ur.string();
+    }
+
+    // Encode the part data as CBOR: [seqNum, seqLen, messageLen, checksum, data]
+    // Using a simple format: seqNum-seqLen prefix followed by bytewords-encoded part
+    const partData = this._encodePartData(part);
+    const encoded = encodeBytewords(partData, BytewordsStyle.Minimal);
+
+    return `ur:${this._ur.urTypeStr()}/${part.seqNum}-${part.seqLen}/${encoded}`;
+  }
+
+  /**
+   * Encodes part metadata and data into bytes for bytewords encoding.
+   */
+  private _encodePartData(part: FountainPart): Uint8Array {
+    // Simple encoding: messageLen (4 bytes) + checksum (4 bytes) + data
+    const result = new Uint8Array(8 + part.data.length);
+
+    // Message length (big-endian)
+    result[0] = (part.messageLen >>> 24) & 0xff;
+    result[1] = (part.messageLen >>> 16) & 0xff;
+    result[2] = (part.messageLen >>> 8) & 0xff;
+    result[3] = part.messageLen & 0xff;
+
+    // Checksum (big-endian)
+    result[4] = (part.checksum >>> 24) & 0xff;
+    result[5] = (part.checksum >>> 16) & 0xff;
+    result[6] = (part.checksum >>> 8) & 0xff;
+    result[7] = part.checksum & 0xff;
+
+    // Fragment data
+    result.set(part.data, 8);
+
+    return result;
+  }
+
+  /**
+   * Gets the current part index.
+   */
+  currentIndex(): number {
+    return this._currentIndex;
+  }
+
+  /**
+   * Gets the total number of pure parts.
+   *
+   * Note: Fountain codes can generate unlimited parts beyond this count
+   * for additional redundancy.
+   */
+  partsCount(): number {
+    return this._fountainEncoder.seqLen;
+  }
+
+  /**
+   * Checks if all pure parts have been emitted.
+   *
+   * Even after this returns true, you can continue calling nextPart()
+   * to generate additional rateless parts for redundancy.
+   */
+  isComplete(): boolean {
+    return this._fountainEncoder.isComplete();
+  }
+
+  /**
+   * Resets the encoder to start from the beginning.
+   */
+  reset(): void {
+    this._currentIndex = 0;
+    this._fountainEncoder.reset();
+  }
+}

package/src/ur-codable.ts

@@ -0,0 +1,48 @@
+import type { UREncodable } from "./ur-encodable.js";
+import type { URDecodable } from "./ur-decodable.js";
+
+/**
+ * A type that can be both encoded to and decoded from a UR.
+ *
+ * This combines the UREncodable and URDecodable interfaces for types
+ * that support bidirectional UR conversion.
+ *
+ * @example
+ * ```typescript
+ * class MyType implements URCodable {
+ *   ur(): UR {
+ *     // Encode to UR
+ *   }
+ *
+ *   urString(): string {
+ *     // Return UR string
+ *   }
+ *
+ *   fromUR(ur: UR): MyType {
+ *     // Decode from UR
+ *   }
+ *
+ *   fromURString(urString: string): MyType {
+ *     // Decode from UR string (convenience method)
+ *     return this.fromUR(UR.fromURString(urString));
+ *   }
+ * }
+ * ```
+ */
+export interface URCodable extends UREncodable, URDecodable {}
+
+/**
+ * Helper function to check if an object implements URCodable.
+ */
+export function isURCodable(obj: unknown): obj is URCodable {
+  return (
+    typeof obj === "object" &&
+    obj !== null &&
+    "ur" in obj &&
+    "urString" in obj &&
+    "fromUR" in obj &&
+    typeof (obj as Record<string, unknown>)["ur"] === "function" &&
+    typeof (obj as Record<string, unknown>)["urString"] === "function" &&
+    typeof (obj as Record<string, unknown>)["fromUR"] === "function"
+  );
+}

package/src/ur-decodable.ts

@@ -0,0 +1,56 @@
+import type { UR } from "./ur.js";
+
+/**
+ * A type that can be decoded from a UR (Uniform Resource).
+ *
+ * Types implementing this interface should be able to create themselves
+ * from a UR containing their data.
+ *
+ * @example
+ * ```typescript
+ * class MyType implements URDecodable {
+ *   fromUR(ur: UR): MyType {
+ *     const cbor = ur.cbor();
+ *     // Decode from CBOR and return MyType instance
+ *   }
+ *
+ *   fromURString(urString: string): MyType {
+ *     return this.fromUR(UR.fromURString(urString));
+ *   }
+ * }
+ * ```
+ */
+export interface URDecodable {
+  /**
+   * Creates an instance of this type from a UR.
+   *
+   * @param ur - The UR to decode from
+   * @returns An instance of this type
+   * @throws If the UR type is wrong or data is malformed
+   */
+  fromUR(ur: UR): unknown;
+
+  /**
+   * Creates an instance of this type from a UR string.
+   *
+   * This is a convenience method that parses the UR string and then
+   * calls fromUR().
+   *
+   * @param urString - The UR string to decode from (e.g., "ur:type/...")
+   * @returns An instance of this type
+   * @throws If the UR string is invalid or data is malformed
+   */
+  fromURString?(urString: string): unknown;
+}
+
+/**
+ * Helper function to check if an object implements URDecodable.
+ */
+export function isURDecodable(obj: unknown): obj is URDecodable {
+  return (
+    typeof obj === "object" &&
+    obj !== null &&
+    "fromUR" in obj &&
+    typeof (obj as Record<string, unknown>)["fromUR"] === "function"
+  );
+}

package/src/ur-encodable.ts

@@ -0,0 +1,47 @@
+import type { UR } from "./ur.js";
+
+/**
+ * A type that can be encoded to a UR (Uniform Resource).
+ *
+ * Types implementing this interface should be able to convert themselves
+ * to CBOR data and associate that with a UR type identifier.
+ *
+ * @example
+ * ```typescript
+ * class MyType implements UREncodable {
+ *   toCBOR(): CBOR {
+ *     // Convert to CBOR
+ *   }
+ *
+ *   ur(): UR {
+ *     const cbor = this.toCBOR();
+ *     return UR.new('mytype', cbor);
+ *   }
+ * }
+ * ```
+ */
+export interface UREncodable {
+  /**
+   * Returns the UR representation of the object.
+   */
+  ur(): UR;
+
+  /**
+   * Returns the UR string representation of the object.
+   */
+  urString(): string;
+}
+
+/**
+ * Helper function to check if an object implements UREncodable.
+ */
+export function isUREncodable(obj: unknown): obj is UREncodable {
+  return (
+    typeof obj === "object" &&
+    obj !== null &&
+    "ur" in obj &&
+    "urString" in obj &&
+    typeof (obj as Record<string, unknown>)["ur"] === "function" &&
+    typeof (obj as Record<string, unknown>)["urString"] === "function"
+  );
+}

package/src/ur-type.ts

@@ -0,0 +1,87 @@
+import { InvalidTypeError } from "./error";
+import { isValidURType } from "./utils";
+
+/**
+ * Represents a UR (Uniform Resource) type identifier.
+ *
+ * Valid UR types contain only lowercase letters, digits, and hyphens.
+ *
+ * @example
+ * ```typescript
+ * const urType = new URType('test');
+ * console.log(urType.string()); // "test"
+ * ```
+ */
+export class URType {
+  private readonly _type: string;
+
+  /**
+   * Creates a new URType from the provided type string.
+   *
+   * @param urType - The UR type as a string
+   * @throws {InvalidTypeError} If the type contains invalid characters
+   *
+   * @example
+   * ```typescript
+   * const urType = new URType('test');
+   * ```
+   */
+  constructor(urType: string) {
+    if (!isValidURType(urType)) {
+      throw new InvalidTypeError();
+    }
+    this._type = urType;
+  }
+
+  /**
+   * Returns the string representation of the URType.
+   *
+   * @example
+   * ```typescript
+   * const urType = new URType('test');
+   * console.log(urType.string()); // "test"
+   * ```
+   */
+  string(): string {
+    return this._type;
+  }
+
+  /**
+   * Checks equality with another URType based on the type string.
+   */
+  equals(other: URType): boolean {
+    return this._type === other._type;
+  }
+
+  /**
+   * Returns the string representation.
+   */
+  toString(): string {
+    return this._type;
+  }
+
+  /**
+   * Creates a URType from a string, throwing an error if invalid.
+   *
+   * @param value - The UR type string
+   * @returns A new URType instance
+   * @throws {InvalidTypeError} If the type is invalid
+   */
+  static from(value: string): URType {
+    return new URType(value);
+  }
+
+  /**
+   * Safely creates a URType, returning an error if invalid.
+   *
+   * @param value - The UR type string
+   * @returns Either a URType or an error
+   */
+  static tryFrom(value: string): URType | InvalidTypeError {
+    try {
+      return new URType(value);
+    } catch (error) {
+      return error as InvalidTypeError;
+    }
+  }
+}