docs(api): document federation jsonld helpers

Author: skulidropek

packages/api/src/http.ts

@@ -275,6 +275,21 @@ const binaryResponse = (data: Uint8Array, contentType: string, status = 200) =>
     )
   )
 
+/**
+ * Serializes a federation JSON-LD document with the ForgeFed response content type.
+ *
+ * @param data - JSON-LD payload that satisfies the JSON.stringify serializability precondition.
+ * @param status - HTTP status code assigned to the response.
+ * @returns Effect that yields an HTTP text response containing the serialized JSON-LD document.
+ *
+ * @pure false
+ * @effect Delegates response allocation to textResponse and preserves no-store HTTP headers.
+ * @invariant successful responses always use federationJsonLdResponseContentType.
+ * @precondition data is JSON.stringify-serializable and status is a valid HTTP status code.
+ * @postcondition response body equals JSON.stringify(data) and response status equals status.
+ * @complexity O(n) time and O(n) space where n is the serialized JSON-LD payload size.
+ * @throws TypeError when data violates the JSON.stringify serializability precondition.
+ */
 const jsonLdResponse = (data: unknown, status: number) =>
   textResponse(JSON.stringify(data), federationJsonLdResponseContentType, status)
 
@@ -595,34 +610,99 @@ export const federationExchangeStatusResponse = () =>
     return yield* _(jsonResponse(makeFederationExchangeStatus(context), 200))
   }).pipe(Effect.catchAll(errorResponse))
 
+/**
+ * Builds the federation actor JSON-LD HTTP handler.
+ *
+ * @returns Effect that yields the local ActivityPub actor document response.
+ *
+ * @pure false
+ * @effect Reads HttpServerRequest, resolves federation context, renders makeFederationActorDocument, serializes with jsonLdResponse, and maps failures through errorResponse.
+ * @invariant successful responses contain the actor id derived from the resolved federation context.
+ * @precondition request headers or configured env provide a non-empty public origin.
+ * @postcondition successful responses contain a JSON-LD Person document with HTTP 200.
+ * @complexity O(1) time and O(1) space for document construction, excluding serialization size.
+ * @throws Never; failures are represented through the Effect error channel and converted by errorResponse.
+ */
 export const federationActorDocumentResponse = () =>
   Effect.gen(function*(_) {
     const request = yield* _(HttpServerRequest.HttpServerRequest)
     const context = yield* _(resolveFederationContext(request))
     return yield* _(jsonLdResponse(makeFederationActorDocument(context), 200))
   }).pipe(Effect.catchAll(errorResponse))
 
+/**
+ * Builds the federation outbox JSON-LD HTTP handler.
+ *
+ * @returns Effect that yields the local ActivityPub outbox collection response.
+ *
+ * @pure false
+ * @effect Reads HttpServerRequest, resolves federation context, renders makeFederationOutboxCollection, serializes with jsonLdResponse, and maps failures through errorResponse.
+ * @invariant successful responses contain the outbox id derived from the resolved federation context.
+ * @precondition request headers or configured env provide a non-empty public origin.
+ * @postcondition successful responses contain a JSON-LD OrderedCollection document with HTTP 200.
+ * @complexity O(1) time and O(1) space for document construction, excluding serialization size.
+ * @throws Never; failures are represented through the Effect error channel and converted by errorResponse.
+ */
 export const federationOutboxDocumentResponse = () =>
   Effect.gen(function*(_) {
     const request = yield* _(HttpServerRequest.HttpServerRequest)
     const context = yield* _(resolveFederationContext(request))
     return yield* _(jsonLdResponse(makeFederationOutboxCollection(context), 200))
   }).pipe(Effect.catchAll(errorResponse))
 
+/**
+ * Builds the federation followers JSON-LD HTTP handler.
+ *
+ * @returns Effect that yields the local ActivityPub followers collection response.
+ *
+ * @pure false
+ * @effect Reads HttpServerRequest, resolves federation context, renders makeFederationFollowersCollection, serializes with jsonLdResponse, and maps failures through errorResponse.
+ * @invariant successful responses contain the followers id derived from the resolved federation context.
+ * @precondition request headers or configured env provide a non-empty public origin.
+ * @postcondition successful responses contain a JSON-LD OrderedCollection document with HTTP 200.
+ * @complexity O(1) time and O(1) space for document construction, excluding serialization size.
+ * @throws Never; failures are represented through the Effect error channel and converted by errorResponse.
+ */
 export const federationFollowersDocumentResponse = () =>
   Effect.gen(function*(_) {
     const request = yield* _(HttpServerRequest.HttpServerRequest)
     const context = yield* _(resolveFederationContext(request))
     return yield* _(jsonLdResponse(makeFederationFollowersCollection(context), 200))
   }).pipe(Effect.catchAll(errorResponse))
 
+/**
+ * Builds the federation following JSON-LD HTTP handler.
+ *
+ * @returns Effect that yields the local ActivityPub following collection response.
+ *
+ * @pure false
+ * @effect Reads HttpServerRequest, resolves federation context, renders makeFederationFollowingCollection, serializes with jsonLdResponse, and maps failures through errorResponse.
+ * @invariant successful responses contain the following id derived from the resolved federation context.
+ * @precondition request headers or configured env provide a non-empty public origin.
+ * @postcondition successful responses contain a JSON-LD OrderedCollection document with HTTP 200.
+ * @complexity O(1) time and O(1) space for document construction, excluding serialization size.
+ * @throws Never; failures are represented through the Effect error channel and converted by errorResponse.
+ */
 export const federationFollowingDocumentResponse = () =>
   Effect.gen(function*(_) {
     const request = yield* _(HttpServerRequest.HttpServerRequest)
     const context = yield* _(resolveFederationContext(request))
     return yield* _(jsonLdResponse(makeFederationFollowingCollection(context), 200))
   }).pipe(Effect.catchAll(errorResponse))
 
+/**
+ * Builds the federation liked JSON-LD HTTP handler.
+ *
+ * @returns Effect that yields the local ActivityPub liked collection response.
+ *
+ * @pure false
+ * @effect Reads HttpServerRequest, resolves federation context, renders makeFederationLikedCollection, serializes with jsonLdResponse, and maps failures through errorResponse.
+ * @invariant successful responses contain the liked collection id derived from the resolved federation context.
+ * @precondition request headers or configured env provide a non-empty public origin.
+ * @postcondition successful responses contain a JSON-LD OrderedCollection document with HTTP 200.
+ * @complexity O(1) time and O(1) space for document construction, excluding serialization size.
+ * @throws Never; failures are represented through the Effect error channel and converted by errorResponse.
+ */
 export const federationLikedDocumentResponse = () =>
   Effect.gen(function*(_) {
     const request = yield* _(HttpServerRequest.HttpServerRequest)

packages/api/src/services/federation.ts

@@ -125,6 +125,20 @@ const isRecord = (value: unknown): value is JsonRecord =>
 const asRecord = (value: unknown): JsonRecord | null =>
   isRecord(value) ? value : null
 
+/**
+ * Extracts string JSON-LD context entries from a boundary value.
+ *
+ * @param value - Unknown ActivityPub or ForgeFed @context field value.
+ * @returns Immutable set of string context identifiers; unsupported shapes produce an empty set.
+ *
+ * @pure true
+ * @effect none
+ * @invariant every returned element is a string from value, and no non-string value is introduced.
+ * @precondition value may be any boundary value.
+ * @postcondition result contains value iff value is a string; result contains each string item iff value is an array.
+ * @complexity O(n) time and O(n) space where n is array length, or O(1) for non-array values.
+ * @throws Never.
+ */
 const jsonLdContextValues = (value: unknown): ReadonlySet<string> => {
   if (typeof value === "string") {
     return new Set([value])
@@ -135,11 +149,41 @@ const jsonLdContextValues = (value: unknown): ReadonlySet<string> => {
   return new Set(value.filter((item): item is string => typeof item === "string"))
 }
 
+/**
+ * Checks whether a JSON-LD context value contains both required federation contexts.
+ *
+ * @param value - Unknown @context value to validate.
+ * @returns True when ActivityStreams and ForgeFed context identifiers are both present.
+ *
+ * @pure true
+ * @effect none
+ * @invariant result is true iff jsonLdContextValues(value) contains both required context URIs.
+ * @precondition value may be any boundary value.
+ * @postcondition result does not mutate or normalize the input value.
+ * @complexity O(n) time and O(n) space where n is array length, or O(1) for non-array values.
+ * @throws Never.
+ */
 const hasFederationJsonLdContext = (value: unknown): boolean => {
   const contexts = jsonLdContextValues(value)
   return contexts.has(activityStreamsJsonLdContext) && contexts.has(forgeFedJsonLdContext)
 }
 
+/**
+ * Requires a top-level federation document to declare or inherit valid JSON-LD contexts.
+ *
+ * @param payload - Parsed JSON object representing the federation document being checked.
+ * @param label - Human-readable document label used in the typed validation error.
+ * @param inheritedContext - Optional parent @context accepted when payload omits its own @context.
+ * @returns Effect that succeeds when ActivityStreams and ForgeFed contexts are available.
+ *
+ * @pure false
+ * @effect Constructs a typed ApiBadRequestError in the Effect error channel when validation fails.
+ * @invariant success implies payload.@context or inheritedContext contains ActivityStreams and ForgeFed contexts.
+ * @precondition payload is a decoded JSON object at the federation boundary.
+ * @postcondition failure message identifies the invalid document label.
+ * @complexity O(n) time and O(n) space where n is the checked context array length.
+ * @throws Never; validation failures are represented as ApiBadRequestError.
+ */
 const requireFederationJsonLdContext = (
   payload: JsonRecord,
   label: string,
@@ -159,6 +203,22 @@ const requireFederationJsonLdContext = (
     )
 }
 
+/**
+ * Requires nested federation objects to use valid JSON-LD context only when they override inheritance.
+ *
+ * @param payload - Parsed nested JSON object being checked.
+ * @param label - Human-readable nested object label used in the typed validation error.
+ * @param inheritedContext - Parent @context available to nested objects that omit @context.
+ * @returns Effect that succeeds when the nested object inherits context or declares a valid override.
+ *
+ * @pure false
+ * @effect Delegates invalid explicit context failures to requireFederationJsonLdContext.
+ * @invariant missing nested @context is accepted, explicit nested @context must contain ActivityStreams and ForgeFed contexts.
+ * @precondition payload is a decoded nested JSON object and inheritedContext is the parent document context.
+ * @postcondition success preserves JSON-LD inheritance semantics for nested ForgeFed objects.
+ * @complexity O(n) time and O(n) space where n is the explicit nested context array length, or O(1) if omitted.
+ * @throws Never; validation failures are represented as ApiBadRequestError.
+ */
 const requireNestedFederationJsonLdContext = (
   payload: JsonRecord,
   label: string,