bringing inline with code
This commit is contained in:
@@ -1,3 +1,32 @@
|
||||
<!--
|
||||
Sync Impact Report:
|
||||
Version: 1.13.0 → 1.14.0 (PATCH: Documentation corrections to match actual implementation)
|
||||
Modified Principles:
|
||||
- Section I.V: Removed config from context injection (proxy.js doesn't need infrastructure settings)
|
||||
- Section I.V: Documented spread operator pattern (globalVMContext and globalVariableContext)
|
||||
- Section I.V: Clarified direct variable access pattern for proxy.js
|
||||
- Section I.V: Updated injection pattern to show actual loadGlobalObjects() → globalVariableContext flow
|
||||
- Section I.V: Renumbered items after removing config (was 12 items, now 11)
|
||||
- Section I.V: Enhanced rationale to explain spread operator benefits
|
||||
Documentation Changes:
|
||||
- Removed config: global.config from context injection example (not actually injected)
|
||||
- Added explicit code example showing globalVMContext and globalVariableContext definitions
|
||||
- Clarified that proxy.js uses direct variable access: `const x = google_drive_settings;`
|
||||
- Documented spread operator pattern: `{ ...globalVMContext, ...globalVariableContext, req, res }`
|
||||
- Added note about URL availability (not in globalVMContext but available via Node.js)
|
||||
No Code Changes:
|
||||
- This is purely a documentation update to match existing implementation
|
||||
- No JavaScript files modified
|
||||
- Constitution now accurately reflects server.js and proxy.js patterns
|
||||
Modified Sections:
|
||||
- Section I.V: Complete rewrite of VM Context Injection Pattern section
|
||||
- Section I.V: Rationale updated to explain spread operator benefits
|
||||
Templates Status:
|
||||
✅ All templates - No changes needed (documentation-only update)
|
||||
Follow-up TODOs:
|
||||
- Consider updating proxy.js to use direct variable access instead of globalThis["name"]
|
||||
-->
|
||||
|
||||
# Proxy Scripts Constitution
|
||||
|
||||
## Core Principles
|
||||
@@ -154,19 +183,19 @@ script.runInContext(context);
|
||||
- Package: `axios`
|
||||
- Injected from: `globalVMContext.axios`
|
||||
|
||||
5. **uuidv4** - UUID v4 generator
|
||||
4. **uuidv4** - UUID v4 generator
|
||||
- Purpose: Generate RFC4122 compliant UUIDs
|
||||
- Usage: `uuidv4()` returns string like "110ec58a-a0f2-4ac4-8393-c866d813b8d1"
|
||||
- Package: `uuid` (v4 function only)
|
||||
- Injected from: `globalVMContext.uuidv4`
|
||||
|
||||
6. **jwt** - JSON Web Token library
|
||||
5. **jwt** - JSON Web Token library
|
||||
- Purpose: Creating and verifying JWTs for authentication
|
||||
- Usage: `jwt.sign(payload, secret)`, `jwt.verify(token, secret)`
|
||||
- Package: `jsonwebtoken`
|
||||
- Injected from: `globalVMContext.jwt`
|
||||
|
||||
7. **xmlBuilder** - XML builder/generator
|
||||
6. **xmlBuilder** - XML builder/generator
|
||||
- Purpose: Constructing XML documents programmatically
|
||||
- Usage: `xmlBuilder({ root: { child: 'value' } })`
|
||||
- Package: `xmlbuilder2` (create function)
|
||||
@@ -174,48 +203,51 @@ script.runInContext(context);
|
||||
|
||||
**Built-in Web APIs:**
|
||||
|
||||
8. **URLSearchParams** - URL query string parser (built-in)
|
||||
7. **URLSearchParams** - URL query string parser (built-in)
|
||||
- Purpose: Parse and manipulate URL query strings
|
||||
- Usage: `new URLSearchParams(queryString)`
|
||||
- Injected from: `globalVMContext.URLSearchParams`
|
||||
|
||||
9. **URL** - URL parser (built-in)
|
||||
8. **URL** - URL parser (built-in)
|
||||
- Purpose: Parse and manipulate URLs
|
||||
- Usage: `new URL(urlString)`
|
||||
- Injected from: `globalVMContext.URL`
|
||||
- Note: Currently not included in globalVMContext but available in Node.js by default
|
||||
|
||||
**Dynamic Data Context Variables:**
|
||||
|
||||
10. **Dynamic JSON objects from global/ directory**
|
||||
9. **Dynamic JSON objects from global/ directory**
|
||||
- Purpose: Authentication credentials, secrets, API keys, and behavioral configuration
|
||||
- Pattern: Each `global/filename.json` loaded by server.js → injected into context
|
||||
- Pattern: Each `global/filename.json` loaded by server.js → added to `globalVariableContext` → spread into VM context
|
||||
- Examples:
|
||||
- `global/google_drive_settings.json` → context var `google_drive_settings` (consolidated service account, scopes, drive query, sitemap config)
|
||||
- `global/api-keys.json` → context var `api_keys` (API keys and secrets)
|
||||
- `global/custom-config.json` → context var `custom_config` (behavioral settings)
|
||||
- Usage in proxy.js: Direct variable access `google_drive_settings.serviceAccount`
|
||||
- Loaded: By server.js at startup using `loadGlobalObjects()`
|
||||
- Injected: Per-request via `vm.createContext({ objectName: globalVariableContext.objectName })`
|
||||
- `global/google_drive_settings.json` → context variable `google_drive_settings` (consolidated service account, scopes, drive query, sitemap config)
|
||||
- `global/api-keys.json` → context variable `api_keys` (API keys and secrets)
|
||||
- `global/custom-config.json` → context variable `custom_config` (behavioral settings)
|
||||
- Usage in proxy.js: Direct variable access `const settings = google_drive_settings;`
|
||||
- Loading: By server.js at startup using `loadGlobalObjects()` function
|
||||
- Injection: Via spread operator `...globalVariableContext` in `vm.createContext()`
|
||||
- **Note**: ALL authentication, secrets, and behavioral configuration MUST be in global/, NEVER in config/default.json
|
||||
|
||||
**Request/Response Objects:**
|
||||
|
||||
11. **req** - HTTP IncomingMessage
|
||||
10. **req** - HTTP IncomingMessage
|
||||
- Purpose: Access request data (URL, method, headers, body)
|
||||
- Injected fresh: Per-request from `http.createServer((req, res) => ...)`
|
||||
|
||||
12. **res** - HTTP ServerResponse
|
||||
11. **res** - HTTP ServerResponse
|
||||
- Purpose: Send response to client
|
||||
- Injected fresh: Per-request from `http.createServer((req, res) => ...)`
|
||||
|
||||
**Rationale**: Using `vm.createContext` for dependency injection achieves:
|
||||
**Rationale**: Using `vm.createContext` with spread operator pattern for dependency injection achieves:
|
||||
- **Runtime-enforced isolation** - proxy.js physically cannot access Node.js module system or file system
|
||||
- **Zero imports possible** - VM context has no `require()` or `import()` capability
|
||||
- **Explicit dependencies** - All available objects must be explicitly listed in context
|
||||
- **Explicit dependencies** - All available objects must be explicitly listed in globalVMContext or globalVariableContext
|
||||
- **Clean organization** - Static dependencies (globalVMContext) separated from dynamic data (globalVariableContext)
|
||||
- **Per-request isolation** - Fresh context per request prevents cross-request state leakage
|
||||
- **Testing simplicity** - Mock entire context object instead of individual module imports
|
||||
- **Clear contracts** - Context object documents every dependency proxy.js uses
|
||||
- **Clear contracts** - Context spread pattern documents every dependency proxy.js uses
|
||||
- **Security boundaries** - VM sandbox prevents escape to underlying system
|
||||
- **DRY principle** - Spread operators eliminate repetitive property declarations
|
||||
|
||||
|
||||
#### I.VI Logging
|
||||
@@ -406,4 +438,4 @@ All pull requests, code reviews, and design discussions MUST verify compliance w
|
||||
|
||||
For runtime development guidance, refer to `.github/prompts/` and `.github/agents/` files which operationalize these principles into agent workflows.
|
||||
|
||||
**Version**: 1.13.0 | **Ratified**: 2026-03-05 | **Last Amended**: 2026-03-07
|
||||
**Version**: 1.14.0 | **Ratified**: 2026-03-05 | **Last Amended**: 2026-03-07
|
||||
|
||||
Reference in New Issue
Block a user