@fedify/fedify 2.4.0-dev.1567 → 2.4.0-dev.1570

package/dist/{mq-D-nlpY04.d.ts → metrics-CoUJLQhZ.d.cts}

@@ -1,4 +1,7 @@
 /// <reference lib="esnext.temporal" />
+import { DocumentLoader } from "@fedify/vocab-runtime";
+import { MeterProvider } from "@opentelemetry/api";
+
 //#region src/federation/mq.d.ts
 /**
 * Additional options for enqueuing a message in a queue.
@@ -24,6 +27,19 @@ interface MessageQueueEnqueueOptions {
   * @since 2.0.0
   */
   readonly orderingKey?: string;
+  /**
+  * An optional key requesting at-most-once enqueue semantics for messages
+  * that share it.  A backend that declares
+  * {@link MessageQueue.nativeDeduplication} `true` owns the check: a message
+  * whose `deduplicationKey` was already seen within the backend's
+  * deduplication window is dropped instead of enqueued.  Backends without
+  * native deduplication ignore this field; Fedify performs its own
+  * best-effort deduplication before reaching them on the paths that support
+  * it.
+  *
+  * @since 2.4.0
+  */
+  readonly deduplicationKey?: string;
 }
 /**
 * Additional options for listening to a message queue.
@@ -81,6 +97,17 @@ interface MessageQueue {
   */
   readonly nativeRetrial?: boolean;
   /**
+  * Whether the message queue backend deduplicates messages that share a
+  * {@link MessageQueueEnqueueOptions.deduplicationKey} natively.  When `true`,
+  * Fedify forwards the `deduplicationKey` and relies on the backend to drop
+  * duplicates; when `false` or omitted, Fedify applies its own best-effort
+  * key–value deduplication on the paths that request it.
+  *
+  * @default `false`
+  * @since 2.4.0
+  */
+  readonly nativeDeduplication?: boolean;
+  /**
   * Enqueues a message in the queue.
   * @param message The message to enqueue.
   * @param options Additional options for enqueuing the message.
@@ -141,6 +168,11 @@ declare class InProcessMessageQueue implements MessageQueue {
   */
   readonly nativeRetrial = false;
   /**
+  * In-process message queue does not deduplicate messages natively.
+  * @since 2.4.0
+  */
+  readonly nativeDeduplication = false;
+  /**
   * Constructs a new {@link InProcessMessageQueue} with the given options.
   * @param options Additional options for the in-process message queue.
   */
@@ -189,6 +221,11 @@ declare class ParallelMessageQueue implements MessageQueue {
   * @since 1.7.0
   */
   readonly nativeRetrial?: boolean;
+  /**
+  * Inherits the native deduplication capability from the wrapped queue.
+  * @since 2.4.0
+  */
+  readonly nativeDeduplication?: boolean;
   readonly getDepth?: () => Promise<MessageQueueDepth>;
   /**
   * Constructs a new {@link ParallelMessageQueue} with the given queue and
@@ -205,4 +242,35 @@ declare class ParallelMessageQueue implements MessageQueue {
   listen(handler: (message: any) => Promise<void> | void, options?: MessageQueueListenOptions): Promise<void>;
 }
 //#endregion
-export { MessageQueueEnqueueOptions as a, MessageQueueDepth as i, InProcessMessageQueueOptions as n, MessageQueueListenOptions as o, MessageQueue as r, ParallelMessageQueue as s, InProcessMessageQueue as t };
+//#region src/federation/metrics.d.ts
+/**
+* The kind of remote ActivityPub lookup, recorded as
+* `activitypub.lookup.kind` on the public-key lookup and remote document
+* fetch metric families.
+*
+*  -  `public_key`: a public key lookup performed by `fetchKey` /
+*     `fetchKeyDetailed` (always recorded on `activitypub.key.lookup*`).
+*  -  `actor`: a document fetch whose resolved value is an Actor.  The
+*     bucket exists in the taxonomy for future actor-aware call sites;
+*     today, actor documents fetched through Fedify's generic document
+*     loader are still classified as `object` because the kind is decided
+*     at the loader boundary, before the response is parsed.
+*  -  `object`: a generic ActivityPub object fetch through Fedify's
+*     document loader.  This is the default classification for
+*     `documentLoader` invocations that do not match a more specific
+*     bucket.
+*  -  `context`: a JSON-LD `@context` document fetch through Fedify's
+*     context loader.
+*  -  `other`: a fetch that does not fit any of the above classifications.
+* @since 2.3.0
+*/
+type LookupKind = "public_key" | "actor" | "object" | "context" | "other";
+/**
+* The {@link LookupKind} values that can appear on remote document fetch
+* metrics.  `public_key` lookups are reported on the
+* `activitypub.key.lookup` metric family instead, so it is excluded here.
+* @since 2.3.0
+*/
+type DocumentFetchKind = Exclude<LookupKind, "public_key">;
+//#endregion
+export { MessageQueueDepth as a, ParallelMessageQueue as c, MessageQueue as i, InProcessMessageQueue as n, MessageQueueEnqueueOptions as o, InProcessMessageQueueOptions as r, MessageQueueListenOptions as s, DocumentFetchKind as t };

package/dist/{mq-D8uSFzxe.d.cts → metrics-Dc4jR-IC.d.ts}

@@ -1,4 +1,7 @@
 /// <reference lib="esnext.temporal" />
+import { MeterProvider } from "@opentelemetry/api";
+import { DocumentLoader } from "@fedify/vocab-runtime";
+
 //#region src/federation/mq.d.ts
 /**
 * Additional options for enqueuing a message in a queue.
@@ -24,6 +27,19 @@ interface MessageQueueEnqueueOptions {
   * @since 2.0.0
   */
   readonly orderingKey?: string;
+  /**
+  * An optional key requesting at-most-once enqueue semantics for messages
+  * that share it.  A backend that declares
+  * {@link MessageQueue.nativeDeduplication} `true` owns the check: a message
+  * whose `deduplicationKey` was already seen within the backend's
+  * deduplication window is dropped instead of enqueued.  Backends without
+  * native deduplication ignore this field; Fedify performs its own
+  * best-effort deduplication before reaching them on the paths that support
+  * it.
+  *
+  * @since 2.4.0
+  */
+  readonly deduplicationKey?: string;
 }
 /**
 * Additional options for listening to a message queue.
@@ -81,6 +97,17 @@ interface MessageQueue {
   */
   readonly nativeRetrial?: boolean;
   /**
+  * Whether the message queue backend deduplicates messages that share a
+  * {@link MessageQueueEnqueueOptions.deduplicationKey} natively.  When `true`,
+  * Fedify forwards the `deduplicationKey` and relies on the backend to drop
+  * duplicates; when `false` or omitted, Fedify applies its own best-effort
+  * key–value deduplication on the paths that request it.
+  *
+  * @default `false`
+  * @since 2.4.0
+  */
+  readonly nativeDeduplication?: boolean;
+  /**
   * Enqueues a message in the queue.
   * @param message The message to enqueue.
   * @param options Additional options for enqueuing the message.
@@ -141,6 +168,11 @@ declare class InProcessMessageQueue implements MessageQueue {
   */
   readonly nativeRetrial = false;
   /**
+  * In-process message queue does not deduplicate messages natively.
+  * @since 2.4.0
+  */
+  readonly nativeDeduplication = false;
+  /**
   * Constructs a new {@link InProcessMessageQueue} with the given options.
   * @param options Additional options for the in-process message queue.
   */
@@ -189,6 +221,11 @@ declare class ParallelMessageQueue implements MessageQueue {
   * @since 1.7.0
   */
   readonly nativeRetrial?: boolean;
+  /**
+  * Inherits the native deduplication capability from the wrapped queue.
+  * @since 2.4.0
+  */
+  readonly nativeDeduplication?: boolean;
   readonly getDepth?: () => Promise<MessageQueueDepth>;
   /**
   * Constructs a new {@link ParallelMessageQueue} with the given queue and
@@ -205,4 +242,35 @@ declare class ParallelMessageQueue implements MessageQueue {
   listen(handler: (message: any) => Promise<void> | void, options?: MessageQueueListenOptions): Promise<void>;
 }
 //#endregion
-export { MessageQueueEnqueueOptions as a, MessageQueueDepth as i, InProcessMessageQueueOptions as n, MessageQueueListenOptions as o, MessageQueue as r, ParallelMessageQueue as s, InProcessMessageQueue as t };
+//#region src/federation/metrics.d.ts
+/**
+* The kind of remote ActivityPub lookup, recorded as
+* `activitypub.lookup.kind` on the public-key lookup and remote document
+* fetch metric families.
+*
+*  -  `public_key`: a public key lookup performed by `fetchKey` /
+*     `fetchKeyDetailed` (always recorded on `activitypub.key.lookup*`).
+*  -  `actor`: a document fetch whose resolved value is an Actor.  The
+*     bucket exists in the taxonomy for future actor-aware call sites;
+*     today, actor documents fetched through Fedify's generic document
+*     loader are still classified as `object` because the kind is decided
+*     at the loader boundary, before the response is parsed.
+*  -  `object`: a generic ActivityPub object fetch through Fedify's
+*     document loader.  This is the default classification for
+*     `documentLoader` invocations that do not match a more specific
+*     bucket.
+*  -  `context`: a JSON-LD `@context` document fetch through Fedify's
+*     context loader.
+*  -  `other`: a fetch that does not fit any of the above classifications.
+* @since 2.3.0
+*/
+type LookupKind = "public_key" | "actor" | "object" | "context" | "other";
+/**
+* The {@link LookupKind} values that can appear on remote document fetch
+* metrics.  `public_key` lookups are reported on the
+* `activitypub.key.lookup` metric family instead, so it is excluded here.
+* @since 2.3.0
+*/
+type DocumentFetchKind = Exclude<LookupKind, "public_key">;
+//#endregion
+export { MessageQueueDepth as a, ParallelMessageQueue as c, MessageQueue as i, InProcessMessageQueue as n, MessageQueueEnqueueOptions as o, InProcessMessageQueueOptions as r, MessageQueueListenOptions as s, DocumentFetchKind as t };