@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 176 lines 7.26 KB
Raw
1 import type { BundleConfig } from "alchemy/Bundle/Bundle";
2 import type { Input } from "alchemy/Input";
3 import { Platform, type Main, type PlatformProps } from "alchemy/Platform";
4 import type { Resource } from "alchemy/Resource";
5 import * as Effect from "effect/Effect";
6 import type * as Redacted from "effect/Redacted";
7 import type { BranchScope } from "./BranchScope.ts";
8 import type { FunctionEnvironment, FunctionRequest } from "./FunctionEnvironment.ts";
9 import {
10 makeFunctionRuntimeContext,
11 type FunctionRuntimeContext,
12 } from "./FunctionRuntimeContext.ts";
13 import type { Providers } from "./Providers.ts";
14
15 /**
16 * Prebuilt Node 24 Fetch application. The directory or ZIP must contain
17 * `index.mjs` at its root, exporting a Fetch handler or an object with `fetch`.
18 * Include all runtime dependencies; Alchemy does not bundle prebuilt artifacts.
19 * Archives must not contain symlinks, traversal paths, or deployment secrets.
20 */
21 export type FunctionArtifact =
22 | {
23 /** Directory packaged into a deterministic ZIP. */ directory: string;
24 zip?: never;
25 }
26 | { /** Path to an existing ZIP archive. */ zip: string; directory?: never };
27
28 /**
29 * {@link BranchScope} where the branch or project may also be an Effect that
30 * produces it, so `{ branch: Main }` and `{ branch: yield* Main }` both
31 * type-check.
32 */
33 export type FunctionBranchScope =
34 | {
35 /** Branch resource or explicit branch identity, or an Effect producing one. */
36 branch:
37 | { projectId: string; branchId: string }
38 | Effect.Effect<Input<{ projectId: string; branchId: string }>, never, any>;
39 project?: never;
40 }
41 | {
42 /** Project whose default branch is selected at reconciliation time, or an Effect producing one. */
43 project: { projectId: string } | Effect.Effect<Input<{ projectId: string }>, never, any>;
44 branch?: never;
45 };
46
47 /**
48 * The scope as providers see it. `transformProps` yields an Effect-valued
49 * `branch` or `project` before any lifecycle operation runs, so only the
50 * resolved shape reaches the provider.
51 */
52 export const branchScopeOf = <P extends FunctionBranchScope>(props: P) => props as P & BranchScope;
53
54 export interface FunctionCommonProps extends PlatformProps {
55 /** Immutable lowercase alphanumeric identifier, at most 20 characters. Generated when omitted. */
56 slug?: string;
57 /** Mutable display name. Removing it restores the slug. */
58 name?: string;
59 /** Write-only values. Removing a managed key sends an empty deletion value. Platform-injected keys cannot be overridden. */
60 env?: Record<string, string | Redacted.Redacted<string> | undefined>;
61 /** Node-targeted bundler options; not used with prebuilt artifacts. */
62 bundle?: BundleConfig;
63 /** Local Neon CLI executable (version 2.45.0 or newer) and optional listening port. */
64 dev?: { command?: string; port?: number };
65 }
66
67 export type FunctionProps = FunctionBranchScope &
68 FunctionCommonProps &
69 (
70 | {
71 /** Native Fetch or Effect entry module. */ main: string;
72 artifact?: never;
73 }
74 | {
75 /** Prebuilt Fetch application, mutually exclusive with main. */ artifact: FunctionArtifact;
76 main?: never;
77 }
78 );
79
80 export interface FunctionAttributes {
81 /** Owning project. */ projectId: string;
82 /** Owning branch. */ branchId: string;
83 /** Stable function ID. */ functionId: string;
84 /** Immutable invocation slug. */ slug: string;
85 /** Observed display name. */ name: string;
86 /** Public invocation URL. Authenticate callers in the handler. */ url: string;
87 /** Latest deployment identifier. */ currentDeploymentId: number | undefined;
88 /** Deployment currently serving traffic. */ activeDeploymentId: number | undefined;
89 /** Latest deployment build status. */ status: string | undefined;
90 /** Digest of the last successfully applied artifact, not a remote code attestation. */ codeHash:
91 | string
92 | undefined;
93 /** Last applied environment digest, not proof of remote write-only value equality. */ environmentHash?: string;
94 /** Previously managed environment names. Values cannot be read back. */ environment: string[];
95 }
96
97 export interface FunctionBinding {
98 /** Namespaced application configuration; conflicts with user values are rejected. */
99 env?: Record<string, string | Redacted.Redacted<string> | undefined>;
100 }
101
102 export interface Function extends Resource<
103 "Neon.Function",
104 FunctionProps,
105 FunctionAttributes,
106 FunctionBinding,
107 Providers
108 > {}
109
110 /**
111 * Node.js 24 Fetch function, with native and Effect entrypoints.
112 *
113 * Functions have public URLs. The `functions:invoke` credential scope does not
114 * establish a private invocation policy. Authenticate requests in your handler.
115 * Native same-branch database/storage credentials are injected by Neon; a typed
116 * read-only binding does not restrict the credentials available to the process.
117 * Explicit adoption takes ownership of user-defined environment names: existing
118 * keys omitted from `env` and bindings are removed. Values are write-only, so
119 * cached digests cannot detect out-of-band value drift.
120 *
121 * ### Streaming disconnects <!-- api-prose -->
122 *
123 * Neon’s production host currently does not reliably propagate client disconnects
124 * to uncompressed response streams. An abandoned stream can retain its producer
125 * and request-scoped resources until it finishes. Prefer finite responses and
126 * application-bounded streams; do not rely on disconnect cleanup for long-lived
127 * streaming workloads until [the upstream issue](https://github.com/neondatabase/neon-pkgs/issues/636)
128 * is resolved. Alchemy propagates abort and body-cancel signals when the host supplies them.
129 *
130 * ### Native Fetch
131 * **Example:** Bundle a native object, bare handler, or Hono application
132 * ```typescript
133 * const api = yield* Neon.Function("Api", { branch, main: "./src/api.ts" });
134 * ```
135 *
136 * ### Effect Fetch
137 * **Example:** Class entrypoint
138 * ```typescript
139 * export default class Api extends Neon.Function<Api>()(
140 * "Api", { branch, main: import.meta.url },
141 * Effect.succeed({ fetch: Effect.succeed(HttpServerResponse.text("ok")) }),
142 * ) {}
143 * ```
144 *
145 * ### Prebuilt Applications
146 * **Example:** Deploy Website build output without rebundling
147 * ```typescript
148 * const site = yield* Neon.Function("Site", { branch, artifact: { directory: "./dist" } });
149 * ```
150 *
151 * @resource
152 * @product Function
153 */
154 export const Function: Platform<
155 Function,
156 FunctionEnvironment,
157 Main<FunctionEnvironment | FunctionRequest>,
158 FunctionRuntimeContext
159 > = Platform<Function>("Neon.Function", {
160 createRuntimeContext: makeFunctionRuntimeContext,
161 // `{ branch: Main }` at module scope is an Effect. Yield it here so the
162 // branch (or project) is registered and resolved at reconcile (same as
163 // `yield* Main` inside Effect.gen).
164 transformProps: (_id, props) =>
165 Effect.gen(function* () {
166 if (globalThis.__ALCHEMY_RUNTIME__) return props;
167 const yieldRef = (value: unknown) =>
168 // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- props refs are declaration Effects resolved by the engine
169 Effect.isEffect(value) ? (value as Effect.Effect<unknown>) : Effect.succeed(value);
170 return {
171 ...props,
172 ...(props.branch !== undefined ? { branch: yield* yieldRef(props.branch) } : {}),
173 ...(props.project !== undefined ? { project: yield* yieldRef(props.project) } : {}),
174 };
175 }),
176 });