sailfork / t3code-github / .repos/ alchemy-effect/ packages/ alchemy/ src/ State/ HttpStateApi.ts

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<void, HttpApiError.Unauthorized>;
  }
>()("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<StateAuth, never, BearerTokenValidator> = 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>()(
  "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) {}