import * as ag from "@distilled.cloud/aws/api-gateway";
import { deepEqual, isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { toWireMillis } from "alchemy/Util/Duration";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import type { RestApi } from "./RestApi.ts";
/**
* Integration configuration for an API Gateway method (passed to `putIntegration`).
*/
export interface MethodIntegrationProps {
/** Integration type: `AWS`, `AWS_PROXY`, `HTTP`, `HTTP_PROXY`, or `MOCK`. */
type: ag.IntegrationType;
/** HTTP method used to call the backend (always `POST` for Lambda integrations). */
integrationHttpMethod?: string;
/** Integration endpoint URI (Lambda invocation ARN or HTTP URL). */
uri?: Input<string>;
/** `VPC_LINK` for private integrations, otherwise `INTERNET`. */
connectionType?: ag.ConnectionType;
/** ID of the `VpcLink` when `connectionType` is `VPC_LINK`. */
connectionId?: string;
/**
* IAM role ARN used by API Gateway for integration credentials.
*
* This is not a secret value; API Gateway stores an ARN or passthrough marker.
*/
credentials?: string;
/** Maps integration request parameters from method request parameters. */
requestParameters?: { [key: string]: string | undefined };
/** Request body mapping templates keyed by content type. */
requestTemplates?: { [key: string]: string | undefined };
/** How unmapped content types pass through (`WHEN_NO_MATCH`, `WHEN_NO_TEMPLATES`, `NEVER`). */
passthroughBehavior?: string;
/** Cache namespace for integration responses. */
cacheNamespace?: string;
/** Request parameters whose values form the cache key. */
cacheKeyParameters?: string[];
/** Payload encoding conversion (`CONVERT_TO_BINARY` or `CONVERT_TO_TEXT`). */
contentHandling?: ag.ContentHandlingStrategy;
/**
* Integration timeout (e.g. `"29 seconds"` or `Duration.seconds(29)`;
* a bare number is milliseconds). Sent to the API in milliseconds
* (`timeoutInMillis`).
*/
timeout?: Duration.Input;
/** TLS settings for HTTP integrations (e.g. `insecureSkipVerification`). */
tlsConfig?: ag.TlsConfig;
/** How the integration response is transferred to the client. */
responseTransferMode?: ag.ResponseTransferMode;
/** Target resource of the integration, where the API distinguishes one from `uri`. */
integrationTarget?: string;
}
export interface MethodProps {
/**
* The `RestApi` this method lives on. When supplied, the method auto-binds
* itself to the API so that any `Deployment` of this API waits for the
* method to be created before snapshotting.
*
* When `restApi` is provided, `resourceId` defaults to `restApi.rootResourceId`,
* which is the common case for methods on the API root (`/`). Pass an
* explicit `resourceId` when targeting a sub-path defined by
* `ApiGateway.Resource`.
*
* Passing a raw `restApiId` instead is still supported but opts out of
* automatic deployment ordering — you must then manage `Deployment.triggers`
* yourself.
*/
restApi?: RestApi;
/**
* ID of the REST API. Usually derived from `restApi.restApiId`; supply
* explicitly only when not using `restApi`.
*/
restApiId?: Input<string>;
/**
* ID of the API Gateway Resource this method attaches to. Defaults to
* `restApi.rootResourceId` when `restApi` is provided.
*/
resourceId?: Input<string>;
/** HTTP verb, e.g. `GET`, `POST`, `ANY`. */
httpMethod: string;
/**
* Authorization type (`NONE`, `IAM`, `CUSTOM`, `COGNITO_USER_POOLS`, etc.).
* @default "NONE"
*/
authorizationType?: string;
/** ID of the `Authorizer` when `authorizationType` is `CUSTOM` or `COGNITO_USER_POOLS`. */
authorizerId?: string;
/** Require callers to present an API key. */
apiKeyRequired?: boolean;
/** Friendly operation name (e.g. for SDK generation). */
operationName?: string;
/** Accepted request parameters; `true` marks a parameter required. */
requestParameters?: { [key: string]: boolean | undefined };
/** Request body models keyed by content type. */
requestModels?: { [key: string]: string | undefined };
/** ID of a request validator applied to this method. */
requestValidatorId?: string;
/** OAuth scopes for `COGNITO_USER_POOLS` authorization. */
authorizationScopes?: string[];
/** When set, `putIntegration` is applied after `putMethod`. */
integration?: MethodIntegrationProps;
}
export interface MethodType extends Resource<
"AWS.ApiGateway.Method",
MethodProps,
{
restApiId: string;
resourceId: string;
httpMethod: string;
authorizationType: string;
authorizerId: string | undefined;
apiKeyRequired: boolean | undefined;
operationName: string | undefined;
requestParameters: { [key: string]: boolean | undefined } | undefined;
requestModels: { [key: string]: string | undefined } | undefined;
requestValidatorId: string | undefined;
authorizationScopes: string[] | undefined;
integration: MethodIntegrationProps | undefined;
},
never,
Providers
> {}
/**
* An HTTP method on an API Gateway Resource.
*
* A `Method` is a single HTTP verb (`GET`, `POST`, `ANY`, …) attached to a
* REST API resource path. Most methods also carry an `integration` — the
* downstream target that actually handles the request (a Lambda function,
* an HTTP endpoint, a mock response, etc.).
* ### Binding to a RestApi
* Pass the `RestApi` value on `restApi`. This threads the API id through
* and registers the method as a `RestApiBinding` on the API, so that any
* `Deployment` of the same API is automatically ordered after this method
* completes. You do not need to manage `Deployment.triggers` yourself.
*
* **Example:** GET on the API root with a mock integration
* ```typescript
* yield* ApiGateway.Method("GetRoot", {
* restApi: api,
* httpMethod: "GET",
* authorizationType: "NONE",
* integration: { type: "MOCK" },
* });
* ```
*
* ### Lambda proxy integration
* For Lambda-backed APIs, the integration `uri` follows the
* `arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/<function-arn>/invocations`
* shape. Use `Output.map` to resolve the function ARN before building the
* URI, since the function's ARN is only known at deploy time.
*
* **Example:** ANY method with Lambda AWS_PROXY integration
* ```typescript
* import * as Output from "alchemy/Output";
*
* const invokeUri = Output.map(
* fn.functionArn,
* (arn) =>
* `arn:aws:apigateway:${region}:lambda:path/2015-03-31/functions/${arn}/invocations`,
* );
*
* yield* ApiGateway.Method("RootAny", {
* restApi: api,
* httpMethod: "ANY",
* authorizationType: "NONE",
* integration: {
* type: "AWS_PROXY",
* integrationHttpMethod: "POST",
* uri: invokeUri,
* },
* });
* ```
*
* ### Methods on sub-paths
* Attach a method to a nested path by creating an `ApiGateway.Resource` and
* passing its `resourceId` explicitly. `restApi` is still required so the
* method binds for deployment ordering.
*
* **Example:** Method on `/items`
* ```typescript
* const items = yield* ApiGateway.Resource("Items", {
* restApi: api,
* parentId: api.rootResourceId,
* pathPart: "items",
* });
*
* yield* ApiGateway.Method("ListItems", {
* restApi: api,
* resourceId: items.resourceId,
* httpMethod: "GET",
* authorizationType: "NONE",
* integration: { type: "MOCK" },
* });
* ```
*
* @resource
*/
export const MethodResource = Resource<MethodType>("AWS.ApiGateway.Method");
/**
* `Input`-accepting mirror of {@link MethodProps} used by the `Method`
* wrapper function — see {@link MethodProps} for per-field documentation.
*/
export interface MethodInputProps {
restApi?: RestApi;
restApiId?: Input<string>;
resourceId?: Input<string>;
httpMethod: Input<string>;
authorizationType?: Input<string>;
authorizerId?: Input<string>;
apiKeyRequired?: Input<boolean>;
operationName?: Input<string>;
requestParameters?: Input<MethodProps["requestParameters"]>;
requestModels?: Input<MethodProps["requestModels"]>;
requestValidatorId?: Input<string>;
authorizationScopes?: Input<string[]>;
integration?: Input<MethodIntegrationProps>;
}
const MethodImpl = (id: string, props: MethodInputProps) =>
Effect.gen(function* () {
const { restApi, ...rest } = props;
const restApiId = rest.restApiId ?? restApi?.restApiId;
const resourceId = rest.resourceId ?? restApi?.rootResourceId;
if (!restApiId || !resourceId) {
return yield* Effect.die(
"Method requires either `restApi` (preferred) or explicit " +
"`restApiId` and `resourceId`.",
);
}
const method = yield* MethodResource(id, {
...rest,
restApiId,
resourceId,
} as any);
if (restApi) {
yield* restApi.bind`${method}`({
kind: "method",
methodId: method.LogicalId,
restApiId: method.restApiId,
resourceId: method.resourceId,
httpMethod: method.httpMethod,
});
}
return method;
});
/**
* User-facing wrapper for the Method resource. Accepts `restApi: RestApi`
* as the idiomatic way to attach a method — this both forwards the API id
* and registers the method as a binding on the RestApi so the scheduler
* orders `Deployment` after it.
*/
export const Method = MethodImpl;
const putIntegrationRequest = (
restApiId: string,
resourceId: string,
httpMethod: string,
integration: MethodIntegrationProps,
): ag.PutIntegrationRequest => ({
restApiId,
resourceId,
httpMethod,
type: integration.type,
integrationHttpMethod: integration.integrationHttpMethod,
uri: integration.uri as string,
connectionType: integration.connectionType,
connectionId: integration.connectionId,
credentials: integration.credentials,
requestParameters: integration.requestParameters,
requestTemplates: integration.requestTemplates,
passthroughBehavior: integration.passthroughBehavior,
cacheNamespace: integration.cacheNamespace,
cacheKeyParameters: integration.cacheKeyParameters,
contentHandling: integration.contentHandling,
timeoutInMillis: toWireMillis(integration.timeout),
tlsConfig: integration.tlsConfig,
responseTransferMode: integration.responseTransferMode,
integrationTarget: integration.integrationTarget,
});
const putMethod = (news: Input.ResolveProps<MethodProps>) =>
ag.putMethod({
restApiId: news.restApiId as string,
resourceId: news.resourceId as string,
httpMethod: news.httpMethod,
authorizationType: news.authorizationType ?? "NONE",
authorizerId: news.authorizerId,
apiKeyRequired: news.apiKeyRequired,
operationName: news.operationName,
requestParameters: news.requestParameters,
requestModels: news.requestModels,
requestValidatorId: news.requestValidatorId,
authorizationScopes: news.authorizationScopes,
});
const deleteIntegrationSafe = (p: { restApiId: string; resourceId: string; httpMethod: string }) =>
ag
.deleteIntegration({
restApiId: p.restApiId,
resourceId: p.resourceId,
httpMethod: p.httpMethod,
})
.pipe(Effect.catchTag("NotFoundException", () => Effect.void));
const deleteMethodSafe = (p: { restApiId: string; resourceId: string; httpMethod: string }) =>
ag
.deleteMethod({
restApiId: p.restApiId,
resourceId: p.resourceId,
httpMethod: p.httpMethod,
})
.pipe(Effect.catchTag("NotFoundException", () => Effect.void));
const readMethodSnapshot = (p: { restApiId: string; resourceId: string; httpMethod: string }) =>
Effect.gen(function* () {
const method = yield* ag
.getMethod({
restApiId: p.restApiId,
resourceId: p.resourceId,
httpMethod: p.httpMethod,
})
.pipe(Effect.catchTag("NotFoundException", () => Effect.undefined));
if (!method?.httpMethod) return undefined;
const integ = yield* ag
.getIntegration({
restApiId: p.restApiId,
resourceId: p.resourceId,
httpMethod: p.httpMethod,
})
.pipe(Effect.catchTag("NotFoundException", () => Effect.undefined));
const integration: MethodIntegrationProps | undefined = integ?.type
? {
type: integ.type!,
integrationHttpMethod: integ.httpMethod,
uri: integ.uri,
connectionType: integ.connectionType,
connectionId: integ.connectionId,
credentials: integ.credentials,
requestParameters: integ.requestParameters,
requestTemplates: integ.requestTemplates,
passthroughBehavior: integ.passthroughBehavior,
cacheNamespace: integ.cacheNamespace,
cacheKeyParameters: integ.cacheKeyParameters,
contentHandling: integ.contentHandling,
// Wire milliseconds — a plain number is a valid `Duration.Input`,
// so the observed snapshot stays directly comparable to a desired
// spec normalized via `toWireMillis`.
timeout: integ.timeoutInMillis,
tlsConfig: integ.tlsConfig,
responseTransferMode: integ.responseTransferMode,
integrationTarget: integ.integrationTarget,
}
: undefined;
return {
restApiId: p.restApiId,
resourceId: p.resourceId,
httpMethod: p.httpMethod,
authorizationType: method.authorizationType ?? "NONE",
authorizerId: method.authorizerId,
apiKeyRequired: method.apiKeyRequired,
operationName: method.operationName,
requestParameters: method.requestParameters,
requestModels: method.requestModels,
requestValidatorId: method.requestValidatorId,
authorizationScopes: method.authorizationScopes,
integration,
};
});
export const MethodProvider = () =>
Provider.effect(
MethodResource,
Effect.gen(function* () {
return {
stables: ["restApiId", "resourceId", "httpMethod"] as const,
diff: Effect.fn(function* ({ news: newsIn, olds }) {
if (!isResolved(newsIn)) return;
const news = newsIn as Input.ResolveProps<MethodProps>;
if (
news.restApiId !== olds.restApiId ||
news.resourceId !== olds.resourceId ||
news.httpMethod !== olds.httpMethod
) {
return { action: "replace" } as const;
}
}),
read: Effect.fn(function* ({ output }) {
if (!output) return undefined;
return yield* readMethodSnapshot({
restApiId: output.restApiId,
resourceId: output.resourceId,
httpMethod: output.httpMethod,
});
}),
// Methods are sub-resources keyed by (restApiId, resourceId,
// httpMethod) with no dedicated list-methods API. Enumerate every
// RestApi -> each Resource (embedding its method verbs) -> read each
// method snapshot so every item matches the exact `read` Attributes
// shape (including integration), directly usable by `delete`.
list: () =>
Effect.gen(function* () {
const restApis = yield* ag.getRestApis.pages({}).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.items ?? []).filter(
(api): api is ag.RestApi & { id: string } => api.id != null,
),
),
),
);
const perApi = yield* Effect.forEach(
restApis,
(api) =>
Effect.gen(function* () {
const resources = yield* ag.getResources
.pages({ restApiId: api.id, embed: ["methods"] })
.pipe(
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.items ?? [])),
);
const keys = resources.flatMap((resource) =>
resource.id
? Object.keys(resource.resourceMethods ?? {}).map((httpMethod) => ({
resourceId: resource.id as string,
httpMethod,
}))
: [],
);
const snaps = yield* Effect.forEach(
keys,
(key) =>
readMethodSnapshot({
restApiId: api.id,
resourceId: key.resourceId,
httpMethod: key.httpMethod,
}),
{ concurrency: 10 },
);
return snaps.filter(
(snap): snap is NonNullable<typeof snap> => snap !== undefined,
);
}),
{ concurrency: 5 },
);
return perApi.flat();
}),
reconcile: Effect.fn(function* ({ news: newsIn, output, session }) {
if (!isResolved(newsIn)) {
return yield* Effect.die("Method props were not resolved");
}
const news = newsIn as Input.ResolveProps<MethodProps>;
const authType = news.authorizationType ?? "NONE";
// Methods are keyed by (restApiId, resourceId, httpMethod). All
// three are stable across the resource's lifetime, so we read
// them out of `output` when present and fall back to `news`.
const restApiId = (output?.restApiId ?? news.restApiId) as string;
const resourceId = (output?.resourceId ?? news.resourceId) as string;
const httpMethod = output?.httpMethod ?? news.httpMethod;
// Observe — read live method + integration as a single snapshot.
// `output.*` fields are never trusted as proxies for cloud state;
// they're at most a cache for the natural-key tuple above.
let observed = yield* readMethodSnapshot({
restApiId,
resourceId,
httpMethod,
});
// Ensure — putMethod creates the method shape (auth type,
// request models, scopes, etc.). Some of those fields cannot be
// patched in place by `updateMethod`, so on a "recreate-needed"
// diff we drop the existing method and re-put. This is also the
// path used on first reconcile when nothing exists.
const needsRecreate =
observed !== undefined &&
(news.operationName !== observed.operationName ||
!deepEqual(news.requestParameters, observed.requestParameters) ||
!deepEqual(news.requestModels, observed.requestModels) ||
news.requestValidatorId !== observed.requestValidatorId ||
!deepEqual(news.authorizationScopes, observed.authorizationScopes));
if (observed === undefined || needsRecreate) {
if (needsRecreate) {
yield* deleteIntegrationSafe({
restApiId,
resourceId,
httpMethod,
});
yield* deleteMethodSafe({ restApiId, resourceId, httpMethod });
}
yield* putMethod({
...news,
restApiId,
resourceId,
httpMethod,
});
if (news.integration) {
yield* ag.putIntegration(
putIntegrationRequest(restApiId, resourceId, httpMethod, news.integration),
);
}
yield* session.note(
needsRecreate
? `Recreated method ${httpMethod}`
: `Put method ${httpMethod} on resource ${resourceId}`,
);
// Re-read to get the canonical observed state for the rest of
// the reconciler. After a recreate everything matches `news`,
// so the patch step below becomes a no-op.
observed = yield* readMethodSnapshot({
restApiId,
resourceId,
httpMethod,
});
if (!observed) {
return yield* Effect.die("getMethod missing after put");
}
}
// Sync patchable scalar fields — observed ↔ desired.
const patches: ag.PatchOperation[] = [];
if (authType !== observed.authorizationType) {
patches.push({
op: "replace",
path: "/authorizationType",
value: authType,
});
}
if (news.authorizerId !== observed.authorizerId) {
patches.push({
op: "replace",
path: "/authorizerId",
value: news.authorizerId ?? "",
});
}
if (news.apiKeyRequired !== observed.apiKeyRequired) {
patches.push({
op: "replace",
path: "/apiKeyRequired",
value: String(news.apiKeyRequired ?? false),
});
}
if (patches.length > 0) {
yield* ag.updateMethod({
restApiId,
resourceId,
httpMethod,
patchOperations: patches,
});
}
// Sync integration — putIntegration is an upsert; deleteIntegration
// tolerates missing integrations. Normalize the desired timeout to
// wire milliseconds so it compares against the observed snapshot.
const desiredIntegration = news.integration && {
...news.integration,
timeout: toWireMillis(news.integration.timeout),
};
if (!deepEqual(desiredIntegration, observed.integration)) {
if (news.integration) {
yield* ag.putIntegration(
putIntegrationRequest(restApiId, resourceId, httpMethod, news.integration),
);
} else {
yield* deleteIntegrationSafe({
restApiId,
resourceId,
httpMethod,
});
}
}
yield* session.note(`Reconciled method ${httpMethod}`);
const snap = yield* readMethodSnapshot({
restApiId,
resourceId,
httpMethod,
});
if (!snap) {
return yield* Effect.die("getMethod missing after reconcile");
}
return snap;
}),
delete: Effect.fn(function* ({ output, session }) {
yield* deleteIntegrationSafe({
restApiId: output.restApiId,
resourceId: output.resourceId,
httpMethod: output.httpMethod,
});
yield* deleteMethodSafe({
restApiId: output.restApiId,
resourceId: output.resourceId,
httpMethod: output.httpMethod,
});
yield* session.note(`Deleted method ${output.httpMethod}`);
}),
};
}),
);