@honch/react-native-relay 0.1.0

package/src/uploader.ts

@@ -0,0 +1,165 @@
+import type { StoredRelayMessage } from "./relayQueue";
+import { buildSingleWireV2Frame, buildWireV2Frames, MAX_WIRE_V2_FRAME_SIZE } from "./wireV2";
+
+export type RelayUploaderConfig = {
+  endpointUrl: string;
+  projectKey: string;
+  relayId: string;
+  relaySdkPlatform: string;
+  relaySdkVersion: string;
+  streamId(message: StoredRelayMessage): string;
+  messageId(message: StoredRelayMessage): number;
+  // Max wire-v2 frame size for re-chunking; defaults to MAX_WIRE_V2_FRAME_SIZE.
+  maxFrameSize?: number;
+};
+
+export type RelayUploadOutcome =
+  | { action: "consume"; status: number }
+  | { action: "drop"; status?: number; error?: unknown }
+  | { action: "retry"; status?: number; retryAfterMs?: number; error?: unknown };
+
+export function buildRelayUploadBuffer(
+  config: Pick<RelayUploaderConfig, "messageId">,
+  message: StoredRelayMessage
+): ArrayBuffer {
+  const frame = buildSingleWireV2Frame({
+    messageId: config.messageId(message),
+    payload: message.body
+  });
+  const body = new ArrayBuffer(frame.byteLength);
+  new Uint8Array(body).set(frame);
+  return body;
+}
+
+export async function uploadRelayMessage(
+  config: RelayUploaderConfig,
+  message: StoredRelayMessage
+): Promise<void> {
+  const outcome = await uploadRelayMessageOutcome(config, message);
+  if (outcome.action === "consume") {
+    return;
+  }
+  if (outcome.status !== undefined) {
+    throw new Error(`relay upload failed: ${outcome.status}`);
+  }
+  throw new Error("relay upload failed: network");
+}
+
+export async function uploadRelayMessageOutcome(
+  config: RelayUploaderConfig,
+  message: StoredRelayMessage
+): Promise<RelayUploadOutcome> {
+  // Header values flow straight into the HTTP request. Reject control characters
+  // (CR/LF/NUL) in the project key and the stream id (derived from the device
+  // id) so a crafted value cannot inject headers -- and so an illegal value
+  // can't make fetch throw and wedge the message in an endless retry loop.
+  const streamId = config.streamId(message);
+  if (!isSafeHeaderValue(config.projectKey) || !isSafeHeaderValue(streamId)) {
+    return { action: "drop", error: new Error("relay header value contains control characters") };
+  }
+
+  // Re-chunk the (possibly oversized) reassembled body into wire-v2 frames and
+  // POST them in order: every non-final frame must return 202 (stored, send
+  // next), and the final frame returns 204 (complete). Any error mid-sequence
+  // ends the attempt; the whole message is retried from the first frame (which
+  // also satisfies 409 "retry from offset 0").
+  let frames: Uint8Array[];
+  try {
+    frames = buildWireV2Frames(
+      config.messageId(message),
+      message.body,
+      config.maxFrameSize ?? MAX_WIRE_V2_FRAME_SIZE
+    );
+  } catch (error) {
+    // An un-encodable message id (e.g. beyond the wire-v2 safe-integer range)
+    // can never succeed on retry, so drop this one message instead of letting
+    // the throw propagate and stall the entire drain.
+    return { action: "drop", error };
+  }
+  const url = `${config.endpointUrl.replace(/\/$/, "")}/capture`;
+  const headers = {
+    "Content-Type": "application/vnd.honch.chunk",
+    "X-Honch-Project-Key": config.projectKey,
+    "X-Honch-Stream-Id": streamId,
+    "X-Honch-Relay-Id": config.relayId,
+    "X-Honch-Relay-SDK-Platform": config.relaySdkPlatform,
+    "X-Honch-Relay-SDK-Version": config.relaySdkVersion
+  };
+
+  for (let index = 0; index < frames.length; index += 1) {
+    const isFinal = index === frames.length - 1;
+    const body = new ArrayBuffer(frames[index].byteLength);
+    new Uint8Array(body).set(frames[index]);
+
+    let response: Response;
+    try {
+      response = await fetch(url, { method: "POST", headers, body });
+    } catch (error) {
+      return { action: "retry", error };
+    }
+
+    const outcome = classifyFrameResponse(response, isFinal);
+    if (outcome !== "continue") {
+      return outcome;
+    }
+  }
+
+  // Unreachable: the final frame always yields a terminal outcome.
+  return { action: "retry" };
+}
+
+function classifyFrameResponse(response: Response, isFinal: boolean): RelayUploadOutcome | "continue" {
+  if (isFinal) {
+    if (response.status === 204) {
+      return { action: "consume", status: response.status };
+    }
+  } else if (response.status === 202) {
+    return "continue";
+  }
+  // Permanent rejections (matching the C SDK status mapping): malformed (400),
+  // bad key (401), not found (404), payload too large (413), unsupported content
+  // type (415), semantic validation failure (422). 413 is permanent: the relay
+  // already re-chunks to a fixed frame size, so retrying the identical bytes can
+  // never clear it -- an oversized payload is dropped and logged like the C SDK.
+  if (
+    response.status === 400 ||
+    response.status === 401 ||
+    response.status === 404 ||
+    response.status === 413 ||
+    response.status === 415 ||
+    response.status === 422
+  ) {
+    return { action: "drop", status: response.status };
+  }
+  // Everything else -- 409 (retry from offset 0), 429, 5xx, and any
+  // out-of-sequence 202/204 -- retries the whole message.
+  return {
+    action: "retry",
+    status: response.status,
+    retryAfterMs: parseRetryAfterMs(response.headers.get("Retry-After"))
+  };
+}
+
+function isSafeHeaderValue(value: string): boolean {
+  // HTTP header values must not carry control characters; CR/LF in particular
+  // would allow header injection, and most fetch implementations throw on them.
+  return typeof value === "string" && !/[\x00-\x1f\x7f]/.test(value);
+}
+
+function parseRetryAfterMs(value: string | null): number | undefined {
+  if (value === null) {
+    return undefined;
+  }
+
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return Math.round(seconds * 1000);
+  }
+
+  const retryAt = Date.parse(value);
+  if (!Number.isFinite(retryAt)) {
+    return undefined;
+  }
+
+  return Math.max(0, retryAt - Date.now());
+}

package/src/wireV2.ts

@@ -0,0 +1,198 @@
+export type WireV2FrameOptions = {
+  messageId: number;
+  payload: Uint8Array;
+};
+
+const VERSION_CODE = 2;
+const SOURCE_TYPE_EVENTS = 0;
+
+export function buildSingleWireV2Frame(options: WireV2FrameOptions): Uint8Array {
+  const messageId = encodeUvarint(options.messageId);
+  const crc = crc16CcittFalse(options.payload);
+  const header = (SOURCE_TYPE_EVENTS << 2) | VERSION_CODE;
+  const frame = new Uint8Array(1 + messageId.length + options.payload.length + 2);
+  let offset = 0;
+  frame[offset++] = header;
+  frame.set(messageId, offset);
+  offset += messageId.length;
+  frame.set(options.payload, offset);
+  offset += options.payload.length;
+  frame[offset++] = crc & 0xff;
+  frame[offset] = (crc >> 8) & 0xff;
+  return frame;
+}
+
+export function encodeUvarint(value: number): Uint8Array {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error("wire-v2 message id must be a non-negative safe integer");
+  }
+
+  const bytes: number[] = [];
+  let remaining = value;
+  do {
+    let byte = remaining & 0x7f;
+    remaining = Math.floor(remaining / 128);
+    if (remaining !== 0) {
+      byte |= 0x80;
+    }
+    bytes.push(byte);
+  } while (remaining !== 0);
+
+  return new Uint8Array(bytes);
+}
+
+const HEADER_CONTINUATION = 0x20;
+const HEADER_MORE = 0x40;
+const FINAL_CRC_SIZE = 2;
+
+// Matches the shipping C SDK frame size (HONCH_WIRE_V2_MAX_FRAME_BYTES), which
+// Capture is known to accept, so re-chunked relay frames are guaranteed valid.
+export const MAX_WIRE_V2_FRAME_SIZE = 4096;
+
+export function uvarintSize(value: number): number {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error("wire-v2 uvarint must be a non-negative safe integer");
+  }
+  let size = 1;
+  let remaining = Math.floor(value / 128);
+  while (remaining !== 0) {
+    size += 1;
+    remaining = Math.floor(remaining / 128);
+  }
+  return size;
+}
+
+function frameOverhead(
+  messageId: number,
+  offset: number,
+  total: number,
+  continuation: boolean,
+  more: boolean
+): number {
+  let overhead = 1 + uvarintSize(messageId);
+  if (continuation) {
+    overhead += uvarintSize(offset);
+  } else if (more) {
+    overhead += uvarintSize(total);
+  }
+  if (!more) {
+    overhead += FINAL_CRC_SIZE;
+  }
+  return overhead;
+}
+
+function encodeWireV2Frame(
+  messageId: number,
+  payload: Uint8Array,
+  offset: number,
+  total: number,
+  continuation: boolean,
+  more: boolean,
+  crcWholeMessage: number
+): Uint8Array {
+  const messageIdBytes = encodeUvarint(messageId);
+  const positionBytes = continuation
+    ? encodeUvarint(offset)
+    : more
+      ? encodeUvarint(total)
+      : new Uint8Array(0);
+
+  let header = (SOURCE_TYPE_EVENTS << 2) | VERSION_CODE;
+  if (continuation) header |= HEADER_CONTINUATION;
+  if (more) header |= HEADER_MORE;
+
+  const size =
+    1 + messageIdBytes.length + positionBytes.length + payload.length + (more ? 0 : FINAL_CRC_SIZE);
+  const frame = new Uint8Array(size);
+  let p = 0;
+  frame[p++] = header;
+  frame.set(messageIdBytes, p);
+  p += messageIdBytes.length;
+  frame.set(positionBytes, p);
+  p += positionBytes.length;
+  frame.set(payload, p);
+  p += payload.length;
+  if (!more) {
+    // CRC is over the WHOLE reassembled message, not just this final chunk.
+    frame[p++] = crcWholeMessage & 0xff;
+    frame[p] = (crcWholeMessage >> 8) & 0xff;
+  }
+  return frame;
+}
+
+// Split a complete compact message into wire-v2 frames each <= maxFrameSize,
+// so an oversized relayed body is delivered as a multi-frame sequence rather
+// than a single over-limit frame. A payload that already fits returns one frame
+// (byte-identical to buildSingleWireV2Frame). Faithful port of the C chunker.
+export function buildWireV2Frames(
+  messageId: number,
+  payload: Uint8Array,
+  maxFrameSize: number = MAX_WIRE_V2_FRAME_SIZE
+): Uint8Array[] {
+  if (!Number.isSafeInteger(maxFrameSize) || maxFrameSize < 8) {
+    throw new Error("wire-v2 max frame size too small");
+  }
+  const total = payload.length;
+  const crcWhole = crc16CcittFalse(payload);
+
+  if (total === 0) {
+    return [encodeWireV2Frame(messageId, payload, 0, 0, false, false, crcWhole)];
+  }
+
+  const frames: Uint8Array[] = [];
+  let offset = 0;
+  do {
+    const continuation = offset !== 0;
+    const remaining = total - offset;
+
+    const finalOverhead = frameOverhead(messageId, offset, total, continuation, false);
+    if (finalOverhead >= maxFrameSize) {
+      throw new Error("wire-v2 frame overhead exceeds max frame size");
+    }
+    const finalCapacity = maxFrameSize - finalOverhead;
+
+    const more = remaining > finalCapacity;
+    let payloadCapacity = finalCapacity;
+    if (more) {
+      const moreOverhead = frameOverhead(messageId, offset, total, continuation, true);
+      if (moreOverhead >= maxFrameSize) {
+        throw new Error("wire-v2 frame overhead exceeds max frame size");
+      }
+      payloadCapacity = maxFrameSize - moreOverhead;
+    }
+
+    let payloadSize = Math.min(remaining, payloadCapacity);
+    if (more && payloadSize >= remaining) {
+      payloadSize = remaining - finalCapacity;
+    }
+    if (payloadSize <= 0) {
+      throw new Error("wire-v2 produced a non-positive frame payload");
+    }
+
+    frames.push(
+      encodeWireV2Frame(
+        messageId,
+        payload.subarray(offset, offset + payloadSize),
+        offset,
+        total,
+        continuation,
+        more,
+        crcWhole
+      )
+    );
+    offset += payloadSize;
+  } while (offset < total);
+
+  return frames;
+}
+
+export function crc16CcittFalse(bytes: Uint8Array): number {
+  let crc = 0xffff;
+  for (const byte of bytes) {
+    crc ^= byte << 8;
+    for (let bit = 0; bit < 8; bit += 1) {
+      crc = (crc & 0x8000) !== 0 ? ((crc << 1) ^ 0x1021) & 0xffff : (crc << 1) & 0xffff;
+    }
+  }
+  return crc;
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["vitest/globals"]
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"]
+}