@push.rocks/smartlinuxrepo 0.0.0-stage → 0.1.0

package/ts/shared/errors.ts

@@ -0,0 +1,78 @@
+import type { ILinuxPackageLimits } from './limits.js';
+
+/**
+ * Stable error codes.
+ * - `limit-exceeded`: an `ILinuxPackageLimits` bound was crossed (`detail.limit` names it).
+ * - `unsupported-compression`: a compression the format does not allow.
+ * - `malformed-archive`: broken container structure (ar, tar, gzip, xz, zstd framing or data).
+ * - `malformed-header`: a broken package header (RPM lead and headers).
+ * - `missing-field` / `invalid-field`: package metadata that is absent or not acceptable.
+ * - `unsupported-package-format`: input that is not the expected package format, or uses a form of it
+ *   the codec does not read (the data of a sparse tar entry).
+ * - `truncated`: only a clean early end of input.
+ * - `digest-mismatch`: a digest the package carries does not match its bytes.
+ * - `invalid-input`: a bad argument from the caller.
+ * - `invalid-key`: a key the codec cannot use.
+ * - `signing-failed`: a codec signer failed, or a signer returned something that is not signature bytes.
+ *
+ * The codec never wraps an error it did not raise: an error from the caller's
+ * source or from a caller-supplied signer propagates unchanged. An underlying
+ * error the codec reacts to is kept in the standard `cause`.
+ */
+export type TLinuxRepoErrorCode =
+  | 'limit-exceeded'
+  | 'unsupported-compression'
+  | 'malformed-archive'
+  | 'malformed-header'
+  | 'missing-field'
+  | 'invalid-field'
+  | 'unsupported-package-format'
+  | 'truncated'
+  | 'digest-mismatch'
+  | 'invalid-input'
+  | 'invalid-key'
+  | 'signing-failed';
+
+/** Names the field, structure or limit an error is about. */
+export interface ILinuxRepoErrorDetail {
+  field?: string;
+  limit?: keyof ILinuxPackageLimits;
+  value?: number | string;
+}
+
+export class LinuxRepoError extends Error {
+  public readonly code: TLinuxRepoErrorCode;
+  public readonly detail: Readonly<ILinuxRepoErrorDetail>;
+
+  constructor(
+    codeArg: TLinuxRepoErrorCode,
+    messageArg: string,
+    detailArg: ILinuxRepoErrorDetail = {},
+    optionsArg?: { cause?: unknown },
+  ) {
+    super(
+      messageArg,
+      optionsArg !== undefined && 'cause' in optionsArg ? { cause: optionsArg.cause } : undefined,
+    );
+    this.name = 'LinuxRepoError';
+    this.code = codeArg;
+    this.detail = Object.freeze({ ...detailArg });
+  }
+}
+
+/** Builds the `limit-exceeded` error for one limit. */
+export function limitExceeded(
+  limitArg: keyof ILinuxPackageLimits,
+  maximumArg: number,
+  whatArg: string,
+): LinuxRepoError {
+  return new LinuxRepoError('limit-exceeded', `${whatArg} exceeds ${limitArg} (${maximumArg})`, {
+    limit: limitArg,
+    value: maximumArg,
+  });
+}
+
+/** Builds the `truncated` error for a structure the input ended inside. */
+export function truncated(whatArg: string): LinuxRepoError {
+  return new LinuxRepoError('truncated', `input ended inside ${whatArg}`, { field: whatArg });
+}

package/ts/shared/gopath.ts

@@ -0,0 +1,54 @@
+/**
+ * Go 1.27 `path` semantics (slash-separated paths) the codec mirrors where
+ * Gitea 28.2.0 output depends on them.
+ */
+
+/** Go `path.Clean` (`src/path/path.go:72`). */
+export function goPathClean(pathArg: string): string {
+  if (pathArg === '') {
+    return '.';
+  }
+  const rooted = pathArg.startsWith('/');
+  const parts: string[] = [];
+  for (const element of pathArg.split('/')) {
+    if (element === '' || element === '.') {
+      continue;
+    }
+    if (element === '..') {
+      if (parts.length > 0 && parts[parts.length - 1] !== '..') {
+        parts.pop();
+      } else if (!rooted) {
+        parts.push('..');
+      }
+      continue;
+    }
+    parts.push(element);
+  }
+  const joined = parts.join('/');
+  if (rooted) {
+    return `/${joined}`;
+  }
+  return joined === '' ? '.' : joined;
+}
+
+/**
+ * Go `path.Join` (`src/path/path.go:155`): empty elements are ignored, the
+ * result is cleaned, and all-empty input gives `''`.
+ */
+export function goPathJoin(elementsArg: string[]): string {
+  const joined = elementsArg.filter((element) => element !== '').join('/');
+  return joined === '' ? '' : goPathClean(joined);
+}
+
+/** Go `path.Base` (`src/path/path.go:192`). */
+export function goPathBase(pathArg: string): string {
+  if (pathArg === '') {
+    return '.';
+  }
+  let path = pathArg.replace(/\/+$/, '');
+  const slash = path.lastIndexOf('/');
+  if (slash >= 0) {
+    path = path.slice(slash + 1);
+  }
+  return path === '' ? '/' : path;
+}

package/ts/shared/gostrings.ts

@@ -0,0 +1,31 @@
+/**
+ * Go standard-library string semantics the Arch and Alpine readers mirror, so
+ * derived values match Gitea 28.2.0 (`modules/packages/{arch,alpine}/metadata.go`).
+ */
+
+/**
+ * Go `strings.TrimSpace`: trims Unicode `White_Space` (Go `unicode.IsSpace`).
+ * Unlike `String.prototype.trim` it keeps U+FEFF and trims U+0085.
+ */
+export function goTrimSpace(valueArg: string): string {
+  return valueArg.replace(GO_SPACE_START, '').replace(GO_SPACE_END, '');
+}
+
+const GO_SPACE_CLASS = '[\\t\\n\\v\\f\\r \\u0085\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000]';
+const GO_SPACE_START = new RegExp(`^${GO_SPACE_CLASS}+`);
+const GO_SPACE_END = new RegExp(`${GO_SPACE_CLASS}+$`);
+
+/**
+ * Go `strconv.ParseInt(value, 10, 64)`: an optional sign and ASCII digits,
+ * within int64. Returns `null` where Go returns an error.
+ */
+export function goParseInt64(valueArg: string): bigint | null {
+  if (!/^[+-]?[0-9]+$/.test(valueArg)) {
+    return null;
+  }
+  const value = BigInt(valueArg);
+  if (value > 0x7fffffffffffffffn || value < -0x8000000000000000n) {
+    return null;
+  }
+  return value;
+}

package/ts/shared/limits.ts

@@ -0,0 +1,93 @@
+import { LinuxRepoError } from './errors.js';
+
+/**
+ * Hard bounds for reading a package. Callers override them per call with a
+ * `Partial`; every value is a positive safe integer. The defaults accept
+ * everything a stock Gitea 28.2.0 stores except a deb control member that
+ * decompresses past 32 MiB (see `DEFAULT_LINUX_PACKAGE_LIMITS`); an override
+ * below a default may refuse packages Gitea accepts.
+ */
+export interface ILinuxPackageLimits {
+  /** The whole package input, in bytes. */
+  maxPackageBytes: number;
+  /**
+   * One buffered metadata unit, in bytes: the apk control gzip member, the deb
+   * control member, or the RPM signature header plus main header.
+   */
+  maxMetadataBytes: number;
+  /** The decompressed deb `control.tar`, the apk control tar, or Arch's `.PKGINFO`, in bytes. */
+  maxDecompressedMetadataBytes: number;
+  /** The decompressed Arch payload walked for the file list, in bytes. */
+  maxPayloadBytes: number;
+  /** Tar or ar entries per archive, and values per multi-valued metadata field. */
+  maxEntries: number;
+  /** Total bytes of Arch file names. */
+  maxFileListBytes: number;
+  /**
+   * One tar header chain (the header blocks plus PAX records and GNU long
+   * names), or one metadata line, in bytes. RPM headers count under
+   * `maxMetadataBytes`, not here.
+   */
+  maxHeaderBytes: number;
+}
+
+const KiB = 1024;
+const MiB = 1024 * KiB;
+const GiB = 1024 * MiB;
+
+/**
+ * The default limits. They accept anything a stock Gitea 28.2.0 stores in
+ * practice (Gitea has no package size cap), with one exception:
+ * - `maxDecompressedMetadataBytes` is Gitea's 32 MiB deb control bound, but
+ *   Gitea cuts the decompressed stream there and keeps a `control` found
+ *   before the cut, where the codec refuses the member with `limit-exceeded`;
+ * - `maxEntries` and `maxFileListBytes` are Gitea's Arch file-list caps
+ *   (Alpine's 1024 `.PKGINFO` values fold into `maxEntries`);
+ * - `maxHeaderBytes` covers a full PAX + GNU long name + GNU long link chain at
+ *   Go `archive/tar`'s 1 MiB per special record, and Gitea's 64 KiB line limit.
+ */
+export const DEFAULT_LINUX_PACKAGE_LIMITS: Readonly<ILinuxPackageLimits> = Object.freeze({
+  maxPackageBytes: 8 * GiB,
+  maxMetadataBytes: 64 * MiB,
+  maxDecompressedMetadataBytes: 32 * MiB,
+  maxPayloadBytes: 16 * GiB,
+  maxEntries: 100_000,
+  maxFileListBytes: 16 * MiB,
+  maxHeaderBytes: 4 * MiB,
+});
+
+const LIMIT_KEYS = Object.keys(DEFAULT_LINUX_PACKAGE_LIMITS) as Array<keyof ILinuxPackageLimits>;
+
+/**
+ * Merges per-call overrides over the defaults. Unknown keys and values that
+ * are not positive safe integers are refused with `invalid-input`.
+ */
+export function resolveLinuxPackageLimits(
+  overrides?: Partial<ILinuxPackageLimits>,
+): Readonly<ILinuxPackageLimits> {
+  if (overrides === undefined) {
+    return DEFAULT_LINUX_PACKAGE_LIMITS;
+  }
+  if (overrides === null || typeof overrides !== 'object' || Array.isArray(overrides)) {
+    throw new LinuxRepoError('invalid-input', 'limits must be an object', { field: 'limits' });
+  }
+  const resolved: ILinuxPackageLimits = { ...DEFAULT_LINUX_PACKAGE_LIMITS };
+  for (const key of Object.keys(overrides)) {
+    if (!(LIMIT_KEYS as string[]).includes(key)) {
+      throw new LinuxRepoError('invalid-input', `unknown limit "${key}"`, { field: 'limits', value: key });
+    }
+    const limitKey = key as keyof ILinuxPackageLimits;
+    const value = overrides[limitKey];
+    if (value === undefined) {
+      continue;
+    }
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+      throw new LinuxRepoError('invalid-input', `limit ${limitKey} must be a positive safe integer`, {
+        field: 'limits',
+        limit: limitKey,
+      });
+    }
+    resolved[limitKey] = value;
+  }
+  return Object.freeze(resolved);
+}

package/ts/shared/types.ts

@@ -0,0 +1,251 @@
+/**
+ * The persisted record shapes of `@push.rocks/smartlinuxrepo`.
+ *
+ * Records are public API: every field is plain JSON (strings,
+ * integers within `Number.MAX_SAFE_INTEGER`, booleans, arrays and objects; no
+ * `Date`, no `Uint8Array`). Hashes are lowercase hex. Every 1.0.0 key is
+ * required and always present, using Gitea's zero values (`''`, `0`, `[]`);
+ * keys added in a later minor are optional because older persisted records lack
+ * them. Changing a shape needs a major release. The union is not closed: a
+ * later minor may add a fifth format.
+ */
+
+/** The package formats the codec reads and indexes. */
+export type TLinuxPackageFormat = 'alpine' | 'debian' | 'rpm' | 'arch';
+
+/** Size and digests over the whole package file. */
+export interface ILinuxPackageDigests {
+  /** Byte count of the whole file. */
+  size: number;
+  md5: string;
+  sha1: string;
+  sha256: string;
+  sha512: string;
+}
+
+export interface IAlpinePackageDigests extends ILinuxPackageDigests {
+  /**
+   * SHA-1 of the exact bytes of the gzip member holding `.PKGINFO`. The
+   * APKINDEX `C:` value is `'Q1'` plus the base64 of these 20 bytes.
+   */
+  controlSha1: string;
+}
+
+export interface ILinuxPackageRecordBase {
+  format: TLinuxPackageFormat;
+  name: string;
+  /** Gitea's version string (RPM: `V-R`, or `E-V-R` with a dash when the epoch is not `0`). */
+  version: string;
+  /** The architecture as the package states it (`''` is possible for Alpine). */
+  architecture: string;
+  /** Gitea's stored file name for the package. */
+  fileName: string;
+  digests: ILinuxPackageDigests;
+}
+
+// ---------------------------------------------------------------- Alpine
+
+export interface IAlpinePackageMetadata {
+  description: string;
+  license: string;
+  /** The `.PKGINFO` url when Gitea's URL validation accepts it, else `''`. */
+  projectUrl: string;
+  maintainer: string;
+  packager: string;
+  buildDate: number;
+  installedSize: number;
+  origin: string;
+  commit: string;
+  installIf: string;
+  provides: string[];
+  dependencies: string[];
+  providerPriority: number;
+}
+
+export interface IAlpinePackageRecord extends ILinuxPackageRecordBase {
+  format: 'alpine';
+  digests: IAlpinePackageDigests;
+  metadata: IAlpinePackageMetadata;
+}
+
+// ---------------------------------------------------------------- Debian
+
+export interface IDebianPackageMetadata {
+  /**
+   * Gitea's trimmed control stanza, exactly as Gitea 28.2.0 derives it. It is
+   * the source of truth for the `Packages` stanza. Index-owned fields a crafted
+   * control file carries (`Filename`, `Size`, `MD5sum`, `SHA1`, `SHA256`,
+   * `SHA512`) stay in this text; `renderDebianPackagesStanza` strips them
+   * because it writes those fields itself.
+   */
+  control: string;
+  /** The name part of the `Maintainer` field, as Gitea derives it. */
+  maintainer: string;
+  /** The `Homepage` field when Gitea's URL validation accepts it, else `''`. */
+  projectUrl: string;
+  description: string;
+  dependencies: string[];
+}
+
+export interface IDebianPackageRecord extends ILinuxPackageRecordBase {
+  format: 'debian';
+  metadata: IDebianPackageMetadata;
+}
+
+// ---------------------------------------------------------------- RPM
+
+export interface IRpmDependency {
+  name: string;
+  flags: '' | 'EQ' | 'LT' | 'GT' | 'LE' | 'GE';
+  epoch: string;
+  version: string;
+  release: string;
+}
+
+export interface IRpmFile {
+  path: string;
+  type: '' | 'dir' | 'ghost';
+  isExecutable: boolean;
+}
+
+export interface IRpmChangelog {
+  author: string;
+  date: number;
+  text: string;
+}
+
+export interface IRpmPackageMetadata {
+  epoch: string;
+  upstreamVersion: string;
+  release: string;
+  /** True for a source RPM (lead type). `architecture` stays the ARCH tag, Gitea's identity and path segment. */
+  isSourcePackage: boolean;
+  summary: string;
+  description: string;
+  license: string;
+  /** The URL tag when Gitea's URL validation accepts it, else `''`. */
+  projectUrl: string;
+  vendor: string;
+  group: string;
+  packager: string;
+  sourceRpm: string;
+  buildHost: string;
+  buildTime: number;
+  fileTime: number;
+  installedSize: number;
+  archiveSize: number;
+  provides: IRpmDependency[];
+  requires: IRpmDependency[];
+  conflicts: IRpmDependency[];
+  obsoletes: IRpmDependency[];
+  files: IRpmFile[];
+  changelogs: IRpmChangelog[];
+}
+
+export interface IRpmPackageRecord extends ILinuxPackageRecordBase {
+  format: 'rpm';
+  metadata: IRpmPackageMetadata;
+}
+
+/**
+ * One RPM errata update (updateinfo `<update>`), plain JSON. Ported from Gitea
+ * 28.2.0 `modules/packages/rpm/metadata.go`. Dates are `YYYY-MM-DD HH:MM:SS`
+ * (UTC when the codec writes them) or `null`.
+ */
+export interface IRpmUpdate {
+  id: string;
+  from: string;
+  status: string;
+  type: string;
+  version: string;
+  title: string;
+  severity: string;
+  description: string;
+  issued: string | null;
+  updated: string | null;
+  references: IRpmUpdateReference[];
+  collections: IRpmUpdateCollection[];
+}
+
+export interface IRpmUpdateReference {
+  href: string;
+  id: string;
+  title: string;
+  type: string;
+}
+
+export interface IRpmUpdateCollection {
+  short: string;
+  packages: IRpmUpdatePackage[];
+}
+
+export interface IRpmUpdatePackage {
+  name: string;
+  version: string;
+  release: string;
+  arch: string;
+  src: string;
+  fileName: string;
+}
+
+// ---------------------------------------------------------------- Arch
+
+export interface IArchPackageMetadata {
+  compression: 'zst' | 'xz' | 'gz';
+  base: string;
+  description: string;
+  /** The `.PKGINFO` url when Gitea's URL validation accepts it, else `''`. */
+  projectUrl: string;
+  licenses: string[];
+  installedSize: number;
+  buildDate: number;
+  packager: string;
+  groups: string[];
+  provides: string[];
+  replaces: string[];
+  depends: string[];
+  optDepends: string[];
+  makeDepends: string[];
+  checkDepends: string[];
+  conflicts: string[];
+  xdata: string[];
+  backup: string[];
+  files: string[];
+}
+
+export interface IArchPackageRecord extends ILinuxPackageRecordBase {
+  format: 'arch';
+  metadata: IArchPackageMetadata;
+}
+
+// ---------------------------------------------------------------- union
+
+export type TLinuxPackageRecord =
+  | IAlpinePackageRecord
+  | IDebianPackageRecord
+  | IRpmPackageRecord
+  | IArchPackageRecord;
+
+// ---------------------------------------------------------------- index files
+
+/**
+ * Write order of an index file: every `content` file is written before any
+ * `pointer` file (the signed top-level documents that name the content files).
+ */
+export type TLinuxIndexFileStage = 'content' | 'pointer';
+
+/**
+ * One file of a built index set. A builder returns the complete set of files
+ * that should exist; any previously written file not in the set is stale.
+ */
+export interface ILinuxIndexFile {
+  /** Path relative to the format root, in Gitea's layout. */
+  path: string;
+  bytes: Uint8Array;
+  /** Lowercase hex SHA-256 of `bytes`. */
+  sha256: string;
+  mediaType: string;
+  stage: TLinuxIndexFileStage;
+  /** Other paths serving the same bytes (Debian `by-hash/<ALGO>/<hex>` for every listed hash). */
+  aliases: string[];
+}