@@ -36,11 +36,27 @@ import { getRuntimeEnv, isInternalBinding } from './env.ts';
3636type AnyValidator = StandardSchemaV1 < unknown , unknown > ;
3737type AnySchema = Record < string , AnyValidator > ;
3838
39- type BootValidationState = { ok : true } | { ok : false ; error : EnvValidationError } ;
39+ type BootValidationState =
40+ | { ok : true ; values : Map < string , unknown > }
41+ | { ok : false ; error : EnvValidationError } ;
42+
43+ /** A completed whole-schema validation, with the raw value of each key that it checked. */
44+ type EnvValidation = {
45+ inputs : Map < string , unknown > ;
46+ state : BootValidationState ;
47+ } ;
48+
4049type EnvRegistryState = {
4150 schema : AnySchema | null ;
4251 hasDefineEnvBeenCalled : boolean ;
43- bootValidation : BootValidationState | null ;
52+ /**
53+ * The latest completed whole-schema validation. An env with the same raw values reuses it,
54+ * also when each request brings a new env object. An env with other values is validated
55+ * again rather than given values validated for another. `readKey` serves a key's value from
56+ * here to an env that was not validated itself, while it holds the raw value that the value
57+ * came from.
58+ */
59+ validation ?: EnvValidation | null ;
4460} ;
4561
4662// Tooling can load `void/env` through a different module instance than the Vite
@@ -53,18 +69,16 @@ const registryGlobal = globalThis as typeof globalThis & {
5369const registry = ( registryGlobal [ ENV_REGISTRY_SYMBOL ] ??= {
5470 schema : null ,
5571 hasDefineEnvBeenCalled : false ,
56- bootValidation : null ,
5772} ) ;
58- const validatedCache = new WeakMap < object , Map < string , unknown > > ( ) ;
59- // WeakMap does not expose its values; keep a parallel list so defineEnv can clear them .
60- const cacheList : Array < Map < string , unknown > > = [ ] ;
73+ // Replaced, not cleared, by defineEnv, so the cache of an env holds no reference once the env
74+ // is gone .
75+ let validatedCache = new WeakMap < object , Map < string , unknown > > ( ) ;
6176
6277function getValidatedCache ( rawEnv : object ) : Map < string , unknown > {
6378 let cache = validatedCache . get ( rawEnv ) ;
6479 if ( ! cache ) {
6580 cache = new Map ( ) ;
6681 validatedCache . set ( rawEnv , cache ) ;
67- cacheList . push ( cache ) ;
6882 }
6983 return cache ;
7084}
@@ -108,57 +122,85 @@ export function defineEnv<S extends AnySchema>(schema: S): InferEnv<S> {
108122 // swaps in an empty schema, we still know defineEnv was declared.
109123 registry . hasDefineEnvBeenCalled = true ;
110124 // Drop any cached entries from a prior schema (HMR / re-import).
111- for ( const map of cacheList ) {
112- map . clear ( ) ;
113- }
125+ validatedCache = new WeakMap ( ) ;
114126 // Reset boot-time validation state so a re-imported schema is re-checked.
115- registry . bootValidation = null ;
127+ registry . validation = null ;
116128 return env as unknown as InferEnv < S > ;
117129}
118130
119131/**
120- * Internal: validate the whole schema against the worker env once per isolate,
121- * from the generated worker entry. Catches remote-secret values the deploy CLI
122- * cannot see. Async validators are awaited here and their values cached, so
123- * later synchronous `env.X` reads can serve them.
132+ * Internal: validate the whole schema against the worker env, from the generated
133+ * worker entry. Catches remote-secret values the deploy CLI cannot see. A
134+ * completed validation is reused for the same raw values; an env with other
135+ * values is validated again. Async validators are awaited here, and their values
136+ * serve later synchronous `env.X` reads of the env this call receives, and of any
137+ * other env that holds the same raw values.
124138 */
125139export async function _validateEnvOnce ( envValues : unknown ) : Promise < void > {
126- if ( registry . bootValidation ) {
127- if ( ! registry . bootValidation . ok ) {
128- throw registry . bootValidation . error ;
129- }
140+ const schema = registry . schema ;
141+ if ( ! schema ) {
130142 return ;
131143 }
132- if ( ! registry . schema ) {
133- registry . bootValidation = { ok : true } ;
134- return ;
144+ const inputs = readSchemaInputs ( schema , envValues ) ;
145+ const last = registry . validation ;
146+ let state : BootValidationState ;
147+ if ( last && sameInputs ( last . inputs , inputs ) ) {
148+ state = last . state ;
149+ } else {
150+ // Each call awaits its own validation until one completes. In workerd, a promise that
151+ // waits on another request's I/O never settles once that request is canceled.
152+ state = await validateSchema ( schema , inputs ) ;
153+ if ( registry . schema !== schema ) {
154+ // defineEnv registered another schema while this call waited.
155+ return _validateEnvOnce ( envValues ) ;
156+ }
157+ registry . validation = { inputs, state } ;
135158 }
159+ if ( ! state . ok ) {
160+ throw state . error ;
161+ }
162+ // Keep the values with the env that passed. The registry holds the latest validation only,
163+ // and an env with other values can validate while requests with this env still run:
164+ // Cloudflare may keep an isolate running when only its bindings change.
165+ seedValidated ( envValues , state . values ) ;
166+ }
167+
168+ /** The raw value of each schema key that `readKey` would validate for this env. */
169+ function readSchemaInputs ( schema : AnySchema , envValues : unknown ) : Map < string , unknown > {
170+ const values = ( typeof envValues === 'object' && envValues !== null ? envValues : { } ) as Record <
171+ string ,
172+ unknown
173+ > ;
136174 // Public values belong to this build, not to the remote secret store. Keep
137175 // server rendering and boot validation consistent with the browser bundle.
138- const values = {
139- ...( ( envValues ?? { } ) as Record < string , unknown > ) ,
140- ...getClientEnvValues ( ) ,
141- } ;
142- const report = await validateAllEnvWithValues ( registry . schema , values ) ;
143- if ( report . valid ) {
144- // Seed the per-key cache, keyed by the raw env as in `readKey`.
145- try {
146- const cacheKey = getRawRuntimeEnv ( ) as object ;
147- const cache = getValidatedCache ( cacheKey ) ;
148- for ( const [ key , value ] of report . values ) {
149- // Internal bindings stay hidden even when the schema declares them.
150- if ( isInternalBinding ( key , cacheKey as RuntimeEnv ) ) {
151- continue ;
152- }
153- if ( ! cache . has ( key ) ) {
154- cache . set ( key , value ) ;
155- }
156- }
157- } catch {
158- // No runtime env available — no proxy reads will happen, so no seeding needed.
176+ const clientValues = getClientEnvValues ( ) ;
177+ return new Map (
178+ Object . keys ( schema ) . map ( ( key ) => [
179+ key ,
180+ Object . hasOwn ( clientValues , key ) ? clientValues [ key ] : values [ key ] ,
181+ ] ) ,
182+ ) ;
183+ }
184+
185+ function sameInputs ( a : Map < string , unknown > , b : Map < string , unknown > ) : boolean {
186+ if ( a . size !== b . size ) {
187+ return false ;
188+ }
189+ for ( const [ key , value ] of a ) {
190+ if ( ! b . has ( key ) || ! Object . is ( b . get ( key ) , value ) ) {
191+ return false ;
159192 }
160- registry . bootValidation = { ok : true } ;
161- return ;
193+ }
194+ return true ;
195+ }
196+
197+ async function validateSchema (
198+ schema : AnySchema ,
199+ inputs : Map < string , unknown > ,
200+ ) : Promise < BootValidationState > {
201+ const report = await validateAllEnvWithValues ( schema , Object . fromEntries ( inputs ) ) ;
202+ if ( report . valid ) {
203+ return { ok : true , values : report . values } ;
162204 }
163205 const lines : Array < string > = [ 'Env validation failed at worker boot:' ] ;
164206 for ( const key of report . missing ) {
@@ -168,9 +210,25 @@ export async function _validateEnvOnce(envValues: unknown): Promise<void> {
168210 // Messages are already redacted inside validateAllEnvWithValues.
169211 lines . push ( ` • ${ key } : ${ messages . join ( '; ' ) } ` ) ;
170212 }
171- const error = new EnvValidationError ( '__init__' , [ { message : lines . join ( '\n' ) } ] ) ;
172- registry . bootValidation = { ok : false , error } ;
173- throw error ;
213+ return {
214+ ok : false ,
215+ error : new EnvValidationError ( '__init__' , [ { message : lines . join ( '\n' ) } ] ) ,
216+ } ;
217+ }
218+
219+ /** Seed the per-key cache of `rawEnv`, where `readKey` looks first, with values validated for it. */
220+ function seedValidated ( rawEnv : unknown , values : Map < string , unknown > ) : void {
221+ if ( typeof rawEnv !== 'object' || rawEnv === null || values . size === 0 ) {
222+ return ;
223+ }
224+ const cache = getValidatedCache ( rawEnv ) ;
225+ for ( const [ key , value ] of values ) {
226+ // Internal bindings stay hidden even when the schema declares them. A value that a read
227+ // already returned stays the same object.
228+ if ( ! isInternalBinding ( key , rawEnv as RuntimeEnv ) && ! cache . has ( key ) ) {
229+ cache . set ( key , value ) ;
230+ }
231+ }
174232}
175233
176234/** Internal: framework-only access to the registered schema (for plugin/CLI). */
@@ -263,6 +321,19 @@ function readKey(key: string): unknown {
263321 if ( cache . has ( key ) ) {
264322 return cache . get ( key ) ;
265323 }
324+ // Validation seeds only the env object it receives. Reads also use objects it never
325+ // received: the `cloudflare:workers` env outside a request scope, the remote dev copy. A
326+ // validated value belongs to the raw value it came from, so the latest validation serves
327+ // such an env while it holds that raw value. The value is not cached: this env can come to
328+ // hold another.
329+ const latest = registry . validation ;
330+ if (
331+ latest ?. state . ok &&
332+ latest . state . values . has ( key ) &&
333+ Object . is ( latest . inputs . get ( key ) , rawValue )
334+ ) {
335+ return latest . state . values . get ( key ) ;
336+ }
266337 const result = validator [ '~standard' ] . validate ( rawValue ) ;
267338 if ( result instanceof Promise ) {
268339 throw new Error (
@@ -327,9 +398,8 @@ export type EnvValidationReport = {
327398 missing : Array < string > ;
328399 invalid : Array < { key : string ; messages : Array < string > } > ;
329400 /**
330- * Resolved values for keys that validated successfully. Used to seed the
331- * per-env cache after async pre-validation so sync `env.X` reads hit the
332- * cache.
401+ * Resolved values for keys that validated successfully. After async
402+ * pre-validation they serve sync `env.X` reads.
333403 */
334404 values : Map < string , unknown > ;
335405} ;
@@ -353,7 +423,7 @@ export async function validateAllEnv(
353423
354424/**
355425 * Internal: shared core that validates a schema against values and also
356- * returns the resolved values (for cache seeding ).
426+ * returns the resolved values (for sync reads ).
357427 */
358428async function validateAllEnvWithValues (
359429 schema : AnySchema ,
0 commit comments