@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 316 lines 11.3 KB
Raw
1 import * as ddos from "@distilled.cloud/cloudflare/ddos-protection";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import * as Effect from "effect/Effect";
7 import * as Predicate from "effect/Predicate";
8 import * as Stream from "effect/Stream";
9 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
10 import type { Providers } from "../Providers.ts";
11
12 const TypeId = "Cloudflare.DdosProtection.SynProtectionRule" as const;
13 type TypeId = typeof TypeId;
14
15 /**
16 * Operating mode of an Advanced TCP Protection rule: actively mitigate
17 * (`enabled`), observe only (`monitoring`), or stand down (`disabled`).
18 */
19 export type SynProtectionRuleMode = "enabled" | "disabled" | "monitoring";
20
21 /**
22 * Where a SYN Protection rule applies: every prefix (`global`), one
23 * Cloudflare region (`region`), or one data center (`datacenter`).
24 */
25 export type SynProtectionRuleScope = "global" | "region" | "datacenter";
26
27 /**
28 * Sensitivity of the SYN Protection thresholds.
29 */
30 export type SynProtectionRuleSensitivity = "low" | "medium" | "high";
31
32 /**
33 * How SYN Protection mitigates matched floods.
34 */
35 export type SynProtectionMitigationType = "challenge" | "retransmit";
36
37 export interface SynProtectionRuleProps {
38 /**
39 * The scope of the rule: `global`, `region`, or `datacenter`.
40 *
41 * Immutable — the API only patches mode/sensitivities, so changing the
42 * scope triggers a replacement.
43 */
44 scope: SynProtectionRuleScope;
45 /**
46 * The name of the rule, relative to `scope`: for `global` scope the name
47 * is `global`; for `region`/`datacenter` scope it is the region or data
48 * center name (e.g. `WEUR`, `SJC`).
49 *
50 * Immutable — changing the name triggers a replacement.
51 * @default "global"
52 */
53 name?: string;
54 /**
55 * Operating mode of the rule. Mutable — patched in place.
56 */
57 mode: SynProtectionRuleMode;
58 /**
59 * The burst sensitivity. Mutable — patched in place.
60 */
61 burstSensitivity: SynProtectionRuleSensitivity;
62 /**
63 * The rate sensitivity. Mutable — patched in place.
64 */
65 rateSensitivity: SynProtectionRuleSensitivity;
66 /**
67 * The type of mitigation applied to matched SYN floods. Mutable —
68 * patched in place.
69 * @default "challenge"
70 */
71 mitigationType?: SynProtectionMitigationType;
72 }
73
74 export interface SynProtectionRuleAttributes {
75 /** Cloudflare-assigned identifier of the SYN Protection rule. */
76 ruleId: string;
77 /** The Cloudflare account the rule belongs to. */
78 accountId: string;
79 /** The scope of the rule. */
80 scope: SynProtectionRuleScope;
81 /** The name of the rule, relative to its scope. */
82 name: string;
83 /** Operating mode of the rule. */
84 mode: SynProtectionRuleMode;
85 /** The burst sensitivity. */
86 burstSensitivity: SynProtectionRuleSensitivity;
87 /** The rate sensitivity. */
88 rateSensitivity: SynProtectionRuleSensitivity;
89 /** The type of mitigation applied to matched SYN floods. */
90 mitigationType: SynProtectionMitigationType;
91 /** ISO8601 creation timestamp. */
92 createdOn: string;
93 /** ISO8601 last-modified timestamp. */
94 modifiedOn: string;
95 }
96
97 export type SynProtectionRule = Resource<
98 TypeId,
99 SynProtectionRuleProps,
100 SynProtectionRuleAttributes,
101 never,
102 Providers
103 >;
104
105 /**
106 * An Advanced TCP Protection SYN flood rule (Magic Transit).
107 *
108 * Rules tune how Cloudflare mitigates SYN floods on Magic Transit prefixes,
109 * per scope (`global`, a region, or a data center). The rule's identity is
110 * its `scope` + `name` pair — only `mode`, sensitivities, and
111 * `mitigationType` are mutable in place.
112 *
113 * Requires the **Magic Transit / Advanced TCP Protection** entitlement; on
114 * accounts without it every API call fails with the typed
115 * `AdvancedTcpProtectionNotEntitled` error.
116 *
117 * Safety: rules carry no ownership markers. When there is no prior state,
118 * `read` scans for an existing rule with the same scope + name and reports
119 * it as `Unowned`, so the engine refuses to take it over unless `--adopt`
120 * (or `adopt(true)`) is set.
121 * ### Creating a rule
122 * **Example:** Global SYN protection in monitoring mode
123 * ```typescript
124 * const rule = yield* Cloudflare.DdosProtection.SynProtectionRule("GlobalSyn", {
125 * scope: "global",
126 * mode: "monitoring",
127 * burstSensitivity: "medium",
128 * rateSensitivity: "medium",
129 * });
130 * ```
131 *
132 * **Example:** Data-center scoped rule with retransmit mitigation
133 * ```typescript
134 * yield* Cloudflare.DdosProtection.SynProtectionRule("SjcSyn", {
135 * scope: "datacenter",
136 * name: "SJC",
137 * mode: "enabled",
138 * burstSensitivity: "high",
139 * rateSensitivity: "high",
140 * mitigationType: "retransmit",
141 * });
142 * ```
143 *
144 * @see https://developers.cloudflare.com/ddos-protection/advanced-ddos-systems/overview/advanced-tcp-protection/
145 *
146 * @resource
147 * @product DDoS Protection
148 * @category Network
149 */
150 export const SynProtectionRule = Resource<SynProtectionRule>(TypeId);
151
152 /**
153 * Returns true if the given value is a SynProtectionRule resource.
154 */
155 export const isSynProtectionRule = (value: unknown): value is SynProtectionRule =>
156 Predicate.hasProperty(value, "Type") && value.Type === TypeId;
157
158 export const SynProtectionRuleProvider = () =>
159 Provider.succeed(SynProtectionRule, {
160 stables: ["ruleId", "accountId", "scope", "name", "createdOn"],
161
162 // Account-scoped collection: paginate every rule in the ambient
163 // account. Accounts without the Advanced TCP Protection entitlement (or
164 // lacking read permission) yield no rules — treat the typed rejection as
165 // an empty enumeration rather than an error.
166 list: Effect.fn(function* () {
167 const { accountId } = yield* yield* CloudflareEnvironment;
168 return yield* ddos.listAdvancedTcpProtectionSynProtectionRules.pages({ accountId }).pipe(
169 Stream.runCollect,
170 Effect.map((chunk) =>
171 Array.from(chunk).flatMap((page) =>
172 (page.result ?? []).map((rule) => toAttributes(rule, accountId)),
173 ),
174 ),
175 Effect.catchTags({
176 AdvancedTcpProtectionNotEntitled: () => Effect.succeed([]),
177 Forbidden: () => Effect.succeed([]),
178 }),
179 );
180 }),
181
182 diff: Effect.fn(function* ({ olds, news }) {
183 if (olds === undefined) return undefined;
184 // `news` runs at plan time and may still carry unresolved
185 // expressions — bail out and let the engine apply default logic.
186 if (!isResolved(news)) return undefined;
187 // The API only patches mode/sensitivities/mitigationType — the
188 // scope + name pair is the rule's identity and cannot change.
189 if (olds.scope !== news.scope || ruleName(olds) !== ruleName(news)) {
190 return { action: "replace" } as const;
191 }
192 return undefined;
193 }),
194
195 read: Effect.fn(function* ({ output, olds }) {
196 const { accountId } = yield* yield* CloudflareEnvironment;
197 const acct = output?.accountId ?? accountId;
198
199 // Owned path: refresh by our persisted rule id.
200 if (output?.ruleId) {
201 const observed = yield* getRule(acct, output.ruleId);
202 if (observed) return toAttributes(observed, acct);
203 }
204
205 // Adoption path: a rule for this scope + name may already exist.
206 // Rules carry no ownership markers, so brand the match `Unowned` —
207 // the engine refuses to take over unless `adopt` is set.
208 const identity = output ?? olds;
209 if (identity?.scope) {
210 const observed = yield* findByScopeAndName(acct, identity.scope, ruleName(identity));
211 if (observed) return Unowned(toAttributes(observed, acct));
212 }
213 return undefined;
214 }),
215
216 reconcile: Effect.fn(function* ({ news, output }) {
217 const { accountId } = yield* yield* CloudflareEnvironment;
218 const name = ruleName(news);
219
220 // 1. Observe — the rule id cached on `output` is a hint, not a
221 // guarantee: a missing rule falls through to the scope + name
222 // scan and then to create.
223 let observed = output?.ruleId ? yield* getRule(accountId, output.ruleId) : undefined;
224
225 // 2. Fall back to scanning for the scope + name match (ownership was
226 // already gated by `read` reporting existing rules as Unowned).
227 if (!observed) {
228 observed = yield* findByScopeAndName(accountId, news.scope, name);
229 }
230
231 // 3. Ensure — create when missing.
232 if (!observed) {
233 observed = yield* ddos.createAdvancedTcpProtectionSynProtectionRule({
234 accountId,
235 scope: news.scope,
236 name,
237 mode: news.mode,
238 burstSensitivity: news.burstSensitivity,
239 rateSensitivity: news.rateSensitivity,
240 mitigationType: news.mitigationType,
241 });
242 }
243
244 // 4. Sync — diff observed mutable aspects against desired; skip the
245 // patch entirely on a no-op.
246 const dirty =
247 observed.mode !== news.mode ||
248 observed.burstSensitivity !== news.burstSensitivity ||
249 observed.rateSensitivity !== news.rateSensitivity ||
250 (news.mitigationType !== undefined && observed.mitigationType !== news.mitigationType);
251 if (dirty) {
252 observed = yield* ddos.patchAdvancedTcpProtectionSynProtectionRuleItem({
253 accountId,
254 ruleId: observed.id,
255 mode: news.mode,
256 burstSensitivity: news.burstSensitivity,
257 rateSensitivity: news.rateSensitivity,
258 mitigationType: news.mitigationType,
259 });
260 }
261
262 return toAttributes(observed, accountId);
263 }),
264
265 delete: Effect.fn(function* ({ output }) {
266 yield* ddos
267 .deleteAdvancedTcpProtectionSynProtectionRuleItem({
268 accountId: output.accountId,
269 ruleId: output.ruleId,
270 })
271 .pipe(Effect.catchTag("SynProtectionRuleNotFound", () => Effect.void));
272 }),
273 });
274
275 type ObservedRule = ddos.GetAdvancedTcpProtectionSynProtectionRuleItemResponse;
276
277 const ruleName = (props: { scope: string; name?: string }) => props.name ?? "global";
278
279 /**
280 * Read a rule by id, mapping "gone" (`SynProtectionRuleNotFound`, HTTP 404)
281 * to `undefined`.
282 */
283 const getRule = (accountId: string, ruleId: string) =>
284 ddos.getAdvancedTcpProtectionSynProtectionRuleItem({ accountId, ruleId }).pipe(
285 Effect.map((rule): ObservedRule | undefined => rule),
286 Effect.catchTag("SynProtectionRuleNotFound", () => Effect.undefined),
287 );
288
289 /**
290 * Find a rule by its scope + name identity. If several rules carry the same
291 * pair, pick the oldest for determinism.
292 */
293 const findByScopeAndName = (accountId: string, scope: string, name: string) =>
294 ddos.listAdvancedTcpProtectionSynProtectionRules.items({ accountId }).pipe(
295 Stream.runCollect,
296 Effect.map((chunk) =>
297 Array.from(chunk)
298 .filter((rule) => rule.scope === scope && rule.name === name)
299 .sort((a, b) => a.createdOn.localeCompare(b.createdOn))
300 .at(0),
301 ),
302 );
303
304 const toAttributes = (rule: ObservedRule, accountId: string): SynProtectionRuleAttributes => ({
305 ruleId: rule.id,
306 accountId,
307 // Distilled widens generated string enums to plain strings.
308 scope: rule.scope as SynProtectionRuleScope,
309 name: rule.name,
310 mode: rule.mode as SynProtectionRuleMode,
311 burstSensitivity: rule.burstSensitivity as SynProtectionRuleSensitivity,
312 rateSensitivity: rule.rateSensitivity as SynProtectionRuleSensitivity,
313 mitigationType: rule.mitigationType as SynProtectionMitigationType,
314 createdOn: rule.createdOn,
315 modifiedOn: rule.modifiedOn,
316 });