@electric-ax/agents-server 0.3.0

package/src/routing/entities-router.ts

@@ -0,0 +1,484 @@
+/**
+ * HTTP routes for Electric Agents entity management.
+ */
+
+import { Type, type Static } from '@sinclair/typebox'
+import { Router, json, status } from 'itty-router'
+import { apiError } from '../electric-agents-http.js'
+import { dispatchPolicySchema } from '../dispatch-policy-schema.js'
+import {
+  ErrCodeNotFound,
+  ErrCodeUnknownEntityType,
+  toPublicEntity,
+} from '../electric-agents-types.js'
+import {
+  assertDispatchPolicyAllowed,
+  backfillEntityDispatchPolicy,
+  linkEntityDispatchSubscription,
+  resolveEffectiveDispatchPolicyForSpawn,
+  unlinkEntityDispatchSubscription,
+} from './dispatch-policy.js'
+import { routeBody, withSchema } from './schema.js'
+import type { ElectricAgentsEntity } from '../electric-agents-types.js'
+import type { JsonRouteRequest } from './schema.js'
+import type { RouterType } from 'itty-router'
+import type { TenantContext } from './context.js'
+
+interface AgentsRouteRequest extends JsonRouteRequest {
+  entityRoute?: ExistingEntityRoute
+}
+
+type ExistingEntityRoute = { entityUrl: string; entity: ElectricAgentsEntity }
+type AgentsRouteArgs = [TenantContext]
+type AgentsRouteResult = Response | undefined
+
+export type EntitiesRoutes = RouterType<
+  AgentsRouteRequest,
+  AgentsRouteArgs,
+  AgentsRouteResult
+>
+
+const stringRecordSchema = Type.Record(Type.String(), Type.String())
+
+function writeTokenFromRequest(request: AgentsRouteRequest): string {
+  const electricClaimToken = request.headers.get(`electric-claim-token`)?.trim()
+  if (electricClaimToken) return electricClaimToken
+  return (
+    request.headers
+      .get(`authorization`)
+      ?.replace(/^Bearer\s+/i, ``)
+      .trim() ?? ``
+  )
+}
+
+const wakeConditionSchema = Type.Union([
+  Type.Literal(`runFinished`),
+  Type.Object({
+    on: Type.Literal(`change`),
+    collections: Type.Optional(Type.Array(Type.String())),
+    ops: Type.Optional(
+      Type.Array(
+        Type.Union([
+          Type.Literal(`insert`),
+          Type.Literal(`update`),
+          Type.Literal(`delete`),
+        ])
+      )
+    ),
+  }),
+])
+
+const spawnBodySchema = Type.Object({
+  args: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+  tags: Type.Optional(stringRecordSchema),
+  parent: Type.Optional(Type.String()),
+  dispatch_policy: Type.Optional(dispatchPolicySchema),
+  initialMessage: Type.Optional(Type.Unknown()),
+  wake: Type.Optional(
+    Type.Object({
+      subscriberUrl: Type.String(),
+      condition: wakeConditionSchema,
+      debounceMs: Type.Optional(Type.Number()),
+      timeoutMs: Type.Optional(Type.Number()),
+      includeResponse: Type.Optional(Type.Boolean()),
+    })
+  ),
+})
+
+const sendBodySchema = Type.Object({
+  from: Type.Optional(Type.String()),
+  payload: Type.Optional(Type.Unknown()),
+  key: Type.Optional(Type.String()),
+  type: Type.Optional(Type.String()),
+  afterMs: Type.Optional(Type.Number()),
+})
+
+const forkBodySchema = Type.Object({
+  instance_id: Type.Optional(Type.String()),
+  waitTimeoutMs: Type.Optional(Type.Number()),
+})
+
+const setTagBodySchema = Type.Object({
+  value: Type.String(),
+})
+
+const scheduleBodySchema = Type.Union([
+  Type.Object({
+    scheduleType: Type.Literal(`cron`),
+    expression: Type.String(),
+    timezone: Type.Optional(Type.String()),
+    payload: Type.Unknown(),
+    debounceMs: Type.Optional(Type.Number()),
+    timeoutMs: Type.Optional(Type.Number()),
+  }),
+  Type.Object({
+    scheduleType: Type.Literal(`future_send`),
+    payload: Type.Unknown(),
+    targetUrl: Type.Optional(Type.String()),
+    fireAt: Type.String(),
+    from: Type.Optional(Type.String()),
+    messageType: Type.Optional(Type.String()),
+  }),
+])
+
+const entitiesRegisterBodySchema = Type.Object({
+  tags: Type.Optional(stringRecordSchema),
+})
+
+type SpawnBody = Static<typeof spawnBodySchema>
+type SendBody = Static<typeof sendBodySchema>
+type ForkBody = Static<typeof forkBodySchema>
+type SetTagBody = Static<typeof setTagBodySchema>
+type ScheduleBody = Static<typeof scheduleBodySchema>
+type EntitiesRegisterBody = Static<typeof entitiesRegisterBodySchema>
+
+export const entitiesRouter: EntitiesRoutes = Router<
+  AgentsRouteRequest,
+  AgentsRouteArgs,
+  AgentsRouteResult
+>({
+  base: `/_electric/entities`,
+})
+
+entitiesRouter.get(`/`, listEntities)
+entitiesRouter.post(
+  `/register`,
+  withSchema(entitiesRegisterBodySchema),
+  registerEntitiesSource
+)
+entitiesRouter.put(
+  `/:type/:instanceId`,
+  withSpawnableEntityType,
+  withSchema(spawnBodySchema),
+  spawnEntity
+)
+entitiesRouter.get(`/:type/:instanceId`, withExistingEntity, getEntity)
+entitiesRouter.head(`/:type/:instanceId`, withExistingEntity, headEntity)
+entitiesRouter.delete(`/:type/:instanceId`, withExistingEntity, killEntity)
+entitiesRouter.post(
+  `/:type/:instanceId/send`,
+  withExistingEntity,
+  withSchema(sendBodySchema),
+  sendEntity
+)
+entitiesRouter.post(
+  `/:type/:instanceId/fork`,
+  withExistingEntity,
+  withSchema(forkBodySchema),
+  forkEntity
+)
+entitiesRouter.post(
+  `/:type/:instanceId/tags/:tagKey`,
+  withExistingEntity,
+  withSchema(setTagBodySchema),
+  setTag
+)
+entitiesRouter.delete(
+  `/:type/:instanceId/tags/:tagKey`,
+  withExistingEntity,
+  removeTag
+)
+entitiesRouter.put(
+  `/:type/:instanceId/schedules/:scheduleId`,
+  withExistingEntity,
+  withSchema(scheduleBodySchema),
+  upsertSchedule
+)
+entitiesRouter.delete(
+  `/:type/:instanceId/schedules/:scheduleId`,
+  withExistingEntity,
+  deleteSchedule
+)
+
+function entityUrlFromSegments(
+  type: string,
+  instanceId: string
+): string | null {
+  if (!type || !instanceId) return null
+  if (type.startsWith(`_`) || type.includes(`*`) || instanceId.includes(`*`)) {
+    return null
+  }
+  return `/${type}/${instanceId}`
+}
+
+function firstQueryValue(
+  value: string | Array<string> | undefined
+): string | undefined {
+  return Array.isArray(value) ? value[0] : value
+}
+
+function requireExistingEntityRoute(
+  request: AgentsRouteRequest
+): ExistingEntityRoute {
+  if (!request.entityRoute) {
+    throw new Error(`existing entity middleware did not run`)
+  }
+  return request.entityRoute
+}
+
+async function withExistingEntity(
+  request: AgentsRouteRequest,
+  ctx: TenantContext
+): Promise<AgentsRouteResult> {
+  const entityUrl = entityUrlFromSegments(
+    request.params.type,
+    request.params.instanceId
+  )
+  if (!entityUrl) return undefined
+
+  const entity = await ctx.entityManager.registry.getEntity(entityUrl)
+  if (!entity) {
+    const entityType = await ctx.entityManager.registry.getEntityType(
+      request.params.type
+    )
+    if (entityType) {
+      return apiError(404, ErrCodeNotFound, `Entity not found at ${entityUrl}`)
+    }
+    return apiError(
+      404,
+      ErrCodeUnknownEntityType,
+      `Entity type "${request.params.type}" not found`
+    )
+  }
+
+  request.entityRoute = { entityUrl, entity }
+  return undefined
+}
+
+async function withSpawnableEntityType(
+  request: AgentsRouteRequest,
+  ctx: TenantContext
+): Promise<AgentsRouteResult> {
+  if (!entityUrlFromSegments(request.params.type, request.params.instanceId)) {
+    return undefined
+  }
+
+  const entityType = await ctx.entityManager.registry.getEntityType(
+    request.params.type
+  )
+  if (!entityType) {
+    return apiError(
+      404,
+      ErrCodeUnknownEntityType,
+      `Entity type "${request.params.type}" not found`
+    )
+  }
+
+  return undefined
+}
+
+async function listEntities(
+  { query }: AgentsRouteRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  const { entities } = await ctx.entityManager.registry.listEntities({
+    type: firstQueryValue(query.type),
+    status: firstQueryValue(query.status),
+    parent: firstQueryValue(query.parent),
+  })
+  return json(entities.map((entity) => toPublicEntity(entity)))
+}
+
+async function registerEntitiesSource(
+  request: AgentsRouteRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  const parsed = routeBody<EntitiesRegisterBody>(request)
+  const result = await ctx.entityManager.registerEntitiesSource(
+    parsed.tags ?? {}
+  )
+  return json(result)
+}
+
+async function upsertSchedule(
+  request: AgentsRouteRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  const parsed = routeBody<ScheduleBody>(request)
+  const { entityUrl } = requireExistingEntityRoute(request)
+  const scheduleId = decodeURIComponent(request.params.scheduleId)
+
+  if (parsed.scheduleType === `cron`) {
+    const result = await ctx.entityManager.upsertCronSchedule(entityUrl, {
+      id: scheduleId,
+      expression: parsed.expression,
+      timezone: parsed.timezone,
+      payload: parsed.payload,
+      debounceMs: parsed.debounceMs,
+      timeoutMs: parsed.timeoutMs,
+    })
+    return json(result)
+  }
+
+  if (parsed.scheduleType === `future_send`) {
+    const result = await ctx.entityManager.upsertFutureSendSchedule(entityUrl, {
+      id: scheduleId,
+      payload: parsed.payload,
+      targetUrl: parsed.targetUrl,
+      fireAt: parsed.fireAt,
+      from: parsed.from,
+      messageType: parsed.messageType,
+    })
+    return json(result)
+  }
+
+  throw new Error(`schedule schema accepted an unknown scheduleType`)
+}
+
+async function deleteSchedule(
+  request: AgentsRouteRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  const { entityUrl } = requireExistingEntityRoute(request)
+  const result = await ctx.entityManager.deleteSchedule(entityUrl, {
+    id: decodeURIComponent(request.params.scheduleId),
+  })
+  return json(result)
+}
+
+async function setTag(
+  request: AgentsRouteRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  const parsed = routeBody<SetTagBody>(request)
+  const { entityUrl } = requireExistingEntityRoute(request)
+  const token = writeTokenFromRequest(request)
+  const updated = await ctx.entityManager.setTag(
+    entityUrl,
+    decodeURIComponent(request.params.tagKey),
+    { value: parsed.value },
+    token
+  )
+  return json(toPublicEntity(updated))
+}
+
+async function removeTag(
+  request: AgentsRouteRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  const { entityUrl } = requireExistingEntityRoute(request)
+  const token = writeTokenFromRequest(request)
+  const updated = await ctx.entityManager.removeTag(
+    entityUrl,
+    decodeURIComponent(request.params.tagKey),
+    token
+  )
+  return json(toPublicEntity(updated))
+}
+
+async function forkEntity(
+  request: AgentsRouteRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  const parsed = routeBody<ForkBody>(request)
+  const { entityUrl, entity } = requireExistingEntityRoute(request)
+  await assertDispatchPolicyAllowed(ctx, entity.dispatch_policy)
+  const result = await ctx.entityManager.forkSubtree(entityUrl, {
+    rootInstanceId: parsed.instance_id,
+    waitTimeoutMs: parsed.waitTimeoutMs,
+  })
+  for (const forkedEntity of result.entities) {
+    await linkEntityDispatchSubscription(ctx, forkedEntity)
+  }
+  return json(
+    {
+      root: toPublicEntity(result.root),
+      entities: result.entities.map((entity) => toPublicEntity(entity)),
+    },
+    { status: 201 }
+  )
+}
+
+async function sendEntity(
+  request: AgentsRouteRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  const parsed = routeBody<SendBody>(request)
+  const { entityUrl, entity } = requireExistingEntityRoute(request)
+
+  if (!entity.dispatch_policy) {
+    const updatedEntity = await backfillEntityDispatchPolicy(ctx, entity)
+    await linkEntityDispatchSubscription(ctx, updatedEntity)
+  }
+
+  if (parsed.afterMs && parsed.afterMs > 0) {
+    await ctx.entityManager.enqueueDelayedSend(
+      entityUrl,
+      {
+        from: parsed.from,
+        payload: parsed.payload,
+        key: parsed.key,
+        type: parsed.type,
+      },
+      new Date(Date.now() + parsed.afterMs)
+    )
+  } else {
+    await ctx.entityManager.send(entityUrl, {
+      from: parsed.from,
+      payload: parsed.payload,
+      key: parsed.key,
+      type: parsed.type,
+    })
+  }
+
+  return status(204)
+}
+
+async function spawnEntity(
+  request: AgentsRouteRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  const parsed = routeBody<SpawnBody>(request)
+  const dispatchPolicy = await resolveEffectiveDispatchPolicyForSpawn(
+    ctx,
+    request.params.type,
+    {
+      dispatchPolicy: parsed.dispatch_policy,
+      parent: parsed.parent,
+    }
+  )
+  await assertDispatchPolicyAllowed(ctx, dispatchPolicy)
+  const entity = await ctx.entityManager.spawn(request.params.type, {
+    instance_id: request.params.instanceId,
+    args: parsed.args,
+    tags: parsed.tags,
+    parent: parsed.parent,
+    dispatch_policy: dispatchPolicy,
+    initialMessage: undefined,
+    wake: parsed.wake,
+  })
+  await linkEntityDispatchSubscription(ctx, entity)
+  if (parsed.initialMessage !== undefined) {
+    await ctx.entityManager.send(entity.url, {
+      from: parsed.parent ?? `spawn`,
+      payload: parsed.initialMessage,
+    })
+  }
+
+  return json(
+    { ...toPublicEntity(entity), txid: entity.txid },
+    {
+      status: 201,
+      headers: { 'x-write-token': entity.write_token },
+    }
+  )
+}
+
+function getEntity(request: AgentsRouteRequest): Response {
+  return json(toPublicEntity(requireExistingEntityRoute(request).entity))
+}
+
+function headEntity(): Response {
+  return status(200)
+}
+
+async function killEntity(
+  request: AgentsRouteRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  const { entityUrl, entity } = requireExistingEntityRoute(request)
+  await unlinkEntityDispatchSubscription(ctx, entity)
+  const result = await ctx.entityManager.kill(entityUrl)
+  ctx.runtime.claimWriteTokens.clearStream(ctx.service, entity.streams.main)
+  return json(result)
+}

package/src/routing/entity-types-router.ts

@@ -0,0 +1,229 @@
+/**
+ * HTTP routes for Electric Agents entity type management.
+ */
+
+import { Type, type Static } from '@sinclair/typebox'
+import { Router, json, status } from 'itty-router'
+import { dispatchPolicySchema } from '../dispatch-policy-schema.js'
+import { ElectricAgentsError } from '../entity-manager.js'
+import {
+  ErrCodeNotFound,
+  ErrCodeServeEndpointNameMismatch,
+  ErrCodeServeEndpointUnreachable,
+} from '../electric-agents-types.js'
+import { apiError } from '../electric-agents-http.js'
+import { routeBody, withSchema } from './schema.js'
+import { rewriteLoopbackWebhookUrl } from '../utils/webhook-url.js'
+import type {
+  ElectricAgentsEntityType,
+  RegisterEntityTypeRequest,
+} from '../electric-agents-types.js'
+import type { JsonRouteRequest } from './schema.js'
+import type { RouterType } from 'itty-router'
+import type { TenantContext } from './context.js'
+
+export interface ElectricAgentsEntityTypeRouteRequest
+  extends JsonRouteRequest {}
+
+type EntityTypeRouteArgs = [TenantContext]
+type EntityTypeRouteResult = Response | undefined
+
+export type ElectricAgentsEntityTypeRoutes = RouterType<
+  ElectricAgentsEntityTypeRouteRequest,
+  EntityTypeRouteArgs,
+  EntityTypeRouteResult
+>
+
+type PublicEntityTypeResponse = ElectricAgentsEntityType & {
+  input_schemas?: Record<string, Record<string, unknown>>
+  output_schemas?: Record<string, Record<string, unknown>>
+  revision: number
+}
+
+const jsonObjectSchema = Type.Record(Type.String(), Type.Unknown())
+const schemaMapSchema = Type.Record(Type.String(), jsonObjectSchema)
+
+const registerEntityTypeBodySchema = Type.Object({
+  name: Type.Optional(Type.String()),
+  description: Type.Optional(Type.String()),
+  creation_schema: Type.Optional(jsonObjectSchema),
+  inbox_schemas: Type.Optional(schemaMapSchema),
+  state_schemas: Type.Optional(schemaMapSchema),
+  input_schemas: Type.Optional(schemaMapSchema),
+  output_schemas: Type.Optional(schemaMapSchema),
+  serve_endpoint: Type.Optional(Type.String()),
+  default_dispatch_policy: Type.Optional(dispatchPolicySchema),
+})
+
+const amendEntityTypeSchemasBodySchema = Type.Object({
+  input_schemas: Type.Optional(schemaMapSchema),
+  output_schemas: Type.Optional(schemaMapSchema),
+  inbox_schemas: Type.Optional(schemaMapSchema),
+  state_schemas: Type.Optional(schemaMapSchema),
+})
+
+type RegisterEntityTypeBody = Static<typeof registerEntityTypeBodySchema>
+type AmendEntityTypeSchemasBody = Static<
+  typeof amendEntityTypeSchemasBodySchema
+>
+
+export const entityTypesRouter: ElectricAgentsEntityTypeRoutes = Router<
+  ElectricAgentsEntityTypeRouteRequest,
+  EntityTypeRouteArgs,
+  EntityTypeRouteResult
+>({
+  base: `/_electric/entity-types`,
+})
+
+entityTypesRouter.get(`/`, listEntityTypes)
+entityTypesRouter.post(
+  `/`,
+  withSchema(registerEntityTypeBodySchema),
+  registerEntityType
+)
+entityTypesRouter.patch(
+  `/:name/schemas`,
+  withSchema(amendEntityTypeSchemasBodySchema),
+  amendSchemas
+)
+entityTypesRouter.get(`/:name`, getEntityType)
+entityTypesRouter.delete(`/:name`, deleteEntityType)
+
+async function registerEntityType(
+  request: ElectricAgentsEntityTypeRouteRequest,
+  ctx: TenantContext
+): Promise<EntityTypeRouteResult> {
+  const parsed = routeBody<RegisterEntityTypeBody>(request)
+  const normalized = normalizeEntityTypeRequest(parsed)
+
+  if (
+    normalized.serve_endpoint &&
+    !normalized.description &&
+    !normalized.creation_schema
+  ) {
+    return await discoverServeEndpoint(ctx, normalized)
+  }
+
+  const entityType = await ctx.entityManager.registerEntityType(normalized)
+  return json(toPublicEntityType(entityType), { status: 201 })
+}
+
+async function listEntityTypes(
+  _request: ElectricAgentsEntityTypeRouteRequest,
+  ctx: TenantContext
+): Promise<EntityTypeRouteResult> {
+  const entityTypes = await ctx.entityManager.registry.listEntityTypes()
+  return json(entityTypes.map((entityType) => toPublicEntityType(entityType)))
+}
+
+async function discoverServeEndpoint(
+  ctx: TenantContext,
+  parsed: RegisterEntityTypeRequest
+): Promise<Response> {
+  try {
+    const response = await fetch(parsed.serve_endpoint!, { method: `PUT` })
+
+    if (!response.ok) {
+      return apiError(
+        502,
+        ErrCodeServeEndpointUnreachable,
+        `Serve endpoint returned status ${response.status}`
+      )
+    }
+
+    const manifest = (await response.json()) as RegisterEntityTypeRequest
+    if (manifest.name !== parsed.name) {
+      return apiError(
+        400,
+        ErrCodeServeEndpointNameMismatch,
+        `Serve endpoint returned name "${manifest.name}" but expected "${parsed.name}"`
+      )
+    }
+
+    manifest.serve_endpoint = parsed.serve_endpoint
+
+    const entityType = await ctx.entityManager.registerEntityType(
+      normalizeEntityTypeRequest(manifest)
+    )
+    return json(toPublicEntityType(entityType), { status: 201 })
+  } catch (err) {
+    if (err instanceof ElectricAgentsError) {
+      throw err
+    }
+    return apiError(
+      502,
+      ErrCodeServeEndpointUnreachable,
+      `Failed to reach serve endpoint: ${
+        err instanceof Error ? err.message : String(err)
+      }`
+    )
+  }
+}
+
+async function getEntityType(
+  request: ElectricAgentsEntityTypeRouteRequest,
+  ctx: TenantContext
+): Promise<EntityTypeRouteResult> {
+  const entityType = await ctx.entityManager.registry.getEntityType(
+    request.params.name
+  )
+  if (!entityType) {
+    return apiError(404, ErrCodeNotFound, `Entity type not found`)
+  }
+
+  return json(toPublicEntityType(entityType))
+}
+
+async function amendSchemas(
+  request: ElectricAgentsEntityTypeRouteRequest,
+  ctx: TenantContext
+): Promise<EntityTypeRouteResult> {
+  const parsed = routeBody<AmendEntityTypeSchemasBody>(request)
+
+  const updated = await ctx.entityManager.amendSchemas(request.params.name, {
+    inbox_schemas: parsed.inbox_schemas ?? parsed.input_schemas,
+    state_schemas: parsed.state_schemas ?? parsed.output_schemas,
+  })
+  return json(toPublicEntityType(updated))
+}
+
+async function deleteEntityType(
+  request: ElectricAgentsEntityTypeRouteRequest,
+  ctx: TenantContext
+): Promise<EntityTypeRouteResult> {
+  await ctx.entityManager.deleteEntityType(request.params.name)
+  return status(204)
+}
+
+function normalizeEntityTypeRequest(
+  parsed: RegisterEntityTypeBody | RegisterEntityTypeRequest
+): RegisterEntityTypeRequest {
+  const serveEndpoint = rewriteLoopbackWebhookUrl(parsed.serve_endpoint)
+  const compatibilityFields = parsed as RegisterEntityTypeBody
+  return {
+    name: parsed.name ?? ``,
+    description: parsed.description ?? ``,
+    creation_schema: parsed.creation_schema,
+    inbox_schemas: parsed.inbox_schemas ?? compatibilityFields.input_schemas,
+    state_schemas: parsed.state_schemas ?? compatibilityFields.output_schemas,
+    serve_endpoint: serveEndpoint,
+    default_dispatch_policy:
+      parsed.default_dispatch_policy ??
+      (serveEndpoint
+        ? ({
+            targets: [{ type: `webhook`, url: serveEndpoint }],
+          } as RegisterEntityTypeRequest[`default_dispatch_policy`])
+        : undefined),
+  }
+}
+
+function toPublicEntityType(
+  entityType: ElectricAgentsEntityType
+): PublicEntityTypeResponse {
+  return {
+    ...entityType,
+    input_schemas: entityType.inbox_schemas,
+    output_schemas: entityType.state_schemas,
+    revision: entityType.revision,
+  }
+}