@fin.cx/opendata 3.5.1 → 4.0.0

package/ts/handelsregister/classes.portalsession.ts

@@ -0,0 +1,191 @@
+import { HandelsregisterError, type THandelsregisterStep } from './classes.handelsregistererror.js';
+
+export interface IPortalSessionSettings {
+  portalUrl: string;
+  userAgent: string;
+  requestTimeoutMs: number;
+  maxResponseBytes: number;
+  signal?: AbortSignal;
+}
+
+/** what the caller of a session learns about the progress of its call */
+export interface ICallProgress {
+  step?: THandelsregisterStep;
+  /** counted requests sent so far */
+  countedRequests: number;
+}
+
+export interface IPortalResponse {
+  /** the URL that answered, after redirects */
+  url: string;
+  contentType: string;
+  body: Uint8Array;
+}
+
+const redirectStatuses = new Set([301, 302, 303]);
+const maxRedirects = 3;
+
+/**
+ * One visit to the register portal: a cookie jar, the fixed language and a limit for every
+ * request. It lives for one call of the client and is dropped afterwards, so nothing is shared
+ * between calls or callers.
+ */
+export class PortalSession {
+  private cookies = new Map<string, string>();
+  private origin: string;
+  /** the signal of the request in flight */
+  private currentSignal?: AbortSignal;
+
+  constructor(private settings: IPortalSessionSettings, private progress: ICallProgress) {
+    this.origin = new URL(settings.portalUrl).origin;
+  }
+
+  /** resolves a path or a relative action against the portal or a page */
+  public resolve(targetArg: string, baseArg: string = this.origin): string {
+    return new URL(targetArg, baseArg).toString();
+  }
+
+  public async get(urlArg: string): Promise<IPortalResponse> {
+    return this.request('GET', urlArg);
+  }
+
+  /** submits a form as `application/x-www-form-urlencoded` */
+  public async post(urlArg: string, fieldsArg: Array<[string, string]>): Promise<IPortalResponse> {
+    return this.request('POST', urlArg, new URLSearchParams(fieldsArg).toString());
+  }
+
+  private fail(
+    codeArg: 'aborted' | 'timeout' | 'unreachable' | 'refused' | 'too_large' | 'unexpected_response',
+    messageArg: string,
+    extraArg: { status?: number; cause?: unknown } = {}
+  ): HandelsregisterError {
+    return new HandelsregisterError(codeArg, messageArg, {
+      ...extraArg,
+      step: this.progress.step,
+      countedRequests: this.progress.countedRequests,
+    });
+  }
+
+  private async request(methodArg: 'GET' | 'POST', urlArg: string, bodyArg?: string): Promise<IPortalResponse> {
+    let method = methodArg;
+    let url = urlArg;
+    let body = bodyArg;
+    for (let redirects = 0; ; redirects++) {
+      if (new URL(url).origin !== this.origin) {
+        throw this.fail('unexpected_response', 'The portal pointed to another site.');
+      }
+      const response = await this.send(method, url, body);
+      if (redirectStatuses.has(response.status)) {
+        const location = response.headers.get('location');
+        await response.body?.cancel();
+        if (!location || redirects >= maxRedirects) {
+          throw this.fail('unexpected_response', 'The portal redirected in a way this version does not follow.');
+        }
+        url = new URL(location, url).toString();
+        method = 'GET';
+        body = undefined;
+        continue;
+      }
+      if (response.status !== 200) {
+        await response.body?.cancel();
+        throw this.fail('refused', `The register portal answered with HTTP status ${response.status}.`, {
+          status: response.status,
+        });
+      }
+      return {
+        url,
+        contentType: response.headers.get('content-type') ?? '',
+        body: await this.readBody(response),
+      };
+    }
+  }
+
+  private async send(methodArg: 'GET' | 'POST', urlArg: string, bodyArg?: string): Promise<Response> {
+    if (this.settings.signal?.aborted) {
+      throw this.fail('aborted', 'The call was aborted.', { cause: this.settings.signal.reason });
+    }
+    const headers: Record<string, string> = {
+      'User-Agent': this.settings.userAgent,
+      Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+      'Accept-Language': 'de-DE,de;q=0.9',
+    };
+    if (this.cookies.size > 0) {
+      headers.Cookie = [...this.cookies].map(([name, value]) => `${name}=${value}`).join('; ');
+    }
+    if (bodyArg !== undefined) {
+      headers['Content-Type'] = 'application/x-www-form-urlencoded';
+    }
+    let response: Response;
+    try {
+      response = await fetch(urlArg, {
+        method: methodArg,
+        headers,
+        body: bodyArg,
+        redirect: 'manual',
+        signal: this.requestSignal(),
+      });
+    } catch (error) {
+      throw this.failureOf(error);
+    }
+    for (const cookie of response.headers.getSetCookie()) {
+      const pair = cookie.split(';', 1)[0];
+      const separator = pair.indexOf('=');
+      if (separator > 0) {
+        this.cookies.set(pair.slice(0, separator).trim(), pair.slice(separator + 1).trim());
+      }
+    }
+    return response;
+  }
+
+  /** a signal for one request: the caller's signal and the request's own time limit */
+  private requestSignal(): AbortSignal {
+    const timeout = AbortSignal.timeout(this.settings.requestTimeoutMs);
+    this.currentSignal = this.settings.signal ? AbortSignal.any([this.settings.signal, timeout]) : timeout;
+    return this.currentSignal;
+  }
+
+  private failureOf(errorArg: unknown): HandelsregisterError {
+    if (errorArg instanceof HandelsregisterError) {
+      return errorArg;
+    }
+    if (this.settings.signal?.aborted) {
+      return this.fail('aborted', 'The call was aborted.', { cause: this.settings.signal.reason });
+    }
+    if (this.currentSignal?.aborted) {
+      return this.fail('timeout', 'The register portal did not answer in time.', { cause: errorArg });
+    }
+    return this.fail('unreachable', 'The register portal could not be reached.', { cause: errorArg });
+  }
+
+  private async readBody(responseArg: Response): Promise<Uint8Array> {
+    if (!responseArg.body) {
+      return new Uint8Array(0);
+    }
+    const reader = responseArg.body.getReader();
+    const chunks: Uint8Array[] = [];
+    let total = 0;
+    try {
+      for (;;) {
+        const chunk = await reader.read();
+        if (chunk.done) {
+          break;
+        }
+        total += chunk.value.byteLength;
+        if (total > this.settings.maxResponseBytes) {
+          await reader.cancel();
+          throw this.fail('too_large', 'An answer of the register portal exceeded the size limit.');
+        }
+        chunks.push(chunk.value);
+      }
+    } catch (error) {
+      throw this.failureOf(error);
+    }
+    const body = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+      body.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    return body;
+  }
+}

package/ts/handelsregister/classes.slidingwindowgate.ts

@@ -0,0 +1,74 @@
+import { HandelsregisterError } from './classes.handelsregistererror.js';
+import { portalRequestsPerHour } from './constants.js';
+import type { IRegisterCountedRequest, IRegisterRequestGate } from './interfaces.js';
+
+export interface ISlidingWindowGateOptions {
+  /** requests allowed within one window; default 60, the portal's limit */
+  limit?: number;
+  /** length of the window; default one hour */
+  windowMs?: number;
+  /** clock; default `Date.now` */
+  now?: () => number;
+}
+
+/**
+ * Holds the portal's limit of 60 searches and retrievals per hour over a sliding window: a request
+ * is allowed when fewer than `limit` requests were allowed in the `windowMs` before it. A refusal is
+ * a `HandelsregisterError` with the code `rate_limited` and `retryAt`, the moment the oldest request
+ * leaves the window.
+ *
+ * The window lives in this object, so it counts for one process. Share one gate between every
+ * client of the installation that reaches the portal from the same address.
+ */
+export class SlidingWindowGate implements IRegisterRequestGate {
+  public readonly limit: number;
+  public readonly windowMs: number;
+  private now: () => number;
+  /** epoch ms of the allowed requests still inside the window, oldest first */
+  private allowed: number[] = [];
+
+  constructor(optionsArg: ISlidingWindowGateOptions = {}) {
+    this.limit = optionsArg.limit ?? portalRequestsPerHour;
+    this.windowMs = optionsArg.windowMs ?? 60 * 60 * 1000;
+    this.now = optionsArg.now ?? Date.now;
+    if (!Number.isInteger(this.limit) || this.limit < 1) {
+      throw new RangeError('limit must be a positive integer');
+    }
+    if (!Number.isFinite(this.windowMs) || this.windowMs <= 0) {
+      throw new RangeError('windowMs must be positive');
+    }
+  }
+
+  private prune(nowArg: number): void {
+    while (this.allowed.length > 0 && this.allowed[0] <= nowArg - this.windowMs) {
+      this.allowed.shift();
+    }
+  }
+
+  public async acquire(_requestArg: IRegisterCountedRequest): Promise<void> {
+    const now = this.now();
+    this.prune(now);
+    if (this.allowed.length >= this.limit) {
+      const retryAt = this.allowed[0] + this.windowMs;
+      throw new HandelsregisterError(
+        'rate_limited',
+        `The limit of ${this.limit} register requests per window is used up.`,
+        { retryAt }
+      );
+    }
+    this.allowed.push(now);
+  }
+
+  /** requests still allowed now */
+  public remaining(): number {
+    this.prune(this.now());
+    return this.limit - this.allowed.length;
+  }
+
+  /** epoch ms from which the next request is allowed; now, when one is allowed already */
+  public nextAllowedAt(): number {
+    const now = this.now();
+    this.prune(now);
+    return this.allowed.length < this.limit ? now : this.allowed[this.allowed.length - this.limit] + this.windowMs;
+  }
+}

package/ts/handelsregister/constants.ts

@@ -0,0 +1,30 @@
+import type { IStructuredContentNotice, TRegisterDocument, TRegisterType } from './interfaces.js';
+
+export const registerTypes: readonly TRegisterType[] = ['HRA', 'HRB', 'GnR', 'PR', 'VR', 'GsR'];
+
+export const registerDocuments: readonly TRegisterDocument[] = ['AD', 'CD', 'HD', 'DK', 'UT', 'VÖ', 'SI'];
+
+/** the portal's note on its structured register content, from its start page (2026-09-23) */
+export const structuredContentNotice: IStructuredContentNotice = {
+  de:
+    'Soweit in den Ländern strukturierte Informationen zum Abruf zur Verfügung gestellt werden, handelt es sich ' +
+    'um einen unverbindlichen Service. Der Inhalt kann in speziellen Fällen vom Inhalt des aktuellen Abdrucks ' +
+    'abweichen und diesen ggf. nicht vollständig wiedergeben.',
+  en:
+    'Where the federal states provide structured information for retrieval, this is a non-binding service. In ' +
+    'special cases its content can differ from the current printout and may not reproduce it completely.',
+};
+
+/** the portal's maximum number of hits for one search */
+export const portalMaximumHits = 100;
+
+export const defaultPortalUrl = 'https://www.handelsregister.de';
+
+export const defaultUserAgent = '@fin.cx/opendata (+https://code.foss.global/fin.cx/opendata)';
+
+export const defaultRequestTimeoutMs = 20_000;
+
+export const defaultMaxResponseBytes = 5 * 1024 * 1024;
+
+/** the portal's terms: at most 60 searches or retrievals of entities per hour */
+export const portalRequestsPerHour = 60;