feat(api): align federation objects with konrad notes

Author: skulidropek

packages/api/README.md

@@ -22,12 +22,19 @@ Env:
 - `DOCKER_GIT_API_PORT` (default: `3334`)
 - `DOCKER_GIT_PROJECTS_ROOT` (default: `~/.docker-git`)
 - `DOCKER_GIT_API_LOG_LEVEL` (default: `info`)
+- `DOCKER_GIT_FEDERATION_PUBLIC_ORIGIN` (optional public ActivityPub domain, e.g. `https://social.my-domain.tld`)
+- `DOCKER_GIT_FEDERATION_ACTOR` (default: `docker-git`)
 
 ## Endpoints (v1)
 
 - `GET /v1/health`
 - `POST /v1/federation/inbox` (ForgeFed `Ticket` / `Offer(Ticket)`, ActivityPub `Accept` / `Reject`)
 - `GET /v1/federation/issues`
+- `GET /v1/federation/actor` (ActivityPub `Person`)
+- `GET /v1/federation/outbox`
+- `GET /v1/federation/followers`
+- `GET /v1/federation/following`
+- `GET /v1/federation/liked`
 - `POST /v1/federation/follows` (create ActivityPub `Follow` activity for task-feed subscription)
 - `GET /v1/federation/follows`
 - `GET /v1/projects`
@@ -54,11 +61,13 @@ curl -s http://localhost:3334/v1/projects
 curl -s -X POST http://localhost:3334/v1/projects/<projectId>/up
 curl -s -N http://localhost:3334/v1/projects/<projectId>/events
 
+curl -s http://localhost:3334/v1/federation/actor
+
 curl -s -X POST http://localhost:3334/v1/federation/follows \
   -H 'content-type: application/json' \
-  -d '{"actor":"https://dev.example/users/bot","object":"https://tracker.example/issues/followers"}'
+  -d '{"domain":"social.my-domain.tld","object":"https://social.my-domain.tld/issues/followers"}'
 
 curl -s -X POST http://localhost:3334/v1/federation/inbox \
   -H 'content-type: application/json' \
-  -d '{"type":"Offer","target":"https://tracker.example/issues","object":{"type":"Ticket","id":"https://tracker.example/issues/42","attributedTo":"https://origin.example/users/alice","summary":"Title","content":"Body"}}'
+  -d '{"@context":["https://www.w3.org/ns/activitystreams","https://forgefed.org/ns"],"id":"https://social.my-domain.tld/offers/42","type":"Offer","target":"https://social.my-domain.tld/issues","object":{"type":"Ticket","id":"https://social.my-domain.tld/issues/42","attributedTo":"https://origin.my-domain.tld/users/alice","summary":"Title","content":"Body"}}'
 ```

packages/api/src/api/contracts.ts

@@ -126,8 +126,9 @@ export type FederationIssueRecord = {
 }
 
 export type CreateFollowRequest = {
-  readonly actor: string
+  readonly actor?: string | undefined
   readonly object: string
+  readonly domain?: string | undefined
   readonly inbox?: string | undefined
   readonly to?: ReadonlyArray<string> | undefined
   readonly capability?: string | undefined
@@ -145,6 +146,28 @@ export type ActivityPubFollowActivity = {
   readonly capability?: string | undefined
 }
 
+export type ActivityPubPerson = {
+  readonly "@context": "https://www.w3.org/ns/activitystreams"
+  readonly type: "Person"
+  readonly id: string
+  readonly name: string
+  readonly preferredUsername: string
+  readonly summary: string
+  readonly inbox: string
+  readonly outbox: string
+  readonly followers: string
+  readonly following: string
+  readonly liked: string
+}
+
+export type ActivityPubOrderedCollection = {
+  readonly "@context": "https://www.w3.org/ns/activitystreams"
+  readonly type: "OrderedCollection"
+  readonly id: string
+  readonly totalItems: number
+  readonly orderedItems: ReadonlyArray<unknown>
+}
+
 export type FollowSubscription = {
   readonly id: string
   readonly activityId: string

packages/api/src/api/schema.ts

@@ -48,8 +48,9 @@ export const CreateAgentRequestSchema = Schema.Struct({
 })
 
 export const CreateFollowRequestSchema = Schema.Struct({
-  actor: Schema.String,
+  actor: OptionalString,
   object: Schema.String,
+  domain: OptionalString,
   inbox: OptionalString,
   to: Schema.optional(Schema.Array(Schema.String)),
   capability: OptionalString

packages/api/src/http.ts

@@ -18,7 +18,13 @@ import {
   createFollowSubscription,
   ingestFederationInbox,
   listFederationIssues,
-  listFollowSubscriptions
+  listFollowSubscriptions,
+  makeFederationActorDocument,
+  makeFederationContext,
+  makeFederationFollowersCollection,
+  makeFederationFollowingCollection,
+  makeFederationLikedCollection,
+  makeFederationOutboxCollection
 } from "./services/federation.js"
 import {
   createProjectFromRequest,
@@ -117,6 +123,55 @@ const readCreateProjectRequest = () => HttpServerRequest.schemaBodyJson(CreatePr
 const readCreateFollowRequest = () => HttpServerRequest.schemaBodyJson(CreateFollowRequestSchema)
 const readInboxPayload = () => HttpServerRequest.schemaBodyJson(Schema.Unknown)
 
+const configuredFederationPublicOrigin =
+  process.env["DOCKER_GIT_FEDERATION_PUBLIC_ORIGIN"] ??
+  process.env["DOCKER_GIT_API_PUBLIC_URL"]
+
+const configuredFederationActorUsername =
+  process.env["DOCKER_GIT_FEDERATION_ACTOR"] ?? "docker-git"
+
+const readHeader = (
+  request: HttpServerRequest.HttpServerRequest,
+  key: string
+): string | undefined => {
+  const value = request.headers[key.toLowerCase()]
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined
+}
+
+const firstCommaValue = (value: string | undefined): string | undefined => {
+  if (value === undefined) {
+    return undefined
+  }
+  const first = value.split(",")[0]?.trim()
+  return first && first.length > 0 ? first : undefined
+}
+
+const resolveRequestOrigin = (request: HttpServerRequest.HttpServerRequest): string => {
+  const forwardedHost = firstCommaValue(readHeader(request, "x-forwarded-host"))
+  const host = forwardedHost ?? readHeader(request, "host")
+  const proto = firstCommaValue(readHeader(request, "x-forwarded-proto")) ?? "http"
+  if (host === undefined || host.length === 0) {
+    return "http://localhost:3334"
+  }
+  return `${proto}://${host}`
+}
+
+const resolveFederationContext = (
+  request: HttpServerRequest.HttpServerRequest,
+  requestedDomain?: string | undefined
+) => {
+  const fromBody = requestedDomain?.trim()
+  const publicOrigin =
+    fromBody && fromBody.length > 0
+      ? fromBody
+      : configuredFederationPublicOrigin ?? resolveRequestOrigin(request)
+
+  return makeFederationContext({
+    publicOrigin,
+    actorUsername: configuredFederationActorUsername
+  })
+}
+
 export const makeRouter = () => {
   const base = HttpRouter.empty.pipe(
     HttpRouter.get("/", textResponse(uiHtml, "text/html; charset=utf-8", 200)),
@@ -130,11 +185,53 @@ export const makeRouter = () => {
         Effect.catchAll(errorResponse)
       )
     ),
+    HttpRouter.get(
+      "/v1/federation/actor",
+      Effect.gen(function*(_) {
+        const request = yield* _(HttpServerRequest.HttpServerRequest)
+        const context = yield* _(resolveFederationContext(request))
+        return yield* _(jsonResponse(makeFederationActorDocument(context), 200))
+      }).pipe(Effect.catchAll(errorResponse))
+    ),
+    HttpRouter.get(
+      "/v1/federation/outbox",
+      Effect.gen(function*(_) {
+        const request = yield* _(HttpServerRequest.HttpServerRequest)
+        const context = yield* _(resolveFederationContext(request))
+        return yield* _(jsonResponse(makeFederationOutboxCollection(context), 200))
+      }).pipe(Effect.catchAll(errorResponse))
+    ),
+    HttpRouter.get(
+      "/v1/federation/followers",
+      Effect.gen(function*(_) {
+        const request = yield* _(HttpServerRequest.HttpServerRequest)
+        const context = yield* _(resolveFederationContext(request))
+        return yield* _(jsonResponse(makeFederationFollowersCollection(context), 200))
+      }).pipe(Effect.catchAll(errorResponse))
+    ),
+    HttpRouter.get(
+      "/v1/federation/following",
+      Effect.gen(function*(_) {
+        const request = yield* _(HttpServerRequest.HttpServerRequest)
+        const context = yield* _(resolveFederationContext(request))
+        return yield* _(jsonResponse(makeFederationFollowingCollection(context), 200))
+      }).pipe(Effect.catchAll(errorResponse))
+    ),
+    HttpRouter.get(
+      "/v1/federation/liked",
+      Effect.gen(function*(_) {
+        const request = yield* _(HttpServerRequest.HttpServerRequest)
+        const context = yield* _(resolveFederationContext(request))
+        return yield* _(jsonResponse(makeFederationLikedCollection(context), 200))
+      }).pipe(Effect.catchAll(errorResponse))
+    ),
     HttpRouter.post(
       "/v1/federation/follows",
       Effect.gen(function*(_) {
-        const request = yield* _(readCreateFollowRequest())
-        const created = yield* _(createFollowSubscription(request))
+        const requestBody = yield* _(readCreateFollowRequest())
+        const request = yield* _(HttpServerRequest.HttpServerRequest)
+        const context = yield* _(resolveFederationContext(request, requestBody.domain))
+        const created = yield* _(createFollowSubscription(requestBody, context))
         return yield* _(jsonResponse(created, 201))
       }).pipe(Effect.catchAll(errorResponse))
     ),
@@ -152,7 +249,10 @@ export const makeRouter = () => {
         const result = yield* _(ingestFederationInbox(payload))
         return yield* _(jsonResponse({ result }, 202))
       }).pipe(Effect.catchAll(errorResponse))
-    ),
+    )
+  )
+
+  const withProjects = base.pipe(
     HttpRouter.get(
       "/v1/projects",
       listProjects().pipe(
@@ -226,7 +326,7 @@ export const makeRouter = () => {
     )
   )
 
-  const withAgents = base.pipe(
+  const withAgents = withProjects.pipe(
     HttpRouter.post(
       "/v1/projects/:projectId/agents",
       Effect.gen(function*(_) {