import * as mm from "@distilled.cloud/aws/mailmanager";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, createTagsList, hasAlchemyTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import {
readMailManagerTags,
repeatUntilMailManagerStable,
retryWhileMailManagerConflict,
sameShape,
syncMailManagerTags,
} from "./internal.ts";
export class IngressPointUnexpectedResponse extends Data.TaggedError(
"IngressPointUnexpectedResponse",
)<{
readonly message: string;
readonly cause?: unknown;
}> {}
export interface IngressPointProps {
/**
* Name of the ingress point. If omitted, a deterministic physical name is
* generated from the app, stage, and logical ID. Renames apply in place.
*/
ingressPointName?: string;
/**
* Type of the ingress endpoint: `OPEN` accepts unauthenticated SMTP;
* `AUTH` requires SMTP AUTH credentials (see
* {@link IngressPointProps.ingressPointConfiguration}); `MTLS` requires
* client certificates. Immutable — changing the type replaces the ingress
* point.
*/
type: mm.IngressPointType;
/**
* ID of the rule set applied to email arriving through this ingress
* point. Updates apply in place.
*/
ruleSetId: string;
/**
* ID of the traffic policy evaluated against connections to this ingress
* point. Updates apply in place.
*/
trafficPolicyId: string;
/**
* Authentication configuration for `AUTH`/`MTLS` ingress points: an SMTP
* password, a Secrets Manager secret ARN, or a TLS trust store. Updates
* apply in place.
*/
ingressPointConfiguration?: mm.IngressPointConfiguration;
/**
* Network configuration: public (with IP type) or VPC-endpoint private.
* Immutable — changing it replaces the ingress point.
* @default public IPV4
*/
networkConfiguration?: mm.NetworkConfiguration;
/**
* TLS policy for inbound connections: `REQUIRED`, `OPTIONAL`, or `FIPS`.
* Omitting it applies AWS's `FIPS` default. Changes between `REQUIRED` and
* `OPTIONAL` update in place; AWS rejects updates from or to `FIPS`
* (including the omitted default), so those transitions replace the
* ingress point.
*/
tlsPolicy?: mm.TlsPolicy;
/**
* Tags applied to the ingress point. Alchemy ownership tags are merged in
* automatically.
*/
tags?: Record<string, string>;
}
export interface IngressPoint extends Resource<
"AWS.MailManager.IngressPoint",
IngressPointProps,
{
/** Server-assigned ID of the ingress point. */
ingressPointId: string;
/** ARN of the ingress point. */
ingressPointArn: string;
/** Name of the ingress point. */
ingressPointName: string;
/** DNS A record (SMTP endpoint host) of the ingress point. */
aRecord: string | undefined;
/** Current status (PROVISIONING, ACTIVE, CLOSED, FAILED, ...). */
status: string | undefined;
},
never,
Providers
> {}
/**
* An SES Mail Manager ingress point — the SMTP endpoint that receives
* incoming email, screens it with a traffic policy, and processes it with a
* rule set.
*
* `type` and `networkConfiguration` are immutable (changes replace the
* endpoint); everything else updates in place.
* ### Creating Ingress Points
* **Example:** Open Ingress Point
* ```typescript
* import * as MailManager from "@alchemy.run/aws/MailManager";
*
* const ruleSet = yield* MailManager.RuleSet("Inbound", {
* rules: [{ Name: "DropAll", Actions: [{ Drop: {} }] }],
* });
* const trafficPolicy = yield* MailManager.TrafficPolicy("Edge", {
* defaultAction: "ALLOW",
* });
* const ingress = yield* MailManager.IngressPoint("Smtp", {
* type: "OPEN",
* ruleSetId: ruleSet.ruleSetId,
* trafficPolicyId: trafficPolicy.trafficPolicyId,
* });
* // point your domain's MX record at ingress.aRecord
* ```
*
* **Example:** Authenticated Ingress Point
* ```typescript
* const ingress = yield* MailManager.IngressPoint("Smtp", {
* type: "AUTH",
* ruleSetId: ruleSet.ruleSetId,
* trafficPolicyId: trafficPolicy.trafficPolicyId,
* ingressPointConfiguration: { SecretArn: secret.secretArn },
* tlsPolicy: "REQUIRED",
* });
* ```
*
* @resource
*/
export const IngressPoint = Resource<IngressPoint>("AWS.MailManager.IngressPoint");
export const IngressPointProvider = () =>
Provider.effect(
IngressPoint,
Effect.gen(function* () {
const createName = Effect.fn(function* (id: string, props: { ingressPointName?: string }) {
return (
props.ingressPointName ??
(yield* createPhysicalName({ id, maxLength: 63, lowercase: true }))
);
});
const getById = (ingressPointId: string) =>
mm
.getIngressPoint({ IngressPointId: ingressPointId })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
const findByName = (name: string) =>
mm.listIngressPoints.pages({}).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk)
.flatMap((page) => page.IngressPoints ?? [])
.find((p) => p.IngressPointName === name),
),
);
const observe = Effect.fn(function* (
output: IngressPoint["Attributes"] | undefined,
name: string,
) {
if (output?.ingressPointId !== undefined) {
const found = yield* getById(output.ingressPointId);
if (found !== undefined) return found;
}
const summary = yield* findByName(name);
if (summary?.IngressPointId === undefined) return undefined;
return yield* getById(summary.IngressPointId);
});
// Provisioning/updating is asynchronous — wait (bounded, ~2 min) for
// the endpoint to leave its transitional state before mutating it.
const waitForStable = (ingressPointId: string) =>
repeatUntilMailManagerStable(
getById(ingressPointId),
(r) => r === undefined || (r.Status !== "PROVISIONING" && r.Status !== "UPDATING"),
);
const toAttrs = Effect.fn(function* (ingress: mm.GetIngressPointResponse) {
if (ingress.IngressPointArn === undefined) {
return yield* new IngressPointUnexpectedResponse({
message: `Mail Manager ingress point '${ingress.IngressPointId}' returned without an ARN`,
});
}
return {
ingressPointId: ingress.IngressPointId,
ingressPointArn: ingress.IngressPointArn,
ingressPointName: ingress.IngressPointName,
aRecord: ingress.ARecord,
status: ingress.Status,
};
});
return IngressPoint.Provider.of({
stables: ["ingressPointId", "ingressPointArn"],
list: () =>
mm.listIngressPoints.pages({}).pipe(
Stream.runCollect,
Effect.flatMap((chunk) =>
Effect.forEach(
Array.from(chunk)
.flatMap((page) => page.IngressPoints ?? [])
.map((p) => p.IngressPointId),
(ingressPointId) => getById(ingressPointId),
),
),
Effect.flatMap((results) =>
Effect.forEach(
results.flatMap((p) => (p === undefined ? [] : [p])),
(p) => toAttrs(p),
),
),
),
read: Effect.fn(function* ({ id, olds, output }) {
const name = output?.ingressPointName ?? (yield* createName(id, olds ?? {}));
const ingress = yield* observe(output, name);
if (ingress === undefined) return undefined;
const attrs = yield* toAttrs(ingress);
const tags = yield* readMailManagerTags(attrs.ingressPointArn);
return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
}),
// `type` and `networkConfiguration` are create-only — changing
// either replaces the ingress point. TlsPolicy transitions from or
// to FIPS (including the omitted-default, which AWS creates as
// FIPS) are rejected by UpdateIngressPoint, so they replace too.
diff: Effect.fn(function* ({ news, olds }) {
if (!isResolved(news)) return undefined;
if (olds === undefined) return undefined;
if (olds.type !== news.type) {
return { action: "replace" } as const;
}
if (!sameShape(olds.networkConfiguration, news.networkConfiguration)) {
return { action: "replace" } as const;
}
if (olds.tlsPolicy !== news.tlsPolicy) {
const fipsInvolved =
olds.tlsPolicy === undefined ||
news.tlsPolicy === undefined ||
olds.tlsPolicy === "FIPS" ||
news.tlsPolicy === "FIPS";
if (fipsInvolved) return { action: "replace" } as const;
}
}),
reconcile: Effect.fn(function* ({ id, news, olds, output, session }) {
const name = yield* createName(id, news);
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...news.tags, ...internalTags };
// 1. OBSERVE.
let ingress = yield* observe(output, name);
// 2. ENSURE — create if missing; a Conflict race re-observes.
if (ingress === undefined) {
yield* session.note(`creating ingress point ${name}`);
const created = yield* mm
.createIngressPoint({
IngressPointName: name,
Type: news.type,
RuleSetId: news.ruleSetId,
TrafficPolicyId: news.trafficPolicyId,
IngressPointConfiguration: news.ingressPointConfiguration,
NetworkConfiguration: news.networkConfiguration,
TlsPolicy: news.tlsPolicy,
Tags: createTagsList(desiredTags),
})
.pipe(Effect.catchTag("ConflictException", () => Effect.undefined));
ingress =
created !== undefined
? yield* getById(created.IngressPointId)
: yield* observe(undefined, name);
}
if (ingress === undefined) {
return yield* new IngressPointUnexpectedResponse({
message: `Mail Manager ingress point '${name}' not found after create`,
});
}
// Provisioning is asynchronous — settle before mutating.
const settled = yield* waitForStable(ingress.IngressPointId);
ingress = settled ?? ingress;
// 3. SYNC — diff OBSERVED state against desired. The auth
// configuration is write-only (the Get response only exposes
// password versions / secret ARN), so `olds` is used as a hint
// to push it when the prop changed.
const configChanged =
news.ingressPointConfiguration !== undefined &&
!sameShape(olds?.ingressPointConfiguration, news.ingressPointConfiguration);
// AWS rejects any update from or to FIPS — those transitions go
// through replacement (see diff), so only non-FIPS deltas are
// pushed here.
const tlsChanged =
news.tlsPolicy !== undefined &&
news.tlsPolicy !== "FIPS" &&
ingress.TlsPolicy !== "FIPS" &&
ingress.TlsPolicy !== news.tlsPolicy;
if (
ingress.IngressPointName !== name ||
ingress.RuleSetId !== news.ruleSetId ||
ingress.TrafficPolicyId !== news.trafficPolicyId ||
tlsChanged ||
configChanged
) {
yield* mm.updateIngressPoint({
IngressPointId: ingress.IngressPointId,
IngressPointName: name,
RuleSetId: news.ruleSetId,
TrafficPolicyId: news.trafficPolicyId,
IngressPointConfiguration: configChanged ? news.ingressPointConfiguration : undefined,
TlsPolicy: tlsChanged ? news.tlsPolicy : undefined,
});
const updated = yield* waitForStable(ingress.IngressPointId);
ingress = updated ?? ingress;
}
// 3b. SYNC TAGS.
const attrs = yield* toAttrs(ingress);
yield* syncMailManagerTags(attrs.ingressPointArn, desiredTags);
yield* session.note(attrs.ingressPointId);
return { ...attrs, ingressPointName: name };
}),
delete: Effect.fn(function* ({ output }) {
// Deleting mid-provision conflicts — retry through the window.
yield* retryWhileMailManagerConflict(
mm.deleteIngressPoint({ IngressPointId: output.ingressPointId }),
).pipe(
Effect.asVoid,
Effect.catchTag("ResourceNotFoundException", () => Effect.void),
);
// Deprovisioning is asynchronous and the endpoint keeps its rule
// set and traffic policy "in use" until it is fully gone — wait
// (bounded, ~3 min) so dependent deletes don't conflict.
yield* repeatUntilMailManagerStable(
getById(output.ingressPointId),
(r) => r === undefined,
36,
);
}),
});
}),
);