import * as appsync from "@distilled.cloud/aws/appsync";
import { isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { retryConcurrentModification } from "./common.ts";
import type { GraphqlApi } from "./GraphqlApi.ts";
export interface ApiKeyProps {
/**
* ID of the GraphQL API. Usually derived from `api.apiId` by the
* {@link ApiKey} wrapper.
*/
apiId: string;
/** Description of the key. */
description?: string;
/**
* Expiry as epoch seconds, between 1 and 365 days from creation. AWS
* rounds the value **down to the nearest hour**. When omitted, the key
* expires 7 days after creation and expiry is left unmanaged.
*/
expires?: number;
}
export interface AppSyncApiKey extends Resource<
"AWS.AppSync.ApiKey",
ApiKeyProps,
{
/** The API this key belongs to. */
apiId: string;
/**
* The API key ID — this IS the secret key value (`da2-…`) clients send
* in the `x-api-key` header. Wrapped in `Redacted` — unwrap with
* `Redacted.value(key.id)` where the raw header value is needed.
*/
id: Redacted.Redacted<string>;
/** The key's expiry (epoch seconds, rounded down to the hour). */
expires: number | undefined;
/** The key's description. */
description: string | undefined;
},
never,
Providers
> {}
/**
* An AppSync API key for `API_KEY`-authenticated GraphQL APIs.
*
* The key's `id` attribute is the secret value (`da2-…`) sent in the
* `x-api-key` request header. It is wrapped in `Redacted`; unwrap with
* `Redacted.value(key.id)` where the raw header value is needed.
* ### Creating API Keys
* **Example:** Key with the default 7-day expiry
* ```typescript
* const key = yield* AppSync.ApiKey("Key", { api });
* // Redacted.value(key.id) → "da2-…" — send as the x-api-key header
* ```
*
* **Example:** Key with a managed expiry
* ```typescript
* const key = yield* AppSync.ApiKey("Key", {
* api,
* description: "mobile clients",
* expires: 1893456000, // rounded down to the hour by AWS
* });
* ```
*
* @resource
*/
export const ApiKeyResource = Resource<AppSyncApiKey>("AWS.AppSync.ApiKey");
export interface ApiKeyInputProps extends Omit<
{
[K in keyof ApiKeyProps]?: Input<ApiKeyProps[K]>;
},
"apiId"
> {
/**
* The `GraphqlApi` this key belongs to (preferred). Alternatively pass a
* raw `apiId`.
*/
api?: GraphqlApi;
apiId?: Input<string>;
}
/**
* User-facing wrapper for the ApiKey resource. Accepts `api: GraphqlApi`
* as the idiomatic way to mint a key for an API.
*/
export const ApiKey = (id: string, props: ApiKeyInputProps = {}) =>
Effect.gen(function* () {
const { api, ...rest } = props;
const apiId = rest.apiId ?? api?.apiId;
if (!apiId) {
return yield* Effect.die("ApiKey requires either `api` (preferred) or an explicit `apiId`.");
}
return yield* ApiKeyResource(id, { ...rest, apiId } as any);
});
/** AWS rounds key expiry down to the nearest hour. */
const floorToHour = (epochSeconds: number): number => Math.floor(epochSeconds / 3600) * 3600;
export const ApiKeyProvider = () =>
Provider.effect(
ApiKeyResource,
Effect.gen(function* () {
/** Find a key by its ID (keys have no other stable identity). */
const findKey = Effect.fn(function* (apiId: string, keyId: string) {
const pages = yield* appsync.listApiKeys.pages({ apiId }).pipe(
Stream.runCollect,
Effect.catchTag("NotFoundException", () => Effect.succeed([])),
);
return Array.from(pages)
.flatMap((page) => page.apiKeys ?? [])
.find((key) => key.id === keyId);
});
const toAttributes = (apiId: string, key: appsync.ApiKey): AppSyncApiKey["Attributes"] => ({
apiId,
// The key id doubles as the secret `x-api-key` header value.
id: Redacted.make(key.id!),
expires: key.expires,
description: key.description,
});
return ApiKeyResource.Provider.of({
stables: ["apiId", "id"],
// Sub-resource keyed entirely by its GraphQL API (apiId) with no global
// enumeration API of its own — nuke reaches it through the parent's
// deletion, so enumeration returns empty per the ProviderService
// doctrine.
list: () => Effect.succeed([]),
read: Effect.fn(function* ({ output }) {
// Keys carry no deterministic identity — without the cached id
// there is nothing to look up (a fresh reconcile will mint one).
if (output?.id === undefined) return undefined;
const key = yield* findKey(output.apiId, Redacted.value(output.id));
if (key?.id == null) return undefined;
return toAttributes(output.apiId, key);
}),
diff: Effect.fn(function* ({ news, olds }) {
if (!isResolved(news)) return undefined;
if (news.apiId !== olds.apiId) {
return { action: "replace" } as const;
}
// description/expires converge via updateApiKey
}),
reconcile: Effect.fn(function* ({ news, output, session }) {
const apiId = output?.apiId ?? news.apiId;
// 1. OBSERVE — the cached key id is the only handle.
let observed =
output?.id !== undefined ? yield* findKey(apiId, Redacted.value(output.id)) : undefined;
if (observed?.id == null) {
// 2. ENSURE
const created = yield* retryConcurrentModification(
appsync.createApiKey({
apiId,
description: news.description,
expires: news.expires,
}),
);
observed = created.apiKey!;
yield* session.note(`Created API key for ${apiId}`);
} else {
// 3. SYNC — update description/expiry on drift (expiry only
// when managed by props; AWS floors it to the hour).
const expiresDrifted =
news.expires !== undefined && observed.expires !== floorToHour(news.expires);
const descriptionDrifted =
news.description !== undefined && observed.description !== news.description;
if (expiresDrifted || descriptionDrifted) {
const updated = yield* retryConcurrentModification(
appsync.updateApiKey({
apiId,
id: observed.id,
description: news.description,
expires: news.expires,
}),
);
observed = updated.apiKey ?? observed;
yield* session.note(`Updated API key ${observed.id}`);
}
}
return toAttributes(apiId, observed);
}),
delete: Effect.fn(function* ({ output }) {
yield* retryConcurrentModification(
appsync
.deleteApiKey({
apiId: output.apiId,
id: Redacted.value(output.id),
})
.pipe(Effect.catchTag("NotFoundException", () => Effect.void)),
);
}),
});
}),
);