sailfork / t3code-github / .repos/ alchemy-effect/ packages/ git/ src/ Protocol/ Pkt.ts

/**
 * pkt-line framing (gitprotocol-common).
 *
 * Every protocol message except raw pack bytes is a stream of pkt-lines:
 * 4 lowercase hex digits (total length INCLUDING the 4 length bytes) followed
 * by the payload. Max total length 65520 ⇒ max payload 65516.
 *
 * Special packets whose length field is not a length:
 *
 * | bytes  | meaning                                    |
 * |--------|--------------------------------------------|
 * | `0000` | flush-pkt — end of message/request/response |
 * | `0001` | delim-pkt — section separator (v2)          |
 * | `0002` | response-end-pkt (v2, stateless)            |
 *
 * Readers MUST strip an optional trailing LF from text payloads; writers
 * SHOULD append one. `ERR <msg>` payloads report in-band fatals once a 200
 * has begun.
 */
import * as Arr from "effect/Array";
import * as Cause from "effect/Cause";
import * as Effect from "effect/Effect";
import * as Pull from "effect/Pull";
import * as Schema from "effect/Schema";
import * as Stream from "effect/Stream";
import { concatBytes, utf8Decode, utf8Encode } from "./ObjectCodec.ts";

/**
 * Maximum pkt-line payload: 65520 total − 4 length bytes.
 */
export const MAX_PKT_PAYLOAD = 65516;

/**
 * Error raised on malformed pkt-line framing (bad hex length, out-of-range
 * length, truncated payload, oversize writer payload).
 */
export class PktLineError extends Schema.TaggedError<PktLineError>()("PktLineError", {
  reason: Schema.String,
}) {}

/**
 * Error raised when a syntactically valid pkt-line stream contains a request
 * the protocol grammar does not allow (bad `want`/`have`/command lines,
 * unsupported arguments). Shared by `UploadPack` and `ReceivePack`.
 */
export class ProtocolError extends Schema.TaggedError<ProtocolError>()("ProtocolError", {
  reason: Schema.String,
}) {}

/**
 * One decoded pkt-line: a data packet with its payload, or one of the three
 * special packets.
 */
export type PktLine =
  | { readonly _tag: "data"; readonly payload: Uint8Array }
  | { readonly _tag: "flush" }
  | { readonly _tag: "delim" }
  | { readonly _tag: "responseEnd" };

/** The flush packet singleton. */
export const flush: PktLine = { _tag: "flush" };
/** The delim packet singleton. */
export const delim: PktLine = { _tag: "delim" };

/** The 4 raw bytes of a flush-pkt (`0000`). */
export const flushPkt: Uint8Array = utf8Encode("0000");
/** The 4 raw bytes of a delim-pkt (`0001`). */
export const delimPkt: Uint8Array = utf8Encode("0001");

const HEX_CHARS = "0123456789abcdef";

const encodeLength = (n: number): Uint8Array => {
  const out = new Uint8Array(4);
  out[0] = HEX_CHARS.charCodeAt((n >> 12) & 0xf);
  out[1] = HEX_CHARS.charCodeAt((n >> 8) & 0xf);
  out[2] = HEX_CHARS.charCodeAt((n >> 4) & 0xf);
  out[3] = HEX_CHARS.charCodeAt(n & 0xf);
  return out;
};

/**
 * Encodes a data pkt-line around a binary payload (no LF appended). Throws
 * {@link PktLineError} when the payload exceeds {@link MAX_PKT_PAYLOAD} —
 * an internal invariant violation, since all writers cap their payloads.
 */
export const pktLine = (payload: Uint8Array): Uint8Array => {
  if (payload.length > MAX_PKT_PAYLOAD) {
    throw PktLineError.make({
      reason: `pkt-line payload ${payload.length} exceeds ${MAX_PKT_PAYLOAD}`,
    });
  }
  const out = new Uint8Array(4 + payload.length);
  out.set(encodeLength(payload.length + 4), 0);
  out.set(payload, 4);
  return out;
};

/**
 * Encodes a text pkt-line, appending the conventional trailing LF when the
 * text does not already end with one.
 */
export const pktText = (text: string): Uint8Array =>
  pktLine(utf8Encode(text.endsWith("\n") ? text : `${text}\n`));

/**
 * Encodes an `ERR ` pkt-line. Usable anywhere in a response (including in
 * place of an advertisement); the client prints `remote error: <message>`
 * and aborts.
 */
export const errPkt = (message: string): Uint8Array => pktText(`ERR ${message}`);

/**
 * Decodes a data pkt-line payload as UTF-8 text with the optional trailing
 * LF stripped (readers MUST strip it).
 */
export const pktPayloadText = (payload: Uint8Array): string => {
  const trimmed =
    payload.length > 0 && payload[payload.length - 1] === 0x0a
      ? payload.subarray(0, payload.length - 1)
      : payload;
  return utf8Decode(trimmed);
};

/**
 * Result of attempting to read one pkt-line at an offset.
 */
export type PktReadResult =
  | { readonly _tag: "pkt"; readonly pkt: PktLine; readonly next: number }
  | { readonly _tag: "incomplete" }
  | { readonly _tag: "invalid"; readonly reason: string };

const hexDigit = (byte: number): number => {
  if (byte >= 0x30 && byte <= 0x39) return byte - 0x30;
  if (byte >= 0x61 && byte <= 0x66) return byte - 0x61 + 10;
  if (byte >= 0x41 && byte <= 0x46) return byte - 0x41 + 10;
  return -1;
};

/**
 * Attempts to read one pkt-line from `buf` at `offset` without copying.
 * Returns `incomplete` when more bytes are needed, `invalid` on malformed
 * framing, or the decoded packet and the offset of the next one.
 */
export const readPktLineAt = (buf: Uint8Array, offset: number): PktReadResult => {
  if (offset + 4 > buf.length) return { _tag: "incomplete" };
  let n = 0;
  for (let i = 0; i < 4; i++) {
    const d = hexDigit(buf[offset + i]!);
    if (d === -1) {
      return {
        _tag: "invalid",
        reason: `invalid pkt-line length at offset ${offset}`,
      };
    }
    n = (n << 4) | d;
  }
  if (n === 0) return { _tag: "pkt", pkt: flush, next: offset + 4 };
  if (n === 1) return { _tag: "pkt", pkt: delim, next: offset + 4 };
  if (n === 2) {
    return { _tag: "pkt", pkt: { _tag: "responseEnd" }, next: offset + 4 };
  }
  if (n === 3) {
    return { _tag: "invalid", reason: `invalid pkt-line length 0003` };
  }
  if (n > MAX_PKT_PAYLOAD + 4) {
    return {
      _tag: "invalid",
      reason: `pkt-line length ${n} exceeds maximum 65520`,
    };
  }
  if (offset + n > buf.length) return { _tag: "incomplete" };
  return {
    _tag: "pkt",
    pkt: { _tag: "data", payload: buf.subarray(offset + 4, offset + n) },
    next: offset + n,
  };
};

/**
 * Decodes an entire buffer (from `offset`) as consecutive pkt-lines. Fails
 * with {@link PktLineError} when the buffer ends mid-packet or contains
 * malformed framing.
 */
export const decodePktLines = (
  buf: Uint8Array,
  offset = 0,
): Effect.Effect<ReadonlyArray<PktLine>, PktLineError> =>
  Effect.suspend(() => {
    const out: Array<PktLine> = [];
    let pos = offset;
    while (pos < buf.length) {
      const r = readPktLineAt(buf, pos);
      switch (r._tag) {
        case "pkt":
          out.push(r.pkt);
          pos = r.next;
          break;
        case "incomplete":
          return Effect.fail(PktLineError.make({ reason: `truncated pkt-line at offset ${pos}` }));
        case "invalid":
          return Effect.fail(PktLineError.make({ reason: r.reason }));
      }
    }
    return Effect.succeed(out);
  });

const EMPTY = new Uint8Array(0);

/**
 * Stream transform: decodes a byte stream into a stream of pkt-lines,
 * buffering partial packets across chunk boundaries. Fails with
 * {@link PktLineError} on malformed framing or a truncated trailing packet.
 *
 * Note: payloads are copied out of the internal buffer so they remain valid
 * after the transform advances.
 */
export const decodePktStream = <E, R>(
  input: Stream.Stream<Uint8Array, E, R>,
): Stream.Stream<PktLine, E | PktLineError, R> =>
  Stream.transformPull(input, (pull) =>
    Effect.sync(() => {
      let buffer: Uint8Array = EMPTY;
      let upstreamDone = false;

      const drain = (): Array<PktLine> | PktLineError => {
        const out: Array<PktLine> = [];
        let pos = 0;
        for (;;) {
          const r = readPktLineAt(buffer, pos);
          if (r._tag === "incomplete") break;
          if (r._tag === "invalid") {
            return PktLineError.make({ reason: r.reason });
          }
          // copy the payload: the backing buffer is replaced on refill
          out.push(
            r.pkt._tag === "data"
              ? { _tag: "data", payload: Uint8Array.from(r.pkt.payload) }
              : r.pkt,
          );
          pos = r.next;
        }
        buffer = pos === 0 ? buffer : buffer.subarray(pos);
        return out;
      };

      const loop: Pull.Pull<
        Arr.NonEmptyReadonlyArray<PktLine>,
        E | PktLineError,
        void
      > = Effect.suspend(() => {
        const drained = drain();
        if (Schema.is(PktLineError)(drained)) return Effect.fail(drained);
        if (Arr.isReadonlyArrayNonEmpty(drained)) {
          return Effect.succeed(drained);
        }
        if (upstreamDone) {
          if (buffer.length > 0) {
            return Effect.fail(
              PktLineError.make({
                reason: "byte stream ended inside a pkt-line",
              }),
            );
          }
          return Cause.done();
        }
        return pull.pipe(
          Effect.map((chunks) => {
            buffer = concatBytes([buffer, ...chunks]);
          }),
          Pull.catchDone(() =>
            Effect.sync(() => {
              upstreamDone = true;
            }),
          ),
          Effect.flatMap(() => loop),
        );
      });

      return loop;
    }),
  );