import * as Context from "effect/Context"; import * as Effect from "effect/Effect"; import * as HttpApi from "effect/http-api/HttpApi"; import * as HttpApiEndpoint from "effect/http-api/HttpApiEndpoint"; import * as HttpApiError from "effect/http-api/HttpApiError"; import * as HttpApiGroup from "effect/http-api/HttpApiGroup"; import * as HttpApiMiddleware from "effect/http-api/HttpApiMiddleware"; import * as HttpApiSchema from "effect/http-api/HttpApiSchema"; import * as HttpApiSecurity from "effect/http-api/HttpApiSecurity"; import * as Layer from "effect/Layer"; import * as Redacted from "effect/Redacted"; import * as Schema from "effect/Schema"; import { UserFacingError } from "../UserFacingError.ts"; /** * Resource-state payload shape on the wire. * * Pinned to JSON encoding via {@link HttpApiSchema.asJson} so that both * sides of the API agree on `Content-Type: application/json`. With a * bare `Schema.Any` the server's payload-decoder map is keyed off the * default content type only — any client request that arrives with a * differently-shaped body (or a transport that drops the * `Content-Type` header entirely) falls into the `payloadBy.get( * contentType)` miss branch in `HttpApiBuilder.decodePayload` and * surfaces as a confusing `415 Unsupported Media Type`. Annotating * the schema makes the encoding explicit on both endpoints and the * client encoder, so the wire format is unambiguous. */ export const ResourceStateSchema = Schema.Any.pipe(HttpApiSchema.asJson()); export class BearerTokenValidator extends Context.Service< BearerTokenValidator, { readonly validate: (token: string) => Effect.Effect; } >()("alchemy/State/BearerTokenValidator") {} export class StateAuth extends HttpApiMiddleware.Service< StateAuth, { requires: BearerTokenValidator } >()("alchemy/State/StateAuth", { security: { bearer: HttpApiSecurity.bearer, }, error: HttpApiError.UnauthorizedNoContent, }) {} export const StateAuthLive: Layer.Layer = Layer.effect( StateAuth, Effect.gen(function* () { const validator = yield* BearerTokenValidator; return { bearer: (httpEffect, { credential }) => validator.validate(Redacted.value(credential)).pipe(Effect.flatMap(() => httpEffect)), }; }), ); /** `stack` path segment for nested REST resources. */ const StackParams = Schema.Struct({ stack: Schema.String, }); /** Optional stage selector for stack deletion. */ const OptionalStageQuery = Schema.Struct({ stage: Schema.optional(Schema.String), }); /** `(stack, stage)` path segments shared by stage-scoped endpoints. */ const StackStage = Schema.Struct({ stack: Schema.String, stage: Schema.String, }); /** `(stack, stage, fqn)` path segments for a single resource. */ const ResourceKey = Schema.Struct({ stack: Schema.String, stage: Schema.String, fqn: Schema.String, }); /** * The store failed to serve a request: which operation, and the kind of * failure (its tag). Never the failure's message, which can carry state; the * Worker logs the full cause. Without it, any failure behind the auth * middleware was encoded as its `Unauthorized` and surfaced as a bare 500. */ export class StateStoreFailure extends Schema.TaggedError()( "StateStoreFailure", { operation: Schema.String, reason: Schema.String }, { httpApiStatus: 500 }, ) { readonly [UserFacingError] = true; override get message() { return `State store failed to ${this.operation} (${this.reason}); its logs have the cause`; } } export const ListStacks = HttpApiEndpoint.get("listStacks", "/state/stacks", { success: Schema.Array(Schema.String), error: StateStoreFailure, }); export const ListStages = HttpApiEndpoint.get("listStages", "/state/stacks/:stack/stages", { params: StackParams, success: Schema.Array(Schema.String), error: StateStoreFailure, }); export const ListResources = HttpApiEndpoint.get( "listResources", "/state/stacks/:stack/stages/:stage/resources", { params: StackStage, success: Schema.Array(Schema.String), error: StateStoreFailure, }, ); export const GetState = HttpApiEndpoint.get( "getState", "/state/stacks/:stack/stages/:stage/resources/:fqn", { params: ResourceKey, success: Schema.UndefinedOr(ResourceStateSchema), error: StateStoreFailure, }, ); export const SetState = HttpApiEndpoint.put( "setState", "/state/stacks/:stack/stages/:stage/resources/:fqn", { params: ResourceKey, payload: ResourceStateSchema, success: ResourceStateSchema, error: StateStoreFailure, }, ); export const DeleteState = HttpApiEndpoint.delete( "deleteState", "/state/stacks/:stack/stages/:stage/resources/:fqn", { params: ResourceKey, success: HttpApiSchema.NoContent, error: StateStoreFailure, }, ); export const DeleteStack = HttpApiEndpoint.delete("deleteStack", "/state/stacks/:stack", { params: StackParams, query: OptionalStageQuery, success: HttpApiSchema.NoContent, error: StateStoreFailure, }); export const GetReplacedResources = HttpApiEndpoint.get( "getReplacedResources", "/state/stacks/:stack/stages/:stage/replaced-resources", { params: StackStage, success: Schema.Array(ResourceStateSchema), error: StateStoreFailure, }, ); export const GetStackOutput = HttpApiEndpoint.get( "getStackOutput", "/state/stacks/:stack/stages/:stage/output", { params: StackStage, success: Schema.UndefinedOr(ResourceStateSchema), error: StateStoreFailure, }, ); export const SetStackOutput = HttpApiEndpoint.put( "setStackOutput", "/state/stacks/:stack/stages/:stage/output", { params: StackStage, payload: ResourceStateSchema, success: ResourceStateSchema, error: StateStoreFailure, }, ); /** * Version of the State Store wire / behavioural contract. * * Bump this whenever the wire format or runtime behaviour of an HTTP * state-store changes in a way that an older deployed copy can no * longer satisfy. Clients query `/version` on the deployed worker and * compare against this constant; a mismatch (or 404) triggers a * forced redeploy via the bootstrap flow. */ export const STATE_STORE_VERSION = 5 as const; /** Response shape for the unauthenticated `/version` probe. */ export const VersionResponse = Schema.Struct({ version: Schema.Number, }); /** * Unauthenticated probe so clients can detect a stale (or absent) * deployed worker without holding a valid bearer token. The returned * version is bumped whenever the wire / behavioural contract changes * in a way that requires a redeploy. */ export const GetVersion = HttpApiEndpoint.get("getVersion", "/version", { success: VersionResponse, }); export class StateGroup extends HttpApiGroup.make("state") .add(ListStacks) .add(ListStages) .add(ListResources) .add(GetState) .add(SetState) .add(DeleteState) .add(GetReplacedResources) .add(DeleteStack) .add(GetStackOutput) .add(SetStackOutput) .middleware(StateAuth) {} export class VersionGroup extends HttpApiGroup.make("version").add(GetVersion) {} export class StateApi extends HttpApi.make("alchemy-state").add(StateGroup).add(VersionGroup) {}