Repository navigation
feat(schemas): versioned schema ids, hosted on friggframework.org #705
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| /** | ||
| * Schema identifiers (ADR-051, "Hosted schemas" amendment). | ||
| * | ||
| * Every Frigg JSON Schema has the `$id` | ||
| * https://friggframework.org/schemas/<name>/v<major>.<minor>.json | ||
| * and friggframework.org serves the file at exactly that URL. The `$id` is a | ||
| * name, not a location the runtime reads: validation always resolves it from | ||
| * this package and never fetches it. | ||
| */ | ||
|
|
||
| const SCHEMA_BASE_URL = 'https://friggframework.org/'; | ||
|
|
||
| const SCHEMA_ID_PATTERN = | ||
| /^https:\/\/friggframework\.org\/schemas\/([a-z0-9]+(?:-[a-z0-9]+)*)\/v(0|[1-9]\d*)\.(0|[1-9]\d*)\.json$/; | ||
|
|
||
| /** | ||
| * Unversioned ids the schemas carried before 2.0.1. They never resolved over | ||
| * HTTP, but code may pass them to `validate()`/`getSchema()` or Ajv, so the | ||
| * package still registers them as aliases of the current schema. | ||
| * | ||
| * @deprecated Remove in the release after 2.0.1. | ||
| */ | ||
| const LEGACY_SCHEMA_IDS = Object.freeze({ | ||
| 'api-authorization': ['https://friggframework.org/schemas/api-authorization.json'], | ||
| 'api-credentials': ['https://friggframework.org/schemas/api-credentials.json'], | ||
| 'api-entities': ['https://friggframework.org/schemas/api-entities.json'], | ||
| 'api-proxy': ['https://friggframework.org/schemas/api-proxy.json'], | ||
| 'api-module-definition': ['https://schemas.friggframework.org/api-module-definition.schema.json'], | ||
| 'app-definition': ['https://schemas.friggframework.org/app-definition.schema.json'], | ||
| 'core-models': ['https://schemas.friggframework.org/core-models.schema.json'], | ||
| 'environment-config': ['https://schemas.friggframework.org/environment-config.schema.json'], | ||
| 'integration-definition': ['https://schemas.friggframework.org/integration-definition.schema.json'], | ||
| 'serverless-config': ['https://schemas.friggframework.org/serverless-config.schema.json'], | ||
| }); | ||
|
|
||
| /** | ||
| * Parse a schema `$id`. | ||
| * @param {string} id | ||
| * @returns {{ name: string, version: string, hostedPath: string } | null} | ||
| * `hostedPath` is the path under the website root (`schemas/<name>/v1.0.json`). | ||
| */ | ||
| function parseSchemaId(id) { | ||
| const match = typeof id === 'string' ? SCHEMA_ID_PATTERN.exec(id) : null; | ||
| if (!match) return null; | ||
| const [, name, major, minor] = match; | ||
| const version = `${major}.${minor}`; | ||
| return { name, version, hostedPath: `schemas/${name}/v${version}.json` }; | ||
| } | ||
|
|
||
| /** | ||
| * Register a schema with Ajv under its file name, its `$id`, and its legacy ids. | ||
| * @param {import('ajv').default} ajv | ||
| * @param {object} schema - parsed schema (its `$id` registers automatically) | ||
| * @param {string} name - file name without `.schema.json` | ||
| */ | ||
| function addSchemaWithAliases(ajv, schema, name) { | ||
| ajv.addSchema(schema, name); | ||
| for (const legacyId of LEGACY_SCHEMA_IDS[name] || []) { | ||
| ajv.addSchema({ ...schema, $id: legacyId }); | ||
| } | ||
| } | ||
|
|
||
| module.exports = { | ||
| SCHEMA_BASE_URL, | ||
| SCHEMA_ID_PATTERN, | ||
| LEGACY_SCHEMA_IDS, | ||
| parseSchemaId, | ||
| addSchemaWithAliases, | ||
| }; |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,102 @@ | ||
| #!/usr/bin/env node | ||
|
|
||
| /** | ||
| * Copy the Frigg JSON Schemas into the website, at the path their `$id` names. | ||
| * | ||
| * https://friggframework.org/schemas/<name>/v<x.y>.json | ||
| * -> website/schemas/<name>/v<x.y>.json | ||
| * | ||
| * The copies are committed: friggframework.org is published from website/ as | ||
| * static files, and a file stays in website/schemas after its schema moves to | ||
| * a new version, so every published version keeps resolving. | ||
| * | ||
| * node scripts/sync-hosted-schemas.js write the copies | ||
| * node scripts/sync-hosted-schemas.js --check exit 1 when a copy is missing or stale | ||
| * | ||
| * See ADR-051, "Hosted schemas" amendment. | ||
| */ | ||
|
|
||
| const fs = require('fs'); | ||
|
Check warning on line 19 in packages/schemas/scripts/sync-hosted-schemas.js
|
||
| const path = require('path'); | ||
|
Check warning on line 20 in packages/schemas/scripts/sync-hosted-schemas.js
|
||
| const { parseSchemaId } = require('../schema-ids'); | ||
|
|
||
| const REPO_ROOT = path.resolve(__dirname, '..', '..', '..'); | ||
| const WEBSITE_ROOT = path.join(REPO_ROOT, 'website'); | ||
|
|
||
| // Directories whose *.schema.json files are published. A directory that does | ||
| // not exist on this branch is skipped. | ||
| const SOURCE_DIRS = [ | ||
| 'packages/schemas/schemas', | ||
| 'packages/core/integrations/definitions/schema', | ||
| ]; | ||
|
|
||
| /** | ||
| * @returns {Array<{ source: string, id: string, hostedPath: string, target: string, content: string }>} | ||
| * @throws when a schema has no `$id` on the pattern, or two schemas claim one URL | ||
| */ | ||
| function planHostedSchemas() { | ||
| const plan = []; | ||
| const byHostedPath = new Map(); | ||
|
|
||
| for (const dir of SOURCE_DIRS) { | ||
| const absDir = path.join(REPO_ROOT, dir); | ||
| if (!fs.existsSync(absDir)) continue; | ||
|
|
||
| for (const file of fs.readdirSync(absDir).filter(f => f.endsWith('.schema.json')).sort()) { | ||
| const source = path.posix.join(dir, file); | ||
| const content = fs.readFileSync(path.join(absDir, file), 'utf8'); | ||
| const id = JSON.parse(content).$id; | ||
| const parsed = parseSchemaId(id); | ||
| if (!parsed) { | ||
| throw new Error( | ||
| `${source}: $id ${JSON.stringify(id)} is not https://friggframework.org/schemas/<name>/v<major>.<minor>.json` | ||
| ); | ||
| } | ||
| if (byHostedPath.has(parsed.hostedPath)) { | ||
| throw new Error( | ||
| `${source} and ${byHostedPath.get(parsed.hostedPath)} both have the $id ${id}` | ||
| ); | ||
| } | ||
| byHostedPath.set(parsed.hostedPath, source); | ||
| plan.push({ | ||
| source, | ||
| id, | ||
| hostedPath: parsed.hostedPath, | ||
| target: path.join(WEBSITE_ROOT, parsed.hostedPath), | ||
| content, | ||
| }); | ||
| } | ||
| } | ||
| return plan; | ||
| } | ||
|
|
||
| function main() { | ||
| const check = process.argv.includes('--check'); | ||
| const plan = planHostedSchemas(); | ||
| const stale = []; | ||
|
|
||
| for (const entry of plan) { | ||
| const current = fs.existsSync(entry.target) ? fs.readFileSync(entry.target, 'utf8') : null; | ||
| if (current === entry.content) continue; | ||
| if (check) { | ||
| stale.push(entry); | ||
| continue; | ||
| } | ||
| fs.mkdirSync(path.dirname(entry.target), { recursive: true }); | ||
| fs.writeFileSync(entry.target, entry.content); | ||
| console.log(`wrote website/${entry.hostedPath} (from ${entry.source})`); | ||
| } | ||
|
|
||
| if (check && stale.length > 0) { | ||
| for (const entry of stale) { | ||
| console.error(`website/${entry.hostedPath} is missing or differs from ${entry.source}`); | ||
| } | ||
| console.error('Run `npm run sync:hosted --workspace=packages/schemas` and commit the result.'); | ||
| process.exit(1); | ||
| } | ||
| if (check) console.log(`${plan.length} hosted schemas in sync.`); | ||
| } | ||
|
|
||
| if (require.main === module) main(); | ||
|
|
||
| module.exports = { planHostedSchemas, REPO_ROOT, WEBSITE_ROOT, SOURCE_DIRS }; | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
blocking (merge order with
#666): this renames$idto…/app-definition/v1.0.jsonbut the document body is still the pre-#666schema. ADR-051’s hosted-schemas amendment makes v1.0 immutable once published.Scenario: Ship this before
#666→ public v1.0 rejectspostgres.management: 'external'andfieldLevelEncryptionMethod: 'none', then#666cannot safely overwrite the same URL. Sync hosted copies from the post-#666schema (with those enums) before freezing v1.0.