imposters 0.1.0

package/src/client/ImpostersClient.ts

@@ -0,0 +1,21 @@
+import type { HttpClient } from "@effect/platform"
+import { FetchHttpClient, HttpApiClient } from "@effect/platform"
+import type { Effect } from "effect"
+import { Context, Layer } from "effect"
+import { AdminApi } from "../api/AdminApi"
+
+export const makeImpostersClient = (baseUrl?: string) =>
+  HttpApiClient.make(AdminApi, { baseUrl: baseUrl ?? "http://localhost:2525" })
+
+export type ImpostersClientShape = Effect.Effect.Success<ReturnType<typeof makeImpostersClient>>
+
+export class ImpostersClient extends Context.Tag("ImpostersClient")<
+  ImpostersClient,
+  ImpostersClientShape
+>() {}
+
+export const ImpostersClientLive = (baseUrl?: string): Layer.Layer<ImpostersClient, never, HttpClient.HttpClient> =>
+  Layer.effect(ImpostersClient, makeImpostersClient(baseUrl))
+
+export const ImpostersClientFetchLive = (baseUrl?: string): Layer.Layer<ImpostersClient> =>
+  ImpostersClientLive(baseUrl).pipe(Layer.provide(FetchHttpClient.layer))

package/src/client/index.ts

@@ -0,0 +1,9 @@
+export { HandlerHttpClientLive, makeHandlerHttpClient } from "./HandlerHttpClient"
+
+export { ImpostersClient, ImpostersClientFetchLive, ImpostersClientLive, makeImpostersClient } from "./ImpostersClient"
+
+export type { ImpostersClientShape } from "./ImpostersClient"
+
+export { makeTestServer, withImposter } from "./testing"
+
+export type { ImposterTestContext, StubConfig, WithImposterConfig } from "./testing"

package/src/client/testing.ts

@@ -0,0 +1,105 @@
+import { HttpApiBuilder } from "@effect/platform"
+import { Effect, Layer } from "effect"
+import type { NonEmptyString, PortNumber } from "../schemas/common"
+import type { CreateStubRequest } from "../schemas/StubSchema"
+import { HandlerHttpClientLive } from "./HandlerHttpClient"
+import { ImpostersClient, ImpostersClientLive } from "./ImpostersClient"
+
+export interface StubConfig {
+  readonly predicates?: ReadonlyArray<{
+    readonly field: "method" | "path" | "headers" | "query" | "body"
+    readonly operator: "equals" | "contains" | "startsWith" | "matches" | "exists"
+    readonly value: unknown
+    readonly caseSensitive?: boolean
+  }>
+  readonly responses: readonly [ResponseConfigInput, ...ReadonlyArray<ResponseConfigInput>]
+  readonly responseMode?: "sequential" | "random" | "repeat"
+}
+
+interface ResponseConfigInput {
+  readonly status?: number
+  readonly headers?: Record<string, string>
+  readonly body?: unknown
+  readonly delay?: number
+}
+
+export interface WithImposterConfig {
+  readonly port?: number
+  readonly name?: string
+  readonly stubs?: ReadonlyArray<StubConfig>
+}
+
+export interface ImposterTestContext {
+  readonly id: string
+  readonly port: number
+}
+
+const asPort = (n: number) => n as PortNumber
+const asNes = (s: string) => s as NonEmptyString
+
+const toStubPayload = (stub: StubConfig): CreateStubRequest => ({
+  predicates: (stub.predicates ?? []).map((p) => ({
+    field: p.field,
+    operator: p.operator,
+    value: p.value,
+    caseSensitive: p.caseSensitive ?? true
+  })),
+  responses: stub.responses.map((r) => ({
+    status: r.status ?? 200,
+    ...(r.headers !== undefined ? { headers: r.headers } : {}),
+    ...(r.body !== undefined ? { body: r.body } : {}),
+    ...(r.delay !== undefined ? { delay: r.delay } : {})
+  })) as unknown as CreateStubRequest["responses"],
+  responseMode: stub.responseMode ?? "sequential"
+})
+
+export const withImposter = <A, E>(
+  config: WithImposterConfig,
+  testFn: (ctx: ImposterTestContext) => Effect.Effect<A, E, ImpostersClient>
+): Effect.Effect<A, E | Error, ImpostersClient> =>
+  Effect.acquireUseRelease(
+    Effect.gen(function*() {
+      const client = yield* ImpostersClient
+      const imp = yield* client.imposters.createImposter({
+        payload: {
+          ...(config.port !== undefined ? { port: asPort(config.port) } : {}),
+          ...(config.name !== undefined ? { name: asNes(config.name) } : {}),
+          protocol: "HTTP" as const,
+          adminPath: "/_admin"
+        }
+      })
+
+      for (const stub of config.stubs ?? []) {
+        yield* client.imposters.addStub({
+          path: { imposterId: imp.id },
+          payload: toStubPayload(stub)
+        })
+      }
+
+      yield* client.imposters.updateImposter({
+        path: { id: imp.id },
+        payload: { status: "running" }
+      })
+
+      yield* Effect.sleep("150 millis")
+
+      return { id: imp.id as string, port: imp.port as number }
+    }),
+    (ctx) => testFn(ctx),
+    (ctx) =>
+      Effect.gen(function*() {
+        const client = yield* ImpostersClient
+        yield* client.imposters.deleteImposter({
+          path: { id: ctx.id as typeof ctx.id & NonEmptyString },
+          urlParams: { force: true }
+        }).pipe(Effect.catchAll(() => Effect.void))
+      }).pipe(Effect.catchAll(() => Effect.void))
+  )
+
+export const makeTestServer = (fullLayer: Layer.Layer<any, any, never>) => {
+  const { dispose, handler } = HttpApiBuilder.toWebHandler(fullLayer as any)
+  const clientLayer = ImpostersClientLive().pipe(
+    Layer.provide(HandlerHttpClientLive(handler))
+  )
+  return { handler, dispose, clientLayer }
+}

package/src/domain/imposter.ts

@@ -0,0 +1,186 @@
+import * as Clock from "effect/Clock"
+import * as Data from "effect/Data"
+import * as DateTime from "effect/DateTime"
+import * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import type * as ParseResult from "effect/ParseResult"
+import * as Schema from "effect/Schema"
+import { Uuid } from "../services/Uuid"
+
+// Schemas for validation
+const ImposterNameSchema = Schema.String.pipe(
+  Schema.minLength(1),
+  Schema.maxLength(100),
+  Schema.pattern(/^[a-zA-Z0-9-_]+$/)
+)
+
+const PortSchema = Schema.Number.pipe(
+  Schema.int(),
+  Schema.between(1024, 65535)
+)
+
+type ImposterStatus = "running" | "stopped" | "starting" | "stopping"
+
+const CreateImposterRequestSchema = Schema.Struct({
+  name: Schema.optional(ImposterNameSchema),
+  port: Schema.optional(PortSchema)
+})
+
+export interface ProxyConfigDomain {
+  readonly targetUrl: string
+  readonly mode: "passthrough" | "record"
+  readonly addHeaders?: Record<string, string> | undefined
+  readonly removeHeaders: ReadonlyArray<string>
+  readonly followRedirects: boolean
+  readonly timeout: number
+}
+
+// Domain types using tagged interfaces
+export interface ImposterConfig {
+  readonly _tag: "ImposterConfig"
+  readonly id: string
+  readonly name: string
+  readonly port: number
+  readonly status: ImposterStatus
+  readonly createdAt: DateTime.Utc
+  readonly proxy?: ProxyConfigDomain | undefined
+}
+
+export const ImposterConfig = Data.tagged<ImposterConfig>("ImposterConfig")
+
+export interface CreateImposterRequest {
+  readonly _tag: "CreateImposterRequest"
+  readonly name?: string
+  readonly port?: number
+}
+
+export const CreateImposterRequest = Data.tagged<CreateImposterRequest>("CreateImposterRequest")
+
+export interface ImposterRef {
+  readonly _tag: "ImposterRef"
+  readonly config: ImposterConfig
+  readonly startTime: DateTime.Utc
+  readonly endpointCount: number
+}
+
+export const ImposterRef = Data.tagged<ImposterRef>("ImposterRef")
+
+// Tagged errors
+export class ImposterError extends Data.TaggedError("ImposterError")<{
+  readonly reason: string
+  readonly cause?: unknown
+}> {}
+
+export class PortInUseError extends Data.TaggedError("PortInUseError")<{
+  readonly port: number
+}> {}
+
+export class ImposterNotFoundError extends Data.TaggedError("ImposterNotFoundError")<{
+  readonly id: string
+}> {}
+
+/**
+ * Parses and validates imposter creation request
+ */
+export const parseCreateImposterRequest = (
+  input: unknown
+): Effect.Effect<typeof CreateImposterRequestSchema.Type, ParseResult.ParseError> =>
+  Schema.decodeUnknown(CreateImposterRequestSchema)(input)
+
+/**
+ * Creates a new imposter configuration from validated input
+ */
+export const createImposterConfig = (
+  validatedInput: typeof CreateImposterRequestSchema.Type
+) =>
+  Effect.gen(function*() {
+    const uuid = yield* Uuid
+    const id = yield* uuid.generateShort
+    const name = validatedInput.name ?? id
+
+    return ImposterConfig({
+      id,
+      name,
+      port: validatedInput.port ?? 0, // Will be assigned by port allocator if 0
+      status: "starting",
+      createdAt: DateTime.unsafeNow()
+    })
+  })
+
+/**
+ * Creates a new imposter from raw input (parse + create)
+ */
+export const newImposterConfig = (input: unknown) =>
+  Effect.gen(function*() {
+    const validated = yield* parseCreateImposterRequest(input)
+    return yield* createImposterConfig(validated)
+  })
+
+/**
+ * Updates imposter status
+ */
+export const updateImposterStatus = (status: ImposterStatus) => (config: ImposterConfig): ImposterConfig =>
+  ImposterConfig({
+    ...config,
+    status
+  })
+
+/**
+ * Updates imposter port
+ */
+export const updateImposterPort = (port: number) => (config: ImposterConfig): ImposterConfig =>
+  ImposterConfig({
+    ...config,
+    port
+  })
+
+/**
+ * Calculates imposter uptime using Effect's Duration
+ */
+export const calculateUptime = (startTime: DateTime.Utc) =>
+  Effect.map(Clock.currentTimeMillis, (now) => Duration.millis(now - DateTime.toEpochMillis(startTime)))
+
+/**
+ * Creates an ImposterRef from config and runtime info
+ */
+export const createImposterRef =
+  (startTime: DateTime.Utc) => (endpointCount: number) => (config: ImposterConfig): ImposterRef =>
+    ImposterRef({
+      config,
+      startTime,
+      endpointCount
+    })
+
+/**
+ * Extracts imposter summary for API responses
+ */
+export const toImposterSummary = (ref: ImposterRef) =>
+  Effect.map(calculateUptime(ref.startTime), (uptime) => ({
+    id: ref.config.id,
+    name: ref.config.name,
+    port: ref.config.port,
+    status: ref.config.status,
+    endpointCount: ref.endpointCount,
+    createdAt: DateTime.formatIso(ref.config.createdAt),
+    uptime: Duration.format(uptime)
+  }))
+
+/**
+ * Gets uptime in human readable format
+ */
+export const getUptimeFormatted = (ref: ImposterRef) => Effect.map(calculateUptime(ref.startTime), Duration.format)
+
+/**
+ * Checks if imposter is running
+ */
+export const isRunning = (config: ImposterConfig): boolean => config.status === "running"
+
+/**
+ * Checks if imposter can be started
+ */
+export const canStart = (config: ImposterConfig): boolean => config.status === "stopped" || config.status === "starting"
+
+/**
+ * Checks if imposter can be stopped
+ */
+export const canStop = (config: ImposterConfig): boolean => config.status === "running" || config.status === "stopping"

package/src/domain/route.ts

@@ -0,0 +1,255 @@
+import * as Data from "effect/Data"
+import * as DateTime from "effect/DateTime"
+import * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import { pipe } from "effect/Function"
+import * as Option from "effect/Option"
+import type * as ParseResult from "effect/ParseResult"
+import * as Schema from "effect/Schema"
+import { Uuid } from "../services/Uuid"
+
+const HttpMethodSchema = Schema.Literal("GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS")
+
+const StatusCodeSchema = Schema.Number.pipe(Schema.int(), Schema.between(100, 599))
+
+const DelaySchema = Schema.Number.pipe(Schema.int(), Schema.between(0, 60000))
+
+const PathSchema = Schema.String.pipe(
+  Schema.startsWith("/"),
+  Schema.pattern(/^\/[a-zA-Z0-9\-._~!$&'()*+,;=:@/{}[\]]*$/)
+)
+
+const ResponseSchema = Schema.Struct({
+  status: Schema.optionalWith(StatusCodeSchema, { default: () => 200 }),
+  headers: Schema.optional(
+    Schema.Record({ key: Schema.String, value: Schema.String })
+  ),
+  body: Schema.Unknown
+})
+
+const CreateRouteRequestSchema = Schema.Struct({
+  id: Schema.optional(Schema.String),
+  path: PathSchema,
+  method: Schema.optionalWith(HttpMethodSchema, { default: () => "GET" }),
+  response: ResponseSchema,
+  delay: Schema.optional(DelaySchema)
+})
+
+export interface Route {
+  readonly _tag: "Route"
+  readonly id: string
+  readonly path: string
+  readonly method: typeof HttpMethodSchema.Type
+  readonly response: Response
+  readonly delay: Option.Option<Duration.Duration>
+  readonly createdAt: DateTime.Utc
+}
+
+export const Route = Data.tagged<Route>("Route")
+
+export interface Response {
+  readonly _tag: "Response"
+  readonly status: number
+  readonly headers: Option.Option<Record<string, string>>
+  readonly body: unknown
+}
+
+export const Response = Data.tagged<Response>("Response")
+
+export interface CreateRouteRequest {
+  readonly _tag: "CreateRouteRequest"
+  readonly id?: string
+  readonly path: string
+  readonly method?: string
+  readonly response: {
+    readonly status?: number
+    readonly headers?: Record<string, string>
+    readonly body: unknown
+  }
+  readonly delay?: number
+}
+
+export const CreateRouteRequest = Data.tagged<CreateRouteRequest>("CreateRouteRequest")
+
+// Tagged errors
+export class RouteError extends Data.TaggedError("RouteError")<{
+  readonly reason: string
+  readonly field?: string
+  readonly value?: unknown
+}> {}
+
+export class RouteNotFoundError extends Data.TaggedError("RouteNotFoundError")<{
+  readonly id: string
+}> {}
+
+// Pure functions following Effect patterns
+
+/**
+ * Parses and validates route creation request
+ */
+export const parseCreateRouteRequest = (
+  input: unknown
+): Effect.Effect<typeof CreateRouteRequestSchema.Type, ParseResult.ParseError> =>
+  Schema.decodeUnknown(CreateRouteRequestSchema)(input)
+
+/**
+ * Creates a new route from validated input
+ */
+export const createRoute = (
+  validatedInput: typeof CreateRouteRequestSchema.Type
+) =>
+  Effect.gen(function*() {
+    const uuid = yield* Uuid
+    const id = validatedInput.id ?? (yield* uuid.generate)
+
+    const response = Response({
+      status: validatedInput.response.status,
+      headers: Option.fromNullable(validatedInput.response.headers),
+      body: validatedInput.response.body
+    })
+
+    return Route({
+      id,
+      path: validatedInput.path,
+      method: validatedInput.method,
+      response,
+      delay: pipe(
+        validatedInput.delay,
+        Option.fromNullable,
+        Option.map(Duration.millis)
+      ),
+      createdAt: DateTime.unsafeNow()
+    })
+  })
+
+/**
+ * Creates a new route from raw input (parse + create)
+ */
+export const newRoute = (input: unknown) =>
+  Effect.gen(function*() {
+    const validated = yield* parseCreateRouteRequest(input)
+    return yield* createRoute(validated)
+  })
+
+/**
+ * Updates a route preserving creation time and ID
+ */
+export const updateRoute = (updates: Partial<typeof CreateRouteRequestSchema.Type>) => (existingRoute: Route) =>
+  Effect.gen(function*() {
+    const updateRequest = {
+      id: existingRoute.id,
+      path: updates.path ?? existingRoute.path,
+      method: updates.method ?? existingRoute.method,
+      response: updates.response ?? {
+        status: existingRoute.response.status,
+        headers: Option.getOrUndefined(existingRoute.response.headers),
+        body: existingRoute.response.body
+      },
+      delay: updates.delay ?? pipe(
+        existingRoute.delay,
+        Option.map(Duration.toMillis),
+        Option.getOrUndefined
+      )
+    }
+
+    const updated = yield* createRoute(updateRequest)
+
+    return Route({
+      ...updated,
+      createdAt: existingRoute.createdAt
+    })
+  })
+
+/**
+ * Substitutes parameters in a string using Effect's String utilities
+ */
+const substituteInString = (params: Record<string, string>) => (str: string): string =>
+  Object.entries(params).reduce((acc, [key, value]) => acc.replaceAll(`{{${key}}}`, value), str)
+
+/**
+ * Recursively substitutes parameters in unknown data structure
+ */
+export const substituteParams = (params: Record<string, string>) => (body: unknown): unknown => {
+  if (typeof body === "string") return substituteInString(params)(body)
+  if (Array.isArray(body)) return body.map(substituteParams(params))
+  // TypeScript narrows `typeof body === "object"` to `object | null`, but we've excluded null and Array above.
+  // The cast to Record<string, unknown> is necessary since TS cannot narrow `object` to an indexable type.
+  if (body !== null && typeof body === "object") {
+    return Object.fromEntries(
+      Object.entries(body as Record<string, unknown>).map(([k, v]) => [k, substituteParams(params)(v)])
+    )
+  }
+  return body
+}
+
+/**
+ * Creates a response with substituted parameters
+ */
+export const createResponseWithParams = (params: Record<string, string>) => (response: Response): Response =>
+  Response({
+    ...response,
+    body: substituteParams(params)(response.body)
+  })
+
+/**
+ * Extracts route summary for API responses
+ */
+export const toRouteSummary = (route: Route) => ({
+  id: route.id,
+  path: route.path,
+  method: route.method,
+  status: route.response.status,
+  hasDelay: Option.isSome(route.delay),
+  delayMs: pipe(
+    route.delay,
+    Option.map(Duration.toMillis),
+    Option.getOrUndefined
+  ),
+  createdAt: DateTime.formatIso(route.createdAt)
+})
+
+/**
+ * Gets delay in milliseconds for compatibility
+ */
+export const getDelayMillis = (route: Route): Option.Option<number> => Option.map(route.delay, Duration.toMillis)
+
+/**
+ * Checks if route has custom headers
+ */
+export const hasCustomHeaders = (route: Route): boolean => Option.isSome(route.response.headers)
+
+/**
+ * Gets headers as record or empty object
+ */
+export const getHeaders = (route: Route): Record<string, string> =>
+  pipe(
+    route.response.headers,
+    Option.getOrElse(() => ({}))
+  )
+
+/**
+ * Checks if route has delay configured
+ */
+export const hasDelay = (route: Route): boolean => Option.isSome(route.delay)
+
+/**
+ * Creates a minimal route for testing
+ */
+export const createMinimalRoute = (path: string) => (method: typeof HttpMethodSchema.Type = "GET") =>
+  Effect.gen(function*() {
+    const uuid = yield* Uuid
+    const id = yield* uuid.generateShort
+
+    return Route({
+      id,
+      path,
+      method,
+      response: Response({
+        status: 200,
+        headers: Option.none(),
+        body: { message: "OK" }
+      }),
+      delay: Option.none(),
+      createdAt: DateTime.unsafeNow()
+    })
+  })