diff --git a/gottext/CHANGELOG.md b/gottext/CHANGELOG.md index 205f006..b36b828 100644 --- a/gottext/CHANGELOG.md +++ b/gottext/CHANGELOG.md @@ -5,6 +5,16 @@ versioning follows [Semantic Versioning](https://semver.org/). While at 0.x, minor releases may break. Releases are tagged `gottext/vX.Y.Z` and publish from CI. +## [Unreleased] + +### Added + +- `pot` takes a `manifests` option, globs read from the root, and reads each plugin manifest's `name` and `description` and each setting's `label` and `help`, each key in lower case as pluginkit requires, with the manifest's path as the reference. A glob that matches no file and a manifest it cannot read are rejected. Before Node 22.17 its glob prints Node's experimental warning. + +### Fixed + +- `pot` keeps a message a Go marker or template names `__proto__`, which it used to leave out. + ## [0.8.1] - 2026-11-09 ### Fixed diff --git a/gottext/README.md b/gottext/README.md index d2c3a14..2c25035 100644 --- a/gottext/README.md +++ b/gottext/README.md @@ -41,6 +41,25 @@ template that writes a number through `%d`, `%i`, `%u`, `%e`, `%f` or `%g`, upper case `%E` and `%G` and a length such as `%ld` included, so each count reaches the reader through `formatNumber` and `%s`. +## Plugin manifests + +The build entry's `pot` also reads plugin manifests. Hand its +`manifests` option the globs that name them, read from the root, such +as `plugins/*/plugin.json`. Each manifest gives the template its +`name` and `description`, and the `label` and `help` of each entry in +its `settings`, each key in lower case as pluginkit requires, with the +manifest's path as the reference. It reads no other key, and it leaves +out an empty or null value. + +`pot` rejects a glob that matches no file, a path it cannot read as a +file, a manifest that is not a JSON object, a `settings` that is not a +list of objects, and any of those four keys holding something other +than text. The error names the glob or the manifest. + +`manifests` reads its globs through Node's `fs.globSync`, which is +stable from Node 22.17. On Node 22.13 to 22.16 it works but prints +Node's experimental warning. + ## License Apache-2.0. See NOTICE for how the GPL licensed runtime peer is diff --git a/gottext/src/pot.ts b/gottext/src/pot.ts index 0bfbaf1..9a63823 100644 --- a/gottext/src/pot.ts +++ b/gottext/src/pot.ts @@ -2,8 +2,8 @@ import { GettextExtractor, JsExtractors } from 'gettext-extractor' import { po, type GetTextTranslation } from 'gettext-parser' -import { readFileSync, readdirSync } from 'node:fs' -import { join } from 'node:path' +import { globSync, readFileSync, readdirSync } from 'node:fs' +import { join, resolve } from 'node:path' /** IGNORED is the set of paths that can never name a source, whatever a consumer ships. */ const IGNORED = ['**/node_modules/**', '**/*.d.ts', '**/*.test.ts', '**/*.test.tsx'] @@ -23,6 +23,29 @@ const MARKER_CALL = /\bMsgid\("((?:[^"\\]|\\.)*)"\)/g /** DEFAULT_DOMAIN is the text domain a call naming none belongs to. */ const DEFAULT_DOMAIN = 'default' +/** ManifestKey is a key of a plugin manifest whose text the template carries, in lower case. */ +type ManifestKey = 'name' | 'description' | 'label' | 'help' + +/** MANIFEST_TEXTS is the keys of a plugin manifest whose text the template carries. */ +const MANIFEST_TEXTS: ManifestKey[] = ['name', 'description'] + +/** SETTING_TEXTS is the keys of each setting a plugin manifest declares whose text the template carries. */ +const SETTING_TEXTS: ManifestKey[] = ['label', 'help'] + +/** Entry is one JSON object a plugin manifest holds, read key by key. */ +type Entry = Record + +/** Manifest is one plugin manifest read whole. */ +interface Manifest { + /** path is where the manifest sits, as its glob names it, and the reference its texts carry. */ + path: string + /** entry is the top object the manifest holds. */ + entry: Entry +} + +/** Translations is every entry of a template, by context then message. */ +type Translations = Record> + /** Extractor is what the parser runs over every piece of a source. */ type Extractor = ReturnType @@ -78,6 +101,8 @@ export interface PotOptions { ignored?: string[] /** goRoots are the directories a Go walk reads, none by default. */ goRoots?: string[] + /** manifests are the globs naming the plugin manifests to read, from the root, none by default. */ + manifests?: string[] } /** @@ -149,6 +174,156 @@ export function goMessages(root: string, dirs: string[]): string[] { return [...held] } +/** + * Returns whether a JSON value is an object, rather than a list, a text, a number or null. + * @param value - The value to check. + * @returns True when the value is an object. + */ +function isEntry(value: unknown): value is Entry { + return value instanceof Object && !Array.isArray(value) +} + +/** + * Returns the value a manifest object holds under a key as its own, none when it only inherits one. + * @param entry - The object to read. + * @param key - The key to read. + * @returns The value, or nothing. + */ +function ownValue(entry: Partial>, key: K): unknown { + return Object.hasOwn(entry, key) ? entry[key] : undefined +} + +/** + * Returns the text one key of a manifest object holds, none when the key is absent, null or empty. + * @param manifest - The manifest the object sits in, named in an error. + * @param entry - The object to read. + * @param key - The key to read. + * @returns The text, or nothing. + */ +function textOf(manifest: Manifest, entry: Entry, key: ManifestKey): string[] { + const text = ownValue(entry, key) ?? '' + if (typeof text !== 'string') { + throw new Error(`the manifest ${manifest.path} holds a ${key} that is not text`) + } + return text === '' ? [] : [text] +} + +/** + * Returns the settings a manifest declares, none when it names none. + * @param manifest - The manifest to read. + * @returns The declared settings. + */ +function settingsOf(manifest: Manifest): Entry[] { + const settings = ownValue(manifest.entry, 'settings') ?? [] + if (!Array.isArray(settings) || !settings.every(isEntry)) { + throw new Error(`the manifest ${manifest.path} holds settings that are not a list of objects`) + } + return settings +} + +/** + * Returns the plugin manifest at one path, read whole. + * @param options - The root the path resolves against. + * @param path - The manifest's path, as its glob names it. + * @returns The manifest with its top object. + */ +function manifestAt(options: PotOptions, path: string): Manifest { + let body: string + try { + body = readFileSync(resolve(options.root, path), 'utf8') + } catch (cause) { + throw new Error(`the manifest ${path} cannot be read`, { cause }) + } + let entry: unknown + try { + entry = JSON.parse(body) + } catch { + throw new Error(`the manifest ${path} holds JSON this extractor cannot read`) + } + if (!isEntry(entry)) { + throw new Error(`the manifest ${path} holds no JSON object`) + } + return { path, entry } +} + +/** + * Returns the texts one plugin manifest hands the template. + * @param manifest - The manifest to read. + * @returns The plugin's name and description, then each setting's label and help. + */ +function manifestTexts(manifest: Manifest): string[] { + return [ + ...MANIFEST_TEXTS.flatMap((key) => textOf(manifest, manifest.entry, key)), + ...settingsOf(manifest).flatMap((setting) => SETTING_TEXTS.flatMap((key) => textOf(manifest, setting, key))), + ] +} + +/** + * Returns the paths the manifest globs match, rejecting a glob that matches none. + * @param options - The root and the manifest globs to read. + * @returns The paths found, as the globs name them, in a settled order. + */ +function manifestPaths(options: PotOptions): string[] { + return (options.manifests ?? []).flatMap((pattern) => { + const found = globSync(pattern, { cwd: options.root }) + if (found.length === 0) { + throw new Error(`no manifest matches ${pattern}`) + } + return found + }).sort() +} + +/** + * Returns each text the plugin manifests hand the template, with the manifests holding it. + * @param options - The root and the manifest globs to read. + * @returns The texts found, each with the paths of its manifests in a settled order. + */ +function manifestMessages(options: PotOptions): Map> { + const held = new Map>() + for (const path of manifestPaths(options)) { + for (const text of manifestTexts(manifestAt(options, path))) { + held.set(text, (held.get(text) ?? new Set()).add(path)) + } + } + return held +} + +/** + * Returns the value a table owns under a key, first defining a made one as its own when it owns none. + * @param table - The table to read. + * @param key - The key to read, which may name an Object member such as __proto__ that every table inherits. + * @param made - Returns the value to define when the table owns none. + * @returns The value the table owns under the key. + */ +function owned(table: Record, key: K, made: () => NoInfer): T { + if (!Object.hasOwn(table, key)) { + Object.defineProperty(table, key, { value: made(), enumerable: true, writable: true, configurable: true }) + } + return table[key] +} + +/** + * Returns the entries a template holds under one context, starting them when it holds none. + * @param translations - The template entries, by context then message. + * @param context - The context, which may name an Object member. + * @returns The entries under the context, by message. + */ +function contextOf(translations: Translations, context: string): Record { + return owned(translations, context, () => ({})) +} + +/** + * Adds each text the plugin manifests hold to the template, naming its manifests as its reference. + * @param translations - The template entries, by context then message. + * @param options - The root and the manifest globs to read. + */ +function addManifests(translations: Translations, options: PotOptions): void { + for (const [text, paths] of manifestMessages(options)) { + const entry = owned(contextOf(translations, ''), text, () => ({ msgid: text, msgstr: [''] })) + entry.comments = { reference: [...paths].join('\n') } + } +} + /** * Returns the key an entry is ordered by. * @param entry - The entry to key. @@ -248,16 +423,14 @@ function entryOf(message: Found): GetTextTranslation { * @returns The template as UTF-8 bytes. */ export function pot(options: PotOptions): Buffer { - const translations: Record> = {} - for (const text of goMessages(options.root, options.goRoots ?? [])) { - translations[''] ??= {} - translations[''][text] = { msgid: text, msgstr: [''] } - } + const translations: Translations = {} for (const message of messages(options)) { - const context = message.context ?? '' - translations[context] ??= {} - translations[context][message.text] = entryOf(message) + owned(contextOf(translations, message.context ?? ''), message.text, () => entryOf(message)) + } + for (const text of goMessages(options.root, options.goRoots ?? [])) { + owned(contextOf(translations, ''), text, () => ({ msgid: text, msgstr: [''] })) } + addManifests(translations, options) return po.compile( { charset: 'UTF-8', diff --git a/gottext/test/build.test.ts b/gottext/test/build.test.ts index 3abe3a6..c537ed5 100644 --- a/gottext/test/build.test.ts +++ b/gottext/test/build.test.ts @@ -215,6 +215,18 @@ test('names the messages a Go marker declares', () => { expect(held).toContain('msgid "Saved"') }) +test('keeps the plural form the sources give a message a Go marker declares too', () => { + const root = rootWith({ + 'src/a.ts': "_n('Saved', 'Saved items', 2, 'probe')\n", + 'internal/thing.go': 'package thing\n\nvar held = Msgid("Saved")\n', + }) + + const held = pot({ domain: 'probe', root, sources: SOURCES, goRoots: ['internal'] }).toString() + + expect(held).toContain('\n\nmsgid "Saved"\nmsgid_plural "Saved items"\nmsgstr[0] ""\nmsgstr[1] ""\n') + expect(held).not.toContain('\n\nmsgid "Saved"\nmsgstr ""\n') +}) + test('names the messages a Go template asks for', () => { const root = rootWith({ 'src/a.ts': "__('Older posts', 'probe')\n", @@ -273,6 +285,216 @@ test('answers the messages a Go root declares', () => { expect(goMessages(root, ['internal'])).toEqual(['Saved']) }) +/** NOTES is where the manifest cases write a plugin manifest. */ +const NOTES = 'plugins/notes/plugin.json' + +/** MANIFESTS is the glob the manifest cases read plugin manifests through. */ +const MANIFESTS = ['plugins/*/plugin.json'] + +/** MESSAGE_LINE is the shape of each message line a template holds. */ +const MESSAGE_LINE = /^msgid ".*"$/gm + +/** + * Returns the template built from a root holding only the given plugin manifests. + * @param files - The manifests to write, keyed by path under the root. + * @param manifests - The globs naming the manifests to read. + * @returns The template as text. + */ +function potOfManifests(files: Record, manifests: string[] = MANIFESTS): string { + return pot({ domain: 'probe', root: rootWith(files), sources: SOURCES, manifests }).toString() +} + +test('names the name and description a plugin manifest declares', () => { + const held = potOfManifests({ + [NOTES]: JSON.stringify({ id: 'notes', name: 'Notes', description: 'Keeps short notes beside each post.' }), + }) + + expect(held).toContain('msgid "Notes"') + expect(held).toContain('msgid "Keeps short notes beside each post."') +}) + +test('names the label and help of each setting a plugin manifest declares', () => { + const held = potOfManifests({ + [NOTES]: JSON.stringify({ + id: 'notes', + name: 'Notes', + settings: [ + { key: 'title', type: 'text', label: 'Notes title', help: 'The heading above the notes' }, + { key: 'shown', type: 'count', default: '5', label: 'Notes shown' }, + ], + }), + }) + + expect(held).toContain('msgid "Notes title"') + expect(held).toContain('msgid "The heading above the notes"') + expect(held).toContain('msgid "Notes shown"') +}) + +test('leaves out every other key a plugin manifest holds', () => { + const held = potOfManifests({ + [NOTES]: JSON.stringify({ + id: 'notes-id', + name: 'Notes', + title: 'Notes heading', + version: '0.0.1', + backend: 'example.com/notes', + hooks: ['public.head-tags'], + menu: [{ label: 'Open notes', screen: 'notes', capability: 'edit_posts' }], + settings: [{ key: 'tone', type: 'choice', default: 'calm', options: ['calm', 'loud'], label: 'Tone' }], + }), + }) + + expect(held.match(MESSAGE_LINE)).toEqual(['msgid ""', 'msgid "Notes"', 'msgid "Tone"']) +}) + +test('leaves out a manifest key spelled in another case', () => { + const held = potOfManifests({ [NOTES]: JSON.stringify({ Name: 'Notes' }) }) + + expect(held.match(MESSAGE_LINE)).toEqual(['msgid ""']) +}) + +test.each([ + { key: 'description', manifest: { name: 'Notes' } }, + { key: 'settings', manifest: { name: 'Notes' } }, + { key: 'label', manifest: { name: 'Notes', settings: [{ key: 'title', type: 'text' }] } }, + { key: 'help', manifest: { name: 'Notes', settings: [{ key: 'title', type: 'text' }] } }, +])('reads only the $key a manifest holds itself, when a source context gives every object one', ({ key, manifest }) => { + const root = rootWith({ + 'src/a.ts': `_x('${key}', '__proto__', 'probe')\n`, + [NOTES]: JSON.stringify(manifest), + }) + + try { + const held = pot({ domain: 'probe', root, sources: SOURCES, manifests: MANIFESTS }).toString() + + expect(held.match(MESSAGE_LINE)).toEqual(['msgid ""', 'msgid "Notes"']) + } finally { + Reflect.deleteProperty(Object.prototype, key) + } +}) + +test.each([ + { name: 'Notes', description: '' }, + { name: 'Notes', description: null }, + { name: 'Notes', settings: null }, + { name: 'Notes', settings: [{ key: 'title', type: 'text', label: '', help: null }] }, +])('leaves out an empty or null value a plugin manifest holds: %j', (manifest) => { + const held = potOfManifests({ [NOTES]: JSON.stringify(manifest) }) + + expect(held.match(MESSAGE_LINE)).toEqual(['msgid ""', 'msgid "Notes"']) +}) + +test('names the manifest a message came from as its reference', () => { + const held = potOfManifests({ [NOTES]: JSON.stringify({ id: 'notes', name: 'Notes' }) }) + + expect(held).toContain('\n\n#: plugins/notes/plugin.json\nmsgid "Notes"\n') +}) + +test('names every manifest declaring one message as its reference, in a settled order', () => { + const held = potOfManifests({ + 'plugins/zines/plugin.json': JSON.stringify({ name: 'Zines', settings: [{ key: 'title', label: 'Title' }] }), + [NOTES]: JSON.stringify({ name: 'Notes', settings: [{ key: 'title', label: 'Title' }] }), + }) + + expect(held).toContain('\n\n#: plugins/notes/plugin.json\n#: plugins/zines/plugin.json\nmsgid "Title"\n') +}) + +test('names a manifest once when it declares a message twice or two globs match it', () => { + const held = potOfManifests( + { [NOTES]: JSON.stringify({ name: 'Notes', settings: [{ key: 'notes', label: 'Notes' }] }) }, + [...MANIFESTS, NOTES], + ) + + expect(held).toContain('\n\n#: plugins/notes/plugin.json\nmsgid "Notes"\n') +}) + +test('keeps the plural form the sources give a message a manifest declares too', () => { + const root = rootWith({ + 'src/a.ts': "_n('Note', 'Notes', 2, 'probe')\n", + [NOTES]: JSON.stringify({ name: 'Note' }), + }) + + const held = pot({ domain: 'probe', root, sources: SOURCES, manifests: MANIFESTS }).toString() + + expect(held).toContain('\n\n#: plugins/notes/plugin.json\nmsgid "Note"\nmsgid_plural "Notes"\n') + expect(held.match(MESSAGE_LINE)).toEqual(['msgid ""', 'msgid "Note"']) +}) + +test('reads no plugin manifest unless it is given some', () => { + const root = rootWith({ + 'src/a.ts': "__('Older posts', 'probe')\n", + [NOTES]: JSON.stringify({ name: 'Notes' }), + }) + + const held = pot({ domain: 'probe', root, sources: SOURCES }).toString() + + expect(held).not.toContain('Notes') +}) + +test('rejects a manifest glob that matches no file', () => { + expect(() => potOfManifests({ 'src/a.ts': "__('Older posts', 'probe')\n" })) + .toThrow('no manifest matches plugins/*/plugin.json') +}) + +test('rejects a manifest path that is a folder, naming the path', () => { + expect(() => potOfManifests({ [`${NOTES}/notes.txt`]: 'Keeps short notes' })) + .toThrow('the manifest plugins/notes/plugin.json cannot be read') +}) + +test('rejects a manifest holding JSON it cannot read', () => { + expect(() => potOfManifests({ [NOTES]: '{"name": "Notes",' })) + .toThrow('the manifest plugins/notes/plugin.json holds JSON this extractor cannot read') +}) + +test.each(['[]', 'null', '"Notes"'])('rejects a manifest holding no JSON object: %s', (body) => { + expect(() => potOfManifests({ [NOTES]: body })) + .toThrow('the manifest plugins/notes/plugin.json holds no JSON object') +}) + +test.each([ + { key: 'name', manifest: { name: 184467235 } }, + { key: 'description', manifest: { name: 'Notes', description: ['Keeps short notes'] } }, + { key: 'label', manifest: { name: 'Notes', settings: [{ key: 'title', label: true }] } }, + { key: 'help', manifest: { name: 'Notes', settings: [{ key: 'title', help: { text: 'The heading' } }] } }, +])('rejects a manifest whose $key holds something other than text', ({ key, manifest }) => { + expect(() => potOfManifests({ [NOTES]: JSON.stringify(manifest) })) + .toThrow(`the manifest plugins/notes/plugin.json holds a ${key} that is not text`) +}) + +test('names the messages a manifest declares under the names of Object members', () => { + const held = potOfManifests({ + [NOTES]: JSON.stringify({ name: 'constructor', settings: [{ key: 'title', label: '__proto__' }] }), + }) + + expect(held).toContain('\n\n#: plugins/notes/plugin.json\nmsgid "__proto__"\n') + expect(held).toContain('\n\n#: plugins/notes/plugin.json\nmsgid "constructor"\n') + expect(Object.hasOwn(Object.prototype, 'comments')).toBe(false) + expect(Object.hasOwn(Object, 'comments')).toBe(false) + expect(({} as { comments?: unknown }).comments).toBeUndefined() +}) + +test('keeps the entry a Go marker gives a message named like an Object member that a manifest declares too', () => { + const root = rootWith({ + 'internal/thing.go': 'package thing\n\nvar held = []string{Msgid("constructor"), Msgid("__proto__")}\n', + [NOTES]: JSON.stringify({ name: 'constructor', description: '__proto__' }), + }) + + const held = pot({ domain: 'probe', root, sources: SOURCES, goRoots: ['internal'], manifests: MANIFESTS }).toString() + + expect(held.match(MESSAGE_LINE)).toEqual(['msgid ""', 'msgid "__proto__"', 'msgid "constructor"']) + expect(held).toContain('\n\n#: plugins/notes/plugin.json\nmsgid "__proto__"\n') + expect(held).toContain('\n\n#: plugins/notes/plugin.json\nmsgid "constructor"\n') +}) + +test.each([ + { name: 'Notes', settings: { title: 'Notes title' } }, + { name: 'Notes', settings: ['title'] }, + { name: 'Notes', settings: [null] }, +])('rejects a manifest whose settings are not a list of objects: %j', (manifest) => { + expect(() => potOfManifests({ [NOTES]: JSON.stringify(manifest) })) + .toThrow('the manifest plugins/notes/plugin.json holds settings that are not a list of objects') +}) + const CATALOGUE = `msgid "" msgstr "" "Language: es-ES\\n" diff --git a/pluginkit/CHANGELOG.md b/pluginkit/CHANGELOG.md index a7aa3de..ada4747 100644 --- a/pluginkit/CHANGELOG.md +++ b/pluginkit/CHANGELOG.md @@ -5,10 +5,15 @@ Releases of this module are tagged `pluginkit/vX.Y.Z`. Releases up to ## Unreleased -- `PluginStore`, with `Records`, `Activate` and `Pause`, is an application's record of each plugin's state: not installed, inactive, active or paused, with the text of the failure that paused it. -- `NewBoot`, `Register`, `Boot.Pause` and `Boot.Started` carry one boot from the records to the start: a plugin seen for the first time is recorded active, inactive and not installed plugins are never registered, a plugin that fails to register, migrate or start is paused, and a paused plugin that starts again is active with no error. +- `PluginStore`, with `Records`, `Activate` and `Pause`, is an application's record of each plugin's state: not installed, inactive, active or paused, with the step a paused plugin failed at and its own error kept apart. A store keeps any step word as written. +- `NewBoot`, `Register`, `Boot.Pause` and `Boot.Started` carry one boot from the records to the start: a plugin seen for the first time is recorded active, inactive and not installed plugins are never registered, a plugin that fails to register, migrate or start is paused at that step with its own error, and a paused plugin that starts again is active with no step and no error. `Boot.Pause` takes a `Failure`, so an application pauses a plugin at a step of its own. +- `StepRoles` names the step where an application declares a plugin's roles, so every application pauses a plugin's roles at one word. +- `Failure.Reason` is the plugin's own error with nothing in front, and a recovered panic reads `panicked: `. `Failure.Err` keeps the whole text, so log lines read as before. - A boot whose context ends pauses nothing, and a store read or write that fails is returned to the application. - `pluginstoretest.Run` checks any `PluginStore` against the contract, and `pluginstoretest.NewMemory` is a store in memory that keeps it. +- `Installed` lists one `InstalledPlugin` per installed plugin, with the JSON names `id`, `name`, `description`, `version`, `status`, `paused_step` and `paused_reason`, sorted by name without regard to case, then by id. It leaves out a plugin the records hold as not installed and a record with no manifest, and lists a manifest with no record as active. The step and the reason are empty unless the plugin is paused. +- `wire.Manifest` reads `description`, which no longer sits in `Extra`, a breaking change. +- `wire` rejects a manifest that spells a key it reads in another case, such as `Name`, repeats a name in one object, or holds text that is not valid UTF-8, as bytes or as an escaped surrogate with no pair, a breaking change. - `RegisterEach` and `Register` take only plugins with an `ID() string` method, and fail at `StepRegister` a plugin whose `ID` is not its entry's id, or a `Register` that answers no plugin, a breaking change. - `Protect` takes the plugin's id and a `RouteSettings`, which holds the middleware as `Wrap`, a breaking change. - `Protect` recovers each panic of a plugin's handler, on its public paths too. While nothing went out, `RouteSettings.Answer` answers it, else the connection is cut, and `RouteSettings.Report` receives a `RouteFailure` with the stack. diff --git a/pluginkit/boot.go b/pluginkit/boot.go index 5fca55f..3f56de9 100644 --- a/pluginkit/boot.go +++ b/pluginkit/boot.go @@ -62,7 +62,7 @@ func (b *Boot) pauseEach(ctx context.Context, failures []Failure) error { if failure.Step == StepRecord { continue } - if err := b.Pause(ctx, failure.ID, failure.Err); err != nil { + if err := b.Pause(ctx, failure); err != nil { return err } } @@ -77,14 +77,14 @@ func (b *Boot) admit(ctx context.Context, id string) (bool, error) { return true, b.activate(ctx, id) } -// Pause pauses the plugin id for failure, a step that failed or a reason of the application's own. -func (b *Boot) Pause(ctx context.Context, id string, failure error) error { - return guarded(ctx, "pause "+id, func(ctx context.Context) error { - return b.store.Pause(ctx, id, failure.Error()) +// Pause pauses the plugin the failure names, recording its step and its reason apart. +func (b *Boot) Pause(ctx context.Context, failure Failure) error { + return guarded(ctx, "pause "+failure.ID, func(ctx context.Context) error { + return b.store.Pause(ctx, failure.ID, failure.Step, failure.Reason) }) } -// activate marks the plugin id active and clears its error. +// activate marks the plugin id active and clears its step and its error. func (b *Boot) activate(ctx context.Context, id string) error { return guarded(ctx, "activate "+id, func(ctx context.Context) error { return b.store.Activate(ctx, id) }) } diff --git a/pluginkit/boot_test.go b/pluginkit/boot_test.go index fe703c3..39bd055 100644 --- a/pluginkit/boot_test.go +++ b/pluginkit/boot_test.go @@ -42,13 +42,13 @@ func (s *countingStore) Activate(ctx context.Context, id string) error { return s.inner.Activate(ctx, id) } -// Pause notes the write and pauses id, or answers the failure it was told. -func (s *countingStore) Pause(ctx context.Context, id, failure string) error { - s.writes = append(s.writes, "pause "+id+": "+failure) +// Pause notes the write and pauses id at step with reason, or answers the failure it was told. +func (s *countingStore) Pause(ctx context.Context, id string, step pluginkit.Step, reason string) error { + s.writes = append(s.writes, "pause "+id+" at "+string(step)+": "+reason) if s.writeErr != nil { return s.writeErr } - return s.inner.Pause(ctx, id, failure) + return s.inner.Pause(ctx, id, step, reason) } // assertErrorFree stops t when err is set. @@ -182,8 +182,9 @@ func TestRegisterTriesAPausedPluginAgainWithoutWriting(t *testing.T) { t.Parallel() var calls []string - store := storeOf(record("events", pluginkit.PluginActive), - pluginkit.PluginRecord{ID: "feed", State: pluginkit.PluginPaused, LastError: "a setting is missing"}) + store := storeOf(record("events", pluginkit.PluginActive), pluginkit.PluginRecord{ + ID: "feed", State: pluginkit.PluginPaused, Step: pluginkit.StepRegister, LastError: "a setting is missing", + }) outcome := registerAll(t, newBoot(t, store), entry("events", &calls, succeeds), entry("feed", &calls, succeeds)) @@ -203,8 +204,8 @@ func TestRegisterPausesEachPluginThatFailsToRegister(t *testing.T) { wantEqual(t, "registered", registeredIDs(outcome), []string{"events"}) wantEqual(t, "writes", store.writes, []string{ - "pause feed: pluginkit: feed register: the title is too long", - "pause gallery: pluginkit: gallery register panicked: boom", + "pause feed at register: the title is too long", + "pause gallery at register: panicked: boom", }) } @@ -260,33 +261,48 @@ func TestRegisterPausesNothingWhenTheContextEnded(t *testing.T) { wantEqual(t, "writes", store.writes, []string(nil)) } -func TestBootPausePausesAPluginForTheApplicationsReason(t *testing.T) { +func TestBootPausePausesAPluginAtTheApplicationsOwnStep(t *testing.T) { t.Parallel() store := storeOf(record("forum", pluginkit.PluginActive)) - err := newBoot(t, store).Pause(t.Context(), "forum", errors.New("forum declares a role it cannot accept")) + err := newBoot(t, store).Pause(t.Context(), pluginkit.Failure{ + ID: "forum", Step: pluginkit.StepRoles, Err: errors.New("forum roles: the role \"editor\" is taken"), + Reason: "the role \"editor\" is taken", + }) assertErrorFree(t, err) wantEqual(t, "records", held(t, store), map[string]pluginkit.PluginRecord{"forum": { - ID: "forum", State: pluginkit.PluginPaused, LastError: "forum declares a role it cannot accept", + ID: "forum", State: pluginkit.PluginPaused, Step: pluginkit.StepRoles, LastError: "the role \"editor\" is taken", }}) } +func TestStepRolesIsTheWordEveryApplicationPausesRolesAt(t *testing.T) { + t.Parallel() + + wantEqual(t, "StepRoles", pluginkit.StepRoles, pluginkit.Step("roles")) +} + func TestStartedPausesEachPluginThatFailedToMigrateOrStart(t *testing.T) { t.Parallel() store := storeOf(record("feed", pluginkit.PluginActive), record("gallery", pluginkit.PluginActive)) err := newBoot(t, store).Started(t.Context(), pluginkit.StartOutcome{Failed: []pluginkit.Failure{ - {ID: "feed", Step: pluginkit.StepMigrate, Err: errors.New("pluginkit: feed migrate: schema exploded")}, - {ID: "gallery", Step: pluginkit.StepStart, Err: errors.New("pluginkit: gallery start: no route table")}, + { + ID: "feed", Step: pluginkit.StepMigrate, Err: errors.New("pluginkit: feed migrate: schema exploded"), + Reason: "schema exploded", + }, + { + ID: "gallery", Step: pluginkit.StepStart, Err: errors.New("pluginkit: gallery start: no route table"), + Reason: "no route table", + }, }}) assertErrorFree(t, err) wantEqual(t, "writes", store.writes, []string{ - "pause feed: pluginkit: feed migrate: schema exploded", - "pause gallery: pluginkit: gallery start: no route table", + "pause feed at migrate: schema exploded", + "pause gallery at start: no route table", }) } @@ -298,20 +314,27 @@ func TestStartedLeavesAFailedMigrationRecordAlone(t *testing.T) { err := newBoot(t, store).Started(t.Context(), pluginkit.StartOutcome{ Started: []pluginkit.StartedPlugin{{ID: "feed"}}, Failed: []pluginkit.Failure{ - {ID: "feed", Step: pluginkit.StepRecord, Err: errors.New("pluginkit: feed record: ledger locked")}, - {ID: "gallery", Step: pluginkit.StepStart, Err: errors.New("pluginkit: gallery start: no route table")}, + { + ID: "feed", Step: pluginkit.StepRecord, Err: errors.New("pluginkit: feed record: ledger locked"), + Reason: "ledger locked", + }, + { + ID: "gallery", Step: pluginkit.StepStart, Err: errors.New("pluginkit: gallery start: no route table"), + Reason: "no route table", + }, }, }) assertErrorFree(t, err) - wantEqual(t, "writes", store.writes, []string{"pause gallery: pluginkit: gallery start: no route table"}) + wantEqual(t, "writes", store.writes, []string{"pause gallery at start: no route table"}) } func TestStartedActivatesAPausedPluginThatStarted(t *testing.T) { t.Parallel() - store := storeOf(record("events", pluginkit.PluginActive), - pluginkit.PluginRecord{ID: "feed", State: pluginkit.PluginPaused, LastError: "a setting is missing"}) + store := storeOf(record("events", pluginkit.PluginActive), pluginkit.PluginRecord{ + ID: "feed", State: pluginkit.PluginPaused, Step: pluginkit.StepStart, LastError: "a setting is missing", + }) err := newBoot(t, store).Started(t.Context(), pluginkit.StartOutcome{ Started: []pluginkit.StartedPlugin{{ID: "events"}, {ID: "feed"}}, diff --git a/pluginkit/features/boot.feature b/pluginkit/features/boot.feature index 8a209ec..b52eaf7 100644 --- a/pluginkit/features/boot.feature +++ b/pluginkit/features/boot.feature @@ -4,9 +4,9 @@ Feature: Booting plugins and pausing the one that fails purpose. Paused means the boot stopped the plugin after it failed, as WordPress's recovery mode does. Each boot reads the records once, registers the active and paused plugins, lets the application run its - own steps, then starts them. A plugin that fails is paused with its - error, and the others still start. A paused plugin is tried again at - every boot. + own steps, then starts them. A plugin that fails is paused with the + step it failed at and its own error, kept apart, and the others still + start. A paused plugin is tried again at every boot. Scenario: The first boot records each compiled plugin as active Given the compiled plugins "events" and "feed" @@ -28,21 +28,28 @@ Feature: Booting plugins and pausing the one that fails And the Register of "feed" fails with "the title is too long" When the application boots its plugins Then "events" and "gallery" started, in that order - And the store records "feed" as paused with "pluginkit: feed register: the title is too long" + And the store records "feed" as paused at "register" with "the title is too long" Scenario: A plugin whose Register panics is paused Given the compiled plugins "events" and "feed" And the Register of "feed" panics with "boom" When the application boots its plugins Then "events" started - And the store records "feed" as paused with "pluginkit: feed register panicked: boom" + And the store records "feed" as paused at "register" with "panicked: boom" + + Scenario: A plugin whose Register error panics when read is paused and the others start + Given the compiled plugins "events", "feed" and "gallery" + And the Register of "feed" fails with an error whose text panics with "text exploded" + When the application boots its plugins + Then "events" and "gallery" started, in that order + And the store records "feed" as paused at "register" with "%!v(PANIC=Error method: text exploded)" Scenario: A plugin that calls itself by another id is paused under its entry's id Given the compiled plugins "events" and "feed" And the Register of "feed" answers a plugin that calls itself "news" When the application boots its plugins Then "events" started - And the store records "feed" as paused with "pluginkit: feed register: the plugin calls itself "news"" + And the store records "feed" as paused at "register" with "the plugin calls itself "news"" And the store holds no record of "news" Scenario: A plugin whose migration fails is paused and never starts @@ -51,14 +58,14 @@ Feature: Booting plugins and pausing the one that fails When the application boots its plugins Then "events" started And "feed" never started - And the store records "feed" as paused with "pluginkit: feed migrate: schema exploded" + And the store records "feed" as paused at "migrate" with "schema exploded" Scenario: A plugin whose Start fails is paused Given the compiled plugins "events" and "feed" And the Start of "feed" fails with "no route table" When the application boots its plugins Then "events" started - And the store records "feed" as paused with "pluginkit: feed start: no route table" + And the store records "feed" as paused at "start" with "no route table" Scenario: A plugin whose migration record fails still starts and stays active Given the compiled plugins "events" and "feed" @@ -83,31 +90,31 @@ Feature: Booting plugins and pausing the one that fails | inactive | | not installed | - Scenario: A paused plugin that now starts is active again with no error + Scenario: A paused plugin that now starts is active again with no step and no error Given the compiled plugins "events" and "feed" And the store records "events" as active - And the store records "feed" as paused with "a setting is missing" + And the store records "feed" as paused at "register" with "a setting is missing" When the application boots its plugins Then "events" and "feed" started, in that order - And the store records "feed" as active with no error + And the store records "feed" as active with no step and no error - Scenario: A paused plugin that fails again stays paused with its new error + Scenario: A paused plugin that fails again stays paused at its new step with its new error Given the compiled plugins "events" and "feed" And the store records "events" as active - And the store records "feed" as paused with "a setting is missing" + And the store records "feed" as paused at "register" with "a setting is missing" And the Start of "feed" fails with "no route table" When the application boots its plugins Then "events" started - And the store records "feed" as paused with "pluginkit: feed start: no route table" + And the store records "feed" as paused at "start" with "no route table" - Scenario: The application pauses a plugin for a reason of its own + Scenario: The application pauses a plugin at the roles step for a reason of its own Given the compiled plugins "events" and "forum" And the store records "events" and "forum" as active And the application finds that "forum" declares a role it cannot accept When the application boots its plugins Then "events" started And "forum" never started - And the store records "forum" as paused with "forum declares a role it cannot accept" + And the store records "forum" as paused at "roles" with "it declares a role the application cannot accept" Scenario: A boot whose context ends pauses nothing Given the compiled plugins "events", "feed" and "gallery" diff --git a/pluginkit/features/features_test.go b/pluginkit/features/features_test.go index c3c2acb..e952d57 100644 --- a/pluginkit/features/features_test.go +++ b/pluginkit/features/features_test.go @@ -50,6 +50,10 @@ func TestBoot(t *testing.T) { runFeature(t, "boot.feature", initializeBoot(t)) } +func TestInstalled(t *testing.T) { + runFeature(t, "installed.feature", initializeInstalled(t)) +} + func TestRoutes(t *testing.T) { runFeature(t, "routes.feature", initializeRoutes()) } diff --git a/pluginkit/features/installed.feature b/pluginkit/features/installed.feature new file mode 100644 index 0000000..6dd7fe0 --- /dev/null +++ b/pluginkit/features/installed.feature @@ -0,0 +1,74 @@ +Feature: Listing the installed plugins + An application lists the plugins it holds on a Plugins screen, as + WordPress lists its installed plugins. The list joins the manifest of + each compiled plugin with the record the store keeps of it. Each row + holds the plugin's id, the name, description and version its manifest + gives, and the state its record holds. A paused row also holds the step + the plugin failed at and its own error, kept apart, so a screen can + build its sentence for the step from a translated template. A plugin + the application has not installed and a record whose plugin is no + longer compiled are left out. + + Scenario: An active plugin is listed with the name, description and version of its manifest + Given the compiled plugins "feed" + And the manifest of "feed" names it "Feed" + And the manifest of "feed" describes it as "Serves the published posts as an RSS feed." + And the manifest of "feed" gives the version "0.0.1" + And the store records "feed" as active + When the application lists the installed plugins + Then the list holds "feed" as "active" + + Scenario: A paused plugin is listed with the step it failed at and its own error + Given the compiled plugins "feed" + And the manifest of "feed" names it "Feed" + And the store records "feed" as paused at "register" with "the title is too long" + When the application lists the installed plugins + Then the list holds "feed" as paused at "register", its reason reading "the title is too long" + + Scenario: An inactive plugin is listed as inactive + Given the compiled plugins "feed" + And the manifest of "feed" names it "Feed" + And the store records "feed" as inactive + When the application lists the installed plugins + Then the list holds "feed" as "inactive" + + Scenario: A plugin the store records as not installed is left out + Given the compiled plugins "events" and "feed" + And the manifest of "events" names it "Events" + And the manifest of "feed" names it "Feed" + And the store records "events" as active + And the store records "feed" as not installed + When the application lists the installed plugins + Then the list holds "events" as "active" + And the list leaves out "feed" + + Scenario: A record of a plugin that is no longer compiled is left out + Given the compiled plugins "events" + And the manifest of "events" names it "Events" + And the store records "events" and "gallery" as active + When the application lists the installed plugins + Then the list holds "events" as "active" + And the list leaves out "gallery" + + Scenario: A compiled plugin with no record is listed as active + Given the compiled plugins "feed" + And the manifest of "feed" names it "Feed" + And the store holds no record + When the application lists the installed plugins + Then the list holds "feed" as "active" + + Scenario: A manifest with no description or version lists both as empty + Given the compiled plugins "feed" + And the manifest of "feed" names it "Feed" + And the store records "feed" as active + When the application lists the installed plugins + Then the list holds "feed" as "active" with no description and no version + + Scenario: The plugins are listed by name, then by id + Given the compiled plugins "events", "feed" and "gallery" + And the manifest of "events" names it "Calendar" + And the manifest of "feed" names it "Atom" + And the manifest of "gallery" names it "Calendar" + And the store holds no record + When the application lists the installed plugins + Then the list names "feed", "events" and "gallery", in that order diff --git a/pluginkit/features/screens.feature b/pluginkit/features/screens.feature index a7c8a6f..998b686 100644 --- a/pluginkit/features/screens.feature +++ b/pluginkit/features/screens.feature @@ -112,6 +112,19 @@ Feature: Admin menus and lazy screens from the manifest | {"label": "Reservations", "screen": "list/all", "capability": "events.manage"} | menu[0]: the screen "list/all" must be one path segment | | {"label": "Reservations", "screen": "reservations", "capability": "events.manage", "position": "first"} | json: cannot unmarshal string into Go struct field manifest.menu.0.position of type int | + Scenario Outline: A menu entry key spelled in another case or named twice is rejected + Given the plugin "events" has a backend and the screens module "@example/plugin-events/screens" + And "events" has the menu entry + When the plugins are wired + Then the wiring is rejected with: pluginwire: plugins/events/plugin.json: + And the files of the earlier wiring are left as they were + + Examples: + | entry | error | + | {"Label": "Reservations", "screen": "reservations", "capability": "events.manage"} | menu[0]: the key "Label" must be spelled "label" | + | {"label": "Reservations", "screen": "reservations", "CAPABILITY": "events.manage"} | menu[0]: the key "CAPABILITY" must be spelled "capability" | + | {"label": "Reservations", "label": "Bookings", "screen": "reservations", "capability": "events.manage"} | menu[0]: the key "label" appears twice | + Scenario Outline: A screen capability with a wrong shape is refused Given the plugin "events" has a backend and the screens module "@example/plugin-events/screens" And "events" has the screen capabilities diff --git a/pluginkit/features/steps_boot_test.go b/pluginkit/features/steps_boot_test.go index cb46645..b06a809 100644 --- a/pluginkit/features/steps_boot_test.go +++ b/pluginkit/features/steps_boot_test.go @@ -75,13 +75,13 @@ func (s *bootStore) Activate(ctx context.Context, id string) error { return s.inner.Activate(ctx, id) } -// Pause notes the write and pauses id, or answers the failure the scenario set. -func (s *bootStore) Pause(ctx context.Context, id, failure string) error { +// Pause notes the write and pauses id at step with reason, or answers the failure the scenario set. +func (s *bootStore) Pause(ctx context.Context, id string, step pluginkit.Step, reason string) error { s.writes++ if s.writeErr != nil { return s.writeErr } - return s.inner.Pause(ctx, id, failure) + return s.inner.Pause(ctx, id, step, reason) } // bootMigrations is the scenario's migration store, failing the record of the plugins the scenario names. @@ -106,6 +106,7 @@ type bootWorld struct { seeds map[string]pluginkit.PluginRecord registerFail map[string]string registerBoom map[string]string + textBoom map[string]string calledAs map[string]string migrateFails map[string]string startFails map[string]string @@ -123,6 +124,14 @@ type bootWorld struct { err error } +// panickingText is an error whose text panics with its own value, a panic fmt catches while it prints the error. +type panickingText string + +// Error panics with the error's value. +func (e panickingText) Error() string { + panic(string(e)) +} + // failure returns the error a scenario set for id in failures, or nil. func (w *bootWorld) failure(failures map[string]string, id string) error { if text, ok := failures[id]; ok { @@ -131,6 +140,14 @@ func (w *bootWorld) failure(failures map[string]string, id string) error { return nil } +// registerError returns the error a scenario set for the Register of id, or nil. +func (w *bootWorld) registerError(id string) error { + if text, ok := w.textBoom[id]; ok { + return panickingText(text) + } + return w.failure(w.registerFail, id) +} + // compile lists the plugins of list as compiled. func (w *bootWorld) compile(list string) { w.compiled = names(list) @@ -146,9 +163,9 @@ func (w *bootWorld) seed(list, state string) { } } -// pausedWith seeds the plugin id as paused with text before the boot, and checks that record after it. -func (w *bootWorld) pausedWith(id, text string) error { - want := pluginkit.PluginRecord{ID: id, State: pluginkit.PluginPaused, LastError: text} +// pausedAt seeds the plugin id as paused at step with its error text before the boot, and checks that record after. +func (w *bootWorld) pausedAt(id, step, text string) error { + want := pluginkit.PluginRecord{ID: id, State: pluginkit.PluginPaused, Step: pluginkit.Step(step), LastError: text} if !w.booted { w.seeds[id] = want return nil @@ -195,7 +212,7 @@ func (w *bootWorld) registerOf(id string) func(string) (*bootPlugin, error) { if value, ok := w.registerBoom[id]; ok { panic(value) } - if err := w.failure(w.registerFail, id); err != nil { + if err := w.registerError(id); err != nil { return nil, err } if name, ok := w.calledAs[id]; ok { @@ -205,7 +222,10 @@ func (w *bootWorld) registerOf(id string) func(string) (*bootPlugin, error) { } } -// accept pauses each registered plugin the application rejects, and answers the ones it keeps. +// rejectedRole is the application's own reason for pausing a plugin whose roles it rejects. +const rejectedRole = "it declares a role the application cannot accept" + +// accept pauses each registered plugin the application rejects at the roles step, and answers the ones it keeps. func (w *bootWorld) accept(ctx context.Context, boot *pluginkit.Boot, registered []*bootPlugin) ([]pluginkit.Plugin, error) { var kept []pluginkit.Plugin @@ -214,7 +234,11 @@ func (w *bootWorld) accept(ctx context.Context, boot *pluginkit.Boot, kept = append(kept, plugin) continue } - if err := boot.Pause(ctx, plugin.id, fmt.Errorf("%s declares a role it cannot accept", plugin.id)); err != nil { + failure := pluginkit.Failure{ + ID: plugin.id, Step: pluginkit.StepRoles, Err: fmt.Errorf("%s roles: %s", plugin.id, rejectedRole), + Reason: rejectedRole, + } + if err := boot.Pause(ctx, failure); err != nil { return nil, err } } @@ -315,7 +339,7 @@ func (w *bootWorld) holds(want pluginkit.PluginRecord) error { return nil } -// recordsClean checks that the store holds the plugin id in state with no error. +// recordsClean checks that the store holds the plugin id in state with no step and no error. func (w *bootWorld) recordsClean(id, state string) error { return w.holds(pluginkit.PluginRecord{ID: id, State: pluginkit.PluginState(state)}) } @@ -357,9 +381,11 @@ func givenBoot(sc *godog.ScenarioContext, w *bootWorld) { sc.Step(`^the compiled plugins (.+)$`, w.compile) sc.Step(`^the store holds no record$`, w.noRecord) sc.Step(`^the store records (.+) as (active|inactive|not installed)$`, w.seed) - sc.Step(`^the store records "([^"]*)" as paused with "(.*)"$`, w.pausedWith) + sc.Step(`^the store records "([^"]*)" as paused at "([^"]*)" with "(.*)"$`, w.pausedAt) sc.Step(`^the Register of "([^"]*)" fails with "([^"]*)"$`, func(id, text string) { set(w.registerFail, id, text) }) sc.Step(`^the Register of "([^"]*)" panics with "([^"]*)"$`, func(id, text string) { set(w.registerBoom, id, text) }) + sc.Step(`^the Register of "([^"]*)" fails with an error whose text panics with "([^"]*)"$`, + func(id, text string) { set(w.textBoom, id, text) }) sc.Step(`^the Register of "([^"]*)" answers a plugin that calls itself "([^"]*)"$`, func(id, name string) { set(w.calledAs, id, name) }) sc.Step(`^the migration of "([^"]*)" fails with "([^"]*)"$`, func(id, text string) { set(w.migrateFails, id, text) }) @@ -379,6 +405,7 @@ func thenBoot(sc *godog.ScenarioContext, w *bootWorld) { sc.Step(`^((?:"[^"]*"(?:, | and )?)+) started(?:, in that order)?$`, w.startedInOrder) sc.Step(`^"([^"]*)" never started$`, w.neverStarted) sc.Step(`^the store records "([^"]*)" as (active|inactive|not installed) with no error$`, w.recordsClean) + sc.Step(`^the store records "([^"]*)" as (active|inactive|not installed) with no step and no error$`, w.recordsClean) sc.Step(`^the store was not written$`, w.notWritten) sc.Step(`^the store holds no record of "([^"]*)"$`, w.noRecordOf) sc.Step(`^the Register of "([^"]*)" never ran$`, w.neverRegistered) @@ -386,15 +413,20 @@ func thenBoot(sc *godog.ScenarioContext, w *bootWorld) { sc.Step(`^the boot fails with: (.+)$`, w.failedWith) } +// newBootWorld returns the empty world of one scenario that seeds a store or boots plugins. +func newBootWorld(t *testing.T) *bootWorld { + return &bootWorld{ + t: t, seeds: map[string]pluginkit.PluginRecord{}, registerFail: map[string]string{}, + registerBoom: map[string]string{}, textBoom: map[string]string{}, migrateFails: map[string]string{}, + startFails: map[string]string{}, recordFails: map[string]string{}, rejected: map[string]bool{}, + endsOn: map[string]string{}, calledAs: map[string]string{}, + } +} + // initializeBoot gives each boot scenario a world of its own and its steps. func initializeBoot(t *testing.T) func(*godog.ScenarioContext) { return func(sc *godog.ScenarioContext) { - w := &bootWorld{ - t: t, seeds: map[string]pluginkit.PluginRecord{}, registerFail: map[string]string{}, - registerBoom: map[string]string{}, migrateFails: map[string]string{}, startFails: map[string]string{}, - recordFails: map[string]string{}, rejected: map[string]bool{}, endsOn: map[string]string{}, - calledAs: map[string]string{}, - } + w := newBootWorld(t) givenBoot(sc, w) thenBoot(sc, w) } diff --git a/pluginkit/features/steps_installed_test.go b/pluginkit/features/steps_installed_test.go new file mode 100644 index 0000000..9ec28c8 --- /dev/null +++ b/pluginkit/features/steps_installed_test.go @@ -0,0 +1,112 @@ +// SPDX-License-Identifier: Apache-2.0 + +package features_test + +import ( + "fmt" + "slices" + "testing" + + "github.com/cucumber/godog" + + "github.com/gopherium/framework/pluginkit" + "github.com/gopherium/framework/pluginkit/wire" +) + +// installedWorld is what one scenario of the installed plugins builds and finds. +type installedWorld struct { + boot *bootWorld + named map[string]string + described map[string]string + versions map[string]string + listed []pluginkit.InstalledPlugin +} + +// list joins the manifest of each compiled plugin with the store's records, as an application lists its plugins. +func (w *installedWorld) list() { + manifests := make([]wire.Manifest, 0, len(w.boot.compiled)) + for _, id := range w.boot.compiled { + manifests = append(manifests, wire.Manifest{ + ID: id, Name: w.named[id], Description: w.described[id], Version: w.versions[id], + }) + } + w.listed = pluginkit.Installed(manifests, w.boot.seeds) +} + +// row returns the row the plugin id should have in state, with the name, description and version its manifest gives. +func (w *installedWorld) row(id string, state pluginkit.PluginState) pluginkit.InstalledPlugin { + return pluginkit.InstalledPlugin{ + ID: id, Name: w.named[id], Description: w.described[id], Version: w.versions[id], State: state, + } +} + +// holds checks that the list holds exactly want as the row of its plugin. +func (w *installedWorld) holds(want pluginkit.InstalledPlugin) error { + at := slices.IndexFunc(w.listed, func(plugin pluginkit.InstalledPlugin) bool { return plugin.ID == want.ID }) + if at < 0 { + return fmt.Errorf("the list holds %+v, want a row of %s", w.listed, want.ID) + } + if got := w.listed[at]; got != want { + return fmt.Errorf("the list holds %+v, want %+v", got, want) + } + return nil +} + +// holdsAs checks the row of the plugin id in state, with its manifest's words and no step or reason. +func (w *installedWorld) holdsAs(id, state string) error { + return w.holds(w.row(id, pluginkit.PluginState(state))) +} + +// holdsBare checks the row of the plugin id in state, with its manifest's name and no description or version. +func (w *installedWorld) holdsBare(id, state string) error { + return w.holds(pluginkit.InstalledPlugin{ID: id, Name: w.named[id], State: pluginkit.PluginState(state)}) +} + +// holdsPaused checks the row of the plugin id as paused at step, with its own error reading reason. +func (w *installedWorld) holdsPaused(id, step, reason string) error { + want := w.row(id, pluginkit.PluginPaused) + want.PausedStep, want.PausedReason = pluginkit.Step(step), reason + return w.holds(want) +} + +// namesInOrder checks that the list holds exactly the plugins of list, in order. +func (w *installedWorld) namesInOrder(list string) error { + ids := make([]string, 0, len(w.listed)) + for _, plugin := range w.listed { + ids = append(ids, plugin.ID) + } + if want := names(list); !slices.Equal(ids, want) { + return fmt.Errorf("the list names %q, want %q", ids, want) + } + return nil +} + +// leavesOut checks that the list holds no row of the plugin id. +func (w *installedWorld) leavesOut(id string) error { + if slices.ContainsFunc(w.listed, func(plugin pluginkit.InstalledPlugin) bool { return plugin.ID == id }) { + return fmt.Errorf("the list holds %+v, want no row of %s", w.listed, id) + } + return nil +} + +// initializeInstalled gives each installed plugins scenario a world of its own, the boot's Given steps and its own. +func initializeInstalled(t *testing.T) func(*godog.ScenarioContext) { + return func(sc *godog.ScenarioContext) { + w := &installedWorld{ + boot: newBootWorld(t), named: map[string]string{}, described: map[string]string{}, + versions: map[string]string{}, + } + givenBoot(sc, w.boot) + sc.Step(`^the manifest of "([^"]*)" names it "([^"]*)"$`, func(id, name string) { set(w.named, id, name) }) + sc.Step(`^the manifest of "([^"]*)" describes it as "([^"]*)"$`, + func(id, text string) { set(w.described, id, text) }) + sc.Step(`^the manifest of "([^"]*)" gives the version "([^"]*)"$`, + func(id, version string) { set(w.versions, id, version) }) + sc.Step(`^the application lists the installed plugins$`, w.list) + sc.Step(`^the list holds "([^"]*)" as "(active|inactive)"$`, w.holdsAs) + sc.Step(`^the list holds "([^"]*)" as "(active|inactive)" with no description and no version$`, w.holdsBare) + sc.Step(`^the list holds "([^"]*)" as paused at "([^"]*)", its reason reading "(.*)"$`, w.holdsPaused) + sc.Step(`^the list names ((?:"[^"]*"(?:, | and )?)+), in that order$`, w.namesInOrder) + sc.Step(`^the list leaves out "([^"]*)"$`, w.leavesOut) + } +} diff --git a/pluginkit/features/steps_screens_test.go b/pluginkit/features/steps_screens_test.go index 3a900f3..9f2a937 100644 --- a/pluginkit/features/steps_screens_test.go +++ b/pluginkit/features/steps_screens_test.go @@ -360,8 +360,13 @@ func (w *screensWorld) writesOnlyWiring() error { // refusedWith checks that the run failed with the text, the scenario's root left out of its paths. func (w *screensWorld) refusedWith(text string) error { + return w.rejectedWith(text) +} + +// rejectedWith checks that the run failed with the text, the scenario's root left out of its paths. +func (w *screensWorld) rejectedWith(text string) error { if w.err == nil { - return errors.New("the run succeeded, want it refused") + return errors.New("the run succeeded, want it rejected") } if got := strings.ReplaceAll(w.err.Error(), w.root+string(filepath.Separator), ""); got != text { return fmt.Errorf("the run failed with %q, want %q", got, text) @@ -453,6 +458,7 @@ func thenScreens(sc *godog.ScenarioContext, w *screensWorld) { sc.Step(`^the frontend wiring imports "([^"]*)" and "([^"]*)"$`, w.importsFrontends) sc.Step(`^the generator writes only the Go and the TypeScript wiring$`, w.writesOnlyWiring) sc.Step(`^the wiring is refused with: (.+)$`, w.refusedWith) + sc.Step(`^the wiring is rejected with: (.+)$`, w.rejectedWith) sc.Step(`^the files of the earlier wiring are left as they were$`, w.earlierWiringKept) sc.Step(`^the package\.json depends only on "([^"]*)" as a workspace package$`, w.dependsOnlyOn) sc.Step(`^the manifest index holds this entry for "([^"]*)":$`, w.indexHolds) diff --git a/pluginkit/host.go b/pluginkit/host.go index 541d481..011f787 100644 --- a/pluginkit/host.go +++ b/pluginkit/host.go @@ -228,16 +228,44 @@ func safeCall(ctx context.Context, id, operation string, fn func(context.Context func guarded(ctx context.Context, name string, fn func(context.Context) error) (err error) { defer func() { if recovered := recover(); recovered != nil { - err = panicError("pluginkit: " + name + " panicked: " + describe(recovered)) + err = guardedPanic{name: name, value: describe(recovered)} } }() if err := fn(ctx); err != nil { - return fmt.Errorf("pluginkit: %s: %w", name, err) + return &guardedError{name: name, text: fmt.Sprint(err), err: err} } return nil } -// panicError is a panic [guarded] recovered, holding the text that names where it came from. +// guardedError is an error [guarded] wrapped, keeping its text, read once inside the recover, apart from the name. +type guardedError struct { + name string + text string + err error +} + +// Error returns the text of the error with the name in front, as a log line prints it. +func (e *guardedError) Error() string { + return "pluginkit: " + e.name + ": " + e.text +} + +// Unwrap returns the error fn returned. +func (e *guardedError) Unwrap() error { + return e.err +} + +// guardedPanic is a panic [guarded] recovered, keeping the name it puts in front apart from the panic's value. +type guardedPanic struct { + name string + value string +} + +// Error returns the text of the panic with the name in front, as a log line prints it. +func (e guardedPanic) Error() string { + return "pluginkit: " + e.name + " panicked: " + e.value +} + +// panicError is a panic a hook or a route recovered, holding the text that names where it came from. type panicError string // Error returns the text of the panic. diff --git a/pluginkit/host_test.go b/pluginkit/host_test.go index edfd999..9cc62dd 100644 --- a/pluginkit/host_test.go +++ b/pluginkit/host_test.go @@ -510,6 +510,20 @@ func TestHostRecoversStartPanic(t *testing.T) { } } +func TestHostKeepsTheTextOfEachPanicItRecovers(t *testing.T) { + t.Parallel() + + var calls []string + host := pluginkit.NewHost( + &fakePlugin{id: "alpha", stopPanic: true, calls: &calls}, + &fakePlugin{id: "beta", startPanic: true, calls: &calls}, + ) + + err := host.Start(t.Context(), stopGrace) + + assertErrorText(t, err, "pluginkit: beta start panicked: boom\npluginkit: alpha stop panicked: boom") +} + func TestHostStopCollectsAllFailures(t *testing.T) { t.Parallel() diff --git a/pluginkit/installed.go b/pluginkit/installed.go new file mode 100644 index 0000000..0babe3a --- /dev/null +++ b/pluginkit/installed.go @@ -0,0 +1,55 @@ +// SPDX-License-Identifier: Apache-2.0 + +package pluginkit + +import ( + "cmp" + "slices" + "strings" + + "github.com/gopherium/framework/pluginkit/wire" +) + +// InstalledPlugin is one compiled plugin a Plugins screen lists, with its state and why it paused. +type InstalledPlugin struct { + ID string `json:"id"` + Name string `json:"name"` + Description string `json:"description"` + Version string `json:"version"` + State PluginState `json:"status"` + PausedStep Step `json:"paused_step"` + PausedReason string `json:"paused_reason"` +} + +// Installed lists each manifest the records hold as installed, by name then id, one with no record as active. +func Installed(manifests []wire.Manifest, records map[string]PluginRecord) []InstalledPlugin { + listed := make([]InstalledPlugin, 0, len(manifests)) + for _, manifest := range manifests { + record, known := records[manifest.ID] + if !known { + record = PluginRecord{ID: manifest.ID, State: PluginActive} + } + if record.State != PluginNotInstalled { + listed = append(listed, installedFrom(manifest, record)) + } + } + slices.SortFunc(listed, byName) + return listed +} + +// byName orders two rows by name without regard to case, then by id. +func byName(a, b InstalledPlugin) int { + return cmp.Or(cmp.Compare(strings.ToLower(a.Name), strings.ToLower(b.Name)), cmp.Compare(a.ID, b.ID)) +} + +// installedFrom returns the row of manifest in the state record holds, with a step and a reason only when paused. +func installedFrom(manifest wire.Manifest, record PluginRecord) InstalledPlugin { + plugin := InstalledPlugin{ + ID: manifest.ID, Name: manifest.Name, Description: manifest.Description, Version: manifest.Version, + State: record.State, + } + if record.State == PluginPaused { + plugin.PausedStep, plugin.PausedReason = record.Step, record.LastError + } + return plugin +} diff --git a/pluginkit/installed_test.go b/pluginkit/installed_test.go new file mode 100644 index 0000000..12656d7 --- /dev/null +++ b/pluginkit/installed_test.go @@ -0,0 +1,185 @@ +// SPDX-License-Identifier: Apache-2.0 + +package pluginkit_test + +import ( + "encoding/json" + "testing" + + "github.com/gopherium/framework/pluginkit" + "github.com/gopherium/framework/pluginkit/wire" +) + +// feedDescription is the description the feed's manifest gives. +const feedDescription = "Serves the published posts as an RSS feed." + +// manifestOf returns the manifest of the plugin id named name, with no description or version. +func manifestOf(id, name string) wire.Manifest { + return wire.Manifest{ID: id, Name: name} +} + +// feedManifest returns the manifest of the feed, with its description and its version. +func feedManifest() wire.Manifest { + return wire.Manifest{ID: "feed", Name: "Feed", Description: feedDescription, Version: "0.0.1"} +} + +// feedRow returns the row of the feed in state, with no step and no reason. +func feedRow(state pluginkit.PluginState) pluginkit.InstalledPlugin { + return pluginkit.InstalledPlugin{ + ID: "feed", Name: "Feed", Description: feedDescription, Version: "0.0.1", State: state, + } +} + +// idsOf returns the id of each listed plugin, in its order. +func idsOf(listed []pluginkit.InstalledPlugin) []string { + ids := make([]string, 0, len(listed)) + for _, plugin := range listed { + ids = append(ids, plugin.ID) + } + return ids +} + +// recordsOf returns records keyed by plugin id. +func recordsOf(records ...pluginkit.PluginRecord) map[string]pluginkit.PluginRecord { + byID := make(map[string]pluginkit.PluginRecord, len(records)) + for _, record := range records { + byID[record.ID] = record + } + return byID +} + +func TestInstalledListsAPluginWithTheNameDescriptionAndVersionOfItsManifest(t *testing.T) { + t.Parallel() + + for _, state := range []pluginkit.PluginState{pluginkit.PluginActive, pluginkit.PluginInactive} { + t.Run(string(state), func(t *testing.T) { + t.Parallel() + + got := pluginkit.Installed([]wire.Manifest{feedManifest()}, recordsOf(record("feed", state))) + + wantEqual(t, "listed", got, []pluginkit.InstalledPlugin{feedRow(state)}) + }) + } +} + +func TestInstalledGivesAPausedPluginItsStepAndItsOwnError(t *testing.T) { + t.Parallel() + + records := recordsOf(pluginkit.PluginRecord{ + ID: "feed", State: pluginkit.PluginPaused, Step: pluginkit.StepRegister, LastError: "the title is too long", + }) + + got := pluginkit.Installed([]wire.Manifest{feedManifest()}, records) + + want := feedRow(pluginkit.PluginPaused) + want.PausedStep, want.PausedReason = pluginkit.StepRegister, "the title is too long" + wantEqual(t, "listed", got, []pluginkit.InstalledPlugin{want}) +} + +func TestInstalledGivesAStepAndAReasonOnlyToAPausedPlugin(t *testing.T) { + t.Parallel() + + for _, state := range []pluginkit.PluginState{pluginkit.PluginActive, pluginkit.PluginInactive} { + t.Run(string(state), func(t *testing.T) { + t.Parallel() + + records := recordsOf(pluginkit.PluginRecord{ + ID: "feed", State: state, Step: pluginkit.StepStart, LastError: "no route table", + }) + + got := pluginkit.Installed([]wire.Manifest{feedManifest()}, records) + + wantEqual(t, "listed", got, []pluginkit.InstalledPlugin{feedRow(state)}) + }) + } +} + +func TestInstalledLeavesOutAPluginTheRecordsHoldAsNotInstalled(t *testing.T) { + t.Parallel() + + manifests := []wire.Manifest{manifestOf("events", "Events"), feedManifest()} + records := recordsOf(record("events", pluginkit.PluginActive), record("feed", pluginkit.PluginNotInstalled)) + + got := pluginkit.Installed(manifests, records) + + wantEqual(t, "listed", got, []pluginkit.InstalledPlugin{ + {ID: "events", Name: "Events", State: pluginkit.PluginActive}, + }) +} + +func TestInstalledLeavesOutARecordWithNoManifest(t *testing.T) { + t.Parallel() + + records := recordsOf(record("feed", pluginkit.PluginActive), record("gallery", pluginkit.PluginPaused)) + + got := pluginkit.Installed([]wire.Manifest{feedManifest()}, records) + + wantEqual(t, "listed", got, []pluginkit.InstalledPlugin{feedRow(pluginkit.PluginActive)}) +} + +func TestInstalledListsAManifestWithNoRecordAsActive(t *testing.T) { + t.Parallel() + + for name, records := range map[string]map[string]pluginkit.PluginRecord{ + "no records at all": nil, + "records of others only": recordsOf(record("events", pluginkit.PluginInactive)), + } { + t.Run(name, func(t *testing.T) { + t.Parallel() + + got := pluginkit.Installed([]wire.Manifest{feedManifest()}, records) + + wantEqual(t, "listed", got, []pluginkit.InstalledPlugin{feedRow(pluginkit.PluginActive)}) + }) + } +} + +func TestInstalledListsByNameThenByID(t *testing.T) { + t.Parallel() + + manifests := []wire.Manifest{ + manifestOf("events", "Calendar"), manifestOf("gallery", "Calendar"), manifestOf("feed", "Atom"), + manifestOf("archive", "Calendar"), + } + + got := pluginkit.Installed(manifests, nil) + + wantEqual(t, "ids", idsOf(got), []string{"feed", "archive", "events", "gallery"}) +} + +func TestInstalledComparesNamesWithoutRegardToCase(t *testing.T) { + t.Parallel() + + manifests := []wire.Manifest{ + manifestOf("zines", "Zines"), manifestOf("upper", "Atom"), manifestOf("lower", "atom"), + manifestOf("bold", "BOLD"), + } + + got := pluginkit.Installed(manifests, nil) + + wantEqual(t, "ids", idsOf(got), []string{"lower", "upper", "bold", "zines"}) +} + +func TestInstalledAnswersAnEmptyListThatEncodesAsOne(t *testing.T) { + t.Parallel() + + got := pluginkit.Installed(nil, recordsOf(record("feed", pluginkit.PluginActive))) + + data, err := json.Marshal(got) + + assertErrorFree(t, err) + wantEqual(t, "JSON", string(data), "[]") +} + +func TestInstalledPluginEncodesUnderTheNamesAScreenReads(t *testing.T) { + t.Parallel() + + row := feedRow(pluginkit.PluginPaused) + row.PausedStep, row.PausedReason = pluginkit.StepStart, "no route table" + + data, err := json.Marshal(row) + + assertErrorFree(t, err) + wantEqual(t, "JSON", string(data), `{"id":"feed","name":"Feed","description":"`+feedDescription+ + `","version":"0.0.1","status":"paused","paused_step":"start","paused_reason":"no route table"}`) +} diff --git a/pluginkit/pluginstore.go b/pluginkit/pluginstore.go index 17d500d..dd6867f 100644 --- a/pluginkit/pluginstore.go +++ b/pluginkit/pluginstore.go @@ -22,7 +22,9 @@ const ( type PluginRecord struct { ID string State PluginState - // LastError is the text of the failure that paused the plugin, and empty otherwise. + // Step is the step a paused plugin failed at, and empty otherwise. + Step Step + // LastError is the plugin's own error when paused, with no plugin id or step in front, and empty otherwise. LastError string } @@ -30,8 +32,8 @@ type PluginRecord struct { type PluginStore interface { // Records returns every record, keyed by plugin id, in one read. Records(ctx context.Context) (map[string]PluginRecord, error) - // Activate marks the plugin id active and clears its error, adding its record when it has none. + // Activate marks the plugin id active and clears its step and its error, adding its record when it has none. Activate(ctx context.Context, id string) error - // Pause marks the plugin id paused with the text of its failure, adding its record when it has none. - Pause(ctx context.Context, id, failure string) error + // Pause marks the plugin id paused at step, kept as written, with reason, adding its record when it has none. + Pause(ctx context.Context, id string, step Step, reason string) error } diff --git a/pluginkit/pluginstoretest/pluginstoretest.go b/pluginkit/pluginstoretest/pluginstoretest.go index f9f1379..cf176c0 100644 --- a/pluginkit/pluginstoretest/pluginstoretest.go +++ b/pluginkit/pluginstoretest/pluginstoretest.go @@ -32,42 +32,56 @@ func cases() map[string]func(t *testing.T, store pluginkit.PluginStore) { act(t, store.Activate(t.Context(), "events")) want(t, store, map[string]pluginkit.PluginRecord{"events": active("events")}) }, - "pausing a plugin it never saw records it paused": func(t *testing.T, store pluginkit.PluginStore) { - act(t, store.Pause(t.Context(), "events", "a setting is missing")) - want(t, store, map[string]pluginkit.PluginRecord{"events": paused("events", "a setting is missing")}) + "pausing a plugin it never saw records its step and its error": func(t *testing.T, store pluginkit.PluginStore) { + act(t, store.Pause(t.Context(), "events", pluginkit.StepRegister, "a setting is missing")) + want(t, store, map[string]pluginkit.PluginRecord{ + "events": paused(pluginkit.Failure{ID: "events", Step: pluginkit.StepRegister, Reason: "a setting is missing"}), + }) }, "pausing an active plugin keeps its failure": func(t *testing.T, store pluginkit.PluginStore) { act(t, store.Activate(t.Context(), "events")) - act(t, store.Pause(t.Context(), "events", "a setting is missing")) - want(t, store, map[string]pluginkit.PluginRecord{"events": paused("events", "a setting is missing")}) + act(t, store.Pause(t.Context(), "events", pluginkit.StepRegister, "a setting is missing")) + want(t, store, map[string]pluginkit.PluginRecord{ + "events": paused(pluginkit.Failure{ID: "events", Step: pluginkit.StepRegister, Reason: "a setting is missing"}), + }) }, - "pausing a paused plugin keeps the newer failure": func(t *testing.T, store pluginkit.PluginStore) { - act(t, store.Pause(t.Context(), "events", "a setting is missing")) - act(t, store.Pause(t.Context(), "events", "no route table")) - want(t, store, map[string]pluginkit.PluginRecord{"events": paused("events", "no route table")}) + "pausing a paused plugin keeps the newer step and the newer error": func(t *testing.T, store pluginkit.PluginStore) { + act(t, store.Pause(t.Context(), "events", pluginkit.StepRegister, "a setting is missing")) + act(t, store.Pause(t.Context(), "events", pluginkit.StepStart, "no route table")) + want(t, store, map[string]pluginkit.PluginRecord{ + "events": paused(pluginkit.Failure{ID: "events", Step: pluginkit.StepStart, Reason: "no route table"}), + }) }, - "activating a paused plugin clears its failure": func(t *testing.T, store pluginkit.PluginStore) { - act(t, store.Pause(t.Context(), "events", "a setting is missing")) + "activating a paused plugin clears its step and its error": func(t *testing.T, store pluginkit.PluginStore) { + act(t, store.Pause(t.Context(), "events", pluginkit.StepRegister, "a setting is missing")) act(t, store.Activate(t.Context(), "events")) want(t, store, map[string]pluginkit.PluginRecord{"events": active("events")}) }, + "a step word the store never saw is kept as written": func(t *testing.T, store pluginkit.PluginStore) { + act(t, store.Pause(t.Context(), "events", pluginkit.Step("crash"), "the site stopped answering")) + want(t, store, map[string]pluginkit.PluginRecord{ + "events": paused(pluginkit.Failure{ID: "events", Step: "crash", Reason: "the site stopped answering"}), + }) + }, "activating an active plugin keeps it active": func(t *testing.T, store pluginkit.PluginStore) { act(t, store.Activate(t.Context(), "events")) act(t, store.Activate(t.Context(), "events")) want(t, store, map[string]pluginkit.PluginRecord{"events": active("events")}) }, "activating a plugin keeps every other record": func(t *testing.T, store pluginkit.PluginStore) { - act(t, store.Pause(t.Context(), "feed", "no route table")) + act(t, store.Pause(t.Context(), "feed", pluginkit.StepStart, "no route table")) act(t, store.Activate(t.Context(), "events")) want(t, store, map[string]pluginkit.PluginRecord{ - "events": active("events"), "feed": paused("feed", "no route table"), + "events": active("events"), + "feed": paused(pluginkit.Failure{ID: "feed", Step: pluginkit.StepStart, Reason: "no route table"}), }) }, "one read answers every plugin by its id": func(t *testing.T, store pluginkit.PluginStore) { act(t, store.Activate(t.Context(), "events")) - act(t, store.Pause(t.Context(), "feed", "no route table")) + act(t, store.Pause(t.Context(), "feed", pluginkit.StepStart, "no route table")) want(t, store, map[string]pluginkit.PluginRecord{ - "events": active("events"), "feed": paused("feed", "no route table"), + "events": active("events"), + "feed": paused(pluginkit.Failure{ID: "feed", Step: pluginkit.StepStart, Reason: "no route table"}), }) }, } @@ -78,9 +92,11 @@ func active(id string) pluginkit.PluginRecord { return pluginkit.PluginRecord{ID: id, State: pluginkit.PluginActive} } -// paused returns the record of the plugin id paused for failure. -func paused(id, failure string) pluginkit.PluginRecord { - return pluginkit.PluginRecord{ID: id, State: pluginkit.PluginPaused, LastError: failure} +// paused returns the record of the plugin the failure names, paused at its step with its reason as the error. +func paused(failure pluginkit.Failure) pluginkit.PluginRecord { + return pluginkit.PluginRecord{ + ID: failure.ID, State: pluginkit.PluginPaused, Step: failure.Step, LastError: failure.Reason, + } } // act stops t when the store refused a write. @@ -126,7 +142,7 @@ func (m *Memory) Records(context.Context) (map[string]pluginkit.PluginRecord, er return maps.Clone(m.records), nil } -// Activate marks the plugin id active and clears its error. +// Activate marks the plugin id active and clears its step and its error. func (m *Memory) Activate(_ context.Context, id string) error { m.mu.Lock() defer m.mu.Unlock() @@ -134,10 +150,10 @@ func (m *Memory) Activate(_ context.Context, id string) error { return nil } -// Pause marks the plugin id paused with the text of its failure. -func (m *Memory) Pause(_ context.Context, id, failure string) error { +// Pause marks the plugin id paused at step with reason, keeping the step beside the error. +func (m *Memory) Pause(_ context.Context, id string, step pluginkit.Step, reason string) error { m.mu.Lock() defer m.mu.Unlock() - m.records[id] = paused(id, failure) + m.records[id] = paused(pluginkit.Failure{ID: id, Step: step, Reason: reason}) return nil } diff --git a/pluginkit/registration_test.go b/pluginkit/registration_test.go index 4f610aa..8c1fc59 100644 --- a/pluginkit/registration_test.go +++ b/pluginkit/registration_test.go @@ -146,6 +146,26 @@ func TestRegisterEachGoesOnPastAFailingRegisterAndNamesIt(t *testing.T) { } } +func TestRegisterEachGoesOnPastAnErrorWhoseTextPanics(t *testing.T) { + t.Parallel() + + var calls []string + entries := []pluginkit.Registration[listedDeps, *listedPlugin]{ + entry("events", &calls, succeeds), entry("feed", &calls, answers(panickingText("title text exploded"))), + entry("gallery", &calls, succeeds), + } + + outcome := pluginkit.RegisterEach(entries, depsOf(&calls)) + + wantEqual(t, "registered", registeredIDs(outcome), []string{"events", "gallery"}) + wantEqual(t, "failed", failures(outcome), []failureWant{ + {"feed", pluginkit.StepRegister, false, "pluginkit: feed register: %!v(PANIC=Error method: title text exploded)"}, + }) + wantEqual(t, "reasons", reasons(outcome.Failed), []string{ + "feed register: %!v(PANIC=Error method: title text exploded)", + }) +} + func TestRegisterEachFailsAPluginWhoseIDIsNotItsEntrys(t *testing.T) { t.Parallel() diff --git a/pluginkit/routes_test.go b/pluginkit/routes_test.go index e329414..1b7e6e0 100644 --- a/pluginkit/routes_test.go +++ b/pluginkit/routes_test.go @@ -69,21 +69,28 @@ func TestRoutesEachFailsAPluginWhoseRoutesFailToLoad(t *testing.T) { const panicked = "pluginkit: feed routes panicked: boom" const noHandler = "pluginkit: feed routes: Routes answered no handler" + const noHandlerReason = "Routes answered no handler" mux := http.NewServeMux() tests := map[string]struct { plugin pluginkit.Plugin want string panicked bool + reason string }{ - "Routes panics": {plugin: &panickyRoutesPlugin{fakePlugin{id: "feed"}}, want: panicked, panicked: true}, + "Routes panics": { + plugin: &panickyRoutesPlugin{fakePlugin{id: "feed"}}, want: panicked, panicked: true, reason: "panicked: boom", + }, "PublicPaths panics": { plugin: &servingPlugin{routedPlugin: *routed("feed", mux), paths: func() []string { panic("boom") }}, want: panicked, panicked: true, + reason: "panicked: boom", + }, + "Routes answers nil": {plugin: routed("feed", nil), want: noHandler, reason: noHandlerReason}, + "Routes answers a nil mux": {plugin: routed("feed", (*http.ServeMux)(nil)), want: noHandler, reason: noHandlerReason}, + "Routes answers a nil handler": { + plugin: routed("feed", http.HandlerFunc(nil)), want: noHandler, reason: noHandlerReason, }, - "Routes answers nil": {plugin: routed("feed", nil), want: noHandler}, - "Routes answers a nil mux": {plugin: routed("feed", (*http.ServeMux)(nil)), want: noHandler}, - "Routes answers a nil handler": {plugin: routed("feed", http.HandlerFunc(nil)), want: noHandler}, } for name, test := range tests { @@ -99,7 +106,9 @@ func TestRoutesEachFailsAPluginWhoseRoutesFailToLoad(t *testing.T) { t.Errorf("PublicPaths = %v, want none", outcome.PublicPaths) } shapes, texts := splitFailures(outcome.Failed) - want := []pluginkit.Failure{{ID: "feed", Step: pluginkit.StepRoutes, Panicked: test.panicked}} + want := []pluginkit.Failure{ + {ID: "feed", Step: pluginkit.StepRoutes, Panicked: test.panicked, Reason: test.reason}, + } if !slices.Equal(shapes, want) { t.Errorf("Failed = %+v, want %+v", outcome.Failed, want) } diff --git a/pluginkit/start_each.go b/pluginkit/start_each.go index 01c65bd..ec3c499 100644 --- a/pluginkit/start_each.go +++ b/pluginkit/start_each.go @@ -21,6 +21,8 @@ const ( StepRegister Step = "register" // StepRoutes is a plugin's Routes and PublicPaths, read by [RoutesEach]. StepRoutes Step = "routes" + // StepRoles is the application's declaration of a plugin's roles, named here so every application uses one word. + StepRoles Step = "roles" ) // Failure is one step one plugin failed, or was still waiting for when the context ended. @@ -29,7 +31,10 @@ type Failure struct { Step Step // Panicked is true only for a panic this step recovered, never for an error that merely holds one. Panicked bool - Err error + // Err is the whole error, the plugin id and the step in front, as a log line prints it. + Err error + // Reason is the plugin's own error with nothing in front, which a pause records beside the step. + Reason string } // StartedPlugin is one plugin whose Start returned nil, and how long that Start took. @@ -90,8 +95,14 @@ func (o *StartOutcome) startAfter(ctx context.Context, p Plugin, migration Failu o.Started = append(o.Started, StartedPlugin{ID: p.ID(), Took: time.Since(began)}) } -// failureOf returns the failure of the plugin id at step, marked as panicked only when err is that step's own panic. +// failureOf returns the failure of the plugin id at step, its reason the text [guarded] read, calling no plugin code. func failureOf(id string, step Step, err error) Failure { - _, panicked := err.(panicError) - return Failure{ID: id, Step: step, Panicked: panicked, Err: err} + failure := Failure{ID: id, Step: step, Err: err} + switch guardedErr := err.(type) { + case guardedPanic: + failure.Panicked, failure.Reason = true, "panicked: "+guardedErr.value + case *guardedError: + failure.Reason = guardedErr.text + } + return failure } diff --git a/pluginkit/start_each_test.go b/pluginkit/start_each_test.go index b24f569..b1bf51c 100644 --- a/pluginkit/start_each_test.go +++ b/pluginkit/start_each_test.go @@ -6,6 +6,7 @@ import ( "context" "errors" "slices" + "strconv" "testing" "testing/synctest" "time" @@ -204,6 +205,131 @@ func TestStartEachKeepsEachCauseInItsFailure(t *testing.T) { } } +// reasons returns the id, the step and the reason of each failure, in order. +func reasons(failures []pluginkit.Failure) []string { + got := make([]string, 0, len(failures)) + for _, failure := range failures { + got = append(got, failure.ID+" "+string(failure.Step)+": "+failure.Reason) + } + return got +} + +func TestStartEachKeepsEachPluginsOwnErrorAsItsReason(t *testing.T) { + t.Parallel() + + var discarded []string + errNested := pluginkit.NewHost(&fakePlugin{id: "inner", startPanic: true, calls: &discarded}). + Start(t.Context(), stopGrace) + var calls []string + schema := migrating("alpha", &calls) + schema.migrateErr = errors.New("schema exploded") + panicking := migrating("beta", &calls) + panicking.migratePanic = true + host := pluginkit.NewHost(schema, panicking, + &fakePlugin{id: "gamma", startErr: errors.New("boot failed"), calls: &calls}, + &fakePlugin{id: "delta", startPanic: true, calls: &calls}, + &fakePlugin{id: "epsilon", startErr: errNested, calls: &calls}, + &fakePlugin{id: "zeta", startErr: selfPanicking{}, calls: &calls}, + ) + + outcome := startEach(t.Context(), t, host) + + wantEqual(t, "reasons", reasons(outcome.Failed), []string{ + "alpha migrate: schema exploded", + "beta migrate: panicked: boom", + "gamma start: boot failed", + "delta start: panicked: boom", + "epsilon start: pluginkit: inner start panicked: boom", + "zeta start: panicked: pluginkit_test.selfPanicking whose text panicked", + }) +} + +func TestStartEachKeepsTheReasonOfAStepAMigrationStoreRuns(t *testing.T) { + t.Parallel() + + var calls []string + store := &memoryStore{versions: map[string]string{}, recordErr: errStoreOffline, calls: &calls} + unversioned := versioned("beta", "", &calls) + host := storeHost(t, store, nil, versioned("alpha", "1", &calls), unversioned) + + outcome := startEach(t.Context(), t, host) + + wantEqual(t, "reasons", reasons(outcome.Failed), []string{ + "alpha record: store offline", + "beta migrate: the version is empty", + }) +} + +func TestStartEachGivesTheEndedContextAsTheReason(t *testing.T) { + t.Parallel() + + var calls []string + ctx, cancel := context.WithCancel(t.Context()) + cancel() + + outcome := startEach(ctx, t, pluginkit.NewHost(migrating("alpha", &calls))) + + wantEqual(t, "reasons", reasons(outcome.Failed), []string{"alpha migrate: context canceled"}) +} + +// panickingText is an error whose text panics with its own value, a panic fmt catches while it prints the error. +type panickingText string + +// Error panics with the error's value. +func (e panickingText) Error() string { + panic(string(e)) +} + +func TestStartEachGoesOnPastAnErrorWhoseTextPanics(t *testing.T) { + t.Parallel() + + var calls []string + schema := migrating("alpha", &calls) + schema.migrateErr = panickingText("schema text exploded") + host := pluginkit.NewHost(schema, migrating("beta", &calls), + &fakePlugin{id: "gamma", startErr: panickingText("boot text exploded"), calls: &calls}, plain("delta", &calls)) + + outcome := startEach(t.Context(), t, host) + + wantOutcome(t, outcome, []string{"beta", "delta"}, []failureWant{ + {"alpha", pluginkit.StepMigrate, false, "pluginkit: alpha migrate: %!v(PANIC=Error method: schema text exploded)"}, + {"gamma", pluginkit.StepStart, false, "pluginkit: gamma start: %!v(PANIC=Error method: boot text exploded)"}, + }) + wantCalls(t, calls, []string{"alpha migrate", "beta migrate", "beta start", "gamma start", "delta start"}) + wantEqual(t, "reasons", reasons(outcome.Failed), []string{ + "alpha migrate: %!v(PANIC=Error method: schema text exploded)", + "gamma start: %!v(PANIC=Error method: boot text exploded)", + }) + var cause panickingText + if !errors.As(outcome.Failed[1].Err, &cause) || cause != "boot text exploded" { + t.Errorf("gamma's error = %#v, want the error its Start answered in its chain", outcome.Failed[1].Err) + } +} + +// changingText is an error whose text counts the times it was read. +type changingText struct { + reads int +} + +// Error returns the text of this read. +func (e *changingText) Error() string { + e.reads++ + return "read " + strconv.Itoa(e.reads) +} + +func TestStartEachReadsTheTextOfAPluginsErrorOnce(t *testing.T) { + t.Parallel() + + var calls []string + text := &changingText{} + + outcome := startEach(t.Context(), t, pluginkit.NewHost(&fakePlugin{id: "alpha", startErr: text, calls: &calls})) + + wantOutcome(t, outcome, nil, []failureWant{{"alpha", pluginkit.StepStart, false, "pluginkit: alpha start: read 1"}}) + wantEqual(t, "reasons", reasons(outcome.Failed), []string{"alpha start: read 1"}) + wantEqual(t, "reads", text.reads, 1) +} + func TestStartEachWithAMigrationStore(t *testing.T) { t.Parallel() diff --git a/pluginkit/wire/manifest.go b/pluginkit/wire/manifest.go index c7841a0..5564523 100644 --- a/pluginkit/wire/manifest.go +++ b/pluginkit/wire/manifest.go @@ -21,18 +21,19 @@ type Manifest struct { Backend string `json:"backend,omitempty"` Frontend string `json:"frontend,omitempty"` - Version string `json:"version,omitempty"` - License string `json:"license,omitempty"` - DID string `json:"did,omitempty"` - Requires map[string]string `json:"requires,omitempty"` - Tested string `json:"tested,omitempty"` - Engines []string `json:"engines,omitempty"` - Uninstall bool `json:"uninstall,omitempty"` - Hooks []string `json:"hooks,omitempty"` - Defines []Define `json:"defines,omitempty"` - Jobs []Job `json:"jobs,omitempty"` - Settings []Setting `json:"settings,omitempty"` - Menu []MenuEntry `json:"menu,omitempty"` + Description string `json:"description,omitempty"` + Version string `json:"version,omitempty"` + License string `json:"license,omitempty"` + DID string `json:"did,omitempty"` + Requires map[string]string `json:"requires,omitempty"` + Tested string `json:"tested,omitempty"` + Engines []string `json:"engines,omitempty"` + Uninstall bool `json:"uninstall,omitempty"` + Hooks []string `json:"hooks,omitempty"` + Defines []Define `json:"defines,omitempty"` + Jobs []Job `json:"jobs,omitempty"` + Settings []Setting `json:"settings,omitempty"` + Menu []MenuEntry `json:"menu,omitempty"` // Screens is the address of the module the admin imports only when one of the plugin's screens opens. Screens string `json:"screens,omitempty"` // ScreenCapabilities maps each screen no menu entry names to the capability it needs. @@ -55,7 +56,7 @@ func (m Manifest) MarshalJSON() ([]byte, error) { return slices.Concat(typed[:len(typed)-len("}\n")], []byte(","), extra[1:]), nil } -// UnmarshalJSON reads m from a plugin.json or an entry of the manifest index, checking only the JSON types. +// UnmarshalJSON reads m from a plugin.json or an entry of the manifest index, checking only keys, text and JSON types. func (m *Manifest) UnmarshalJSON(data []byte) error { parsed, err := parseManifest(data) *m = Manifest(parsed) @@ -119,17 +120,20 @@ type manifest Manifest // typedKeys are the manifest keys Manifest has a field for. var typedKeys = []string{ - "id", "name", "backend", "frontend", "version", "license", "did", "requires", "tested", "engines", "uninstall", - "hooks", "defines", "jobs", "settings", "menu", "screens", "screen_capabilities", + "id", "name", "backend", "frontend", "description", "version", "license", "did", "requires", "tested", "engines", + "uninstall", "hooks", "defines", "jobs", "settings", "menu", "screens", "screen_capabilities", } -// isTypedKey reports whether encoding/json reads key into a field of Manifest. +// isTypedKey reports whether key is the json name of a field of Manifest. func isTypedKey(key string, _ json.RawMessage) bool { - return slices.ContainsFunc(typedKeys, func(typed string) bool { return strings.EqualFold(key, typed) }) + return slices.Contains(typedKeys, key) } // parseManifest decodes one plugin.json, keeping the keys Manifest has no field for in Extra. func parseManifest(data []byte) (manifest, error) { + if err := checkStrict(data); err != nil { + return manifest{}, err + } var m manifest var raw map[string]json.RawMessage err := json.Unmarshal(data, &m) diff --git a/pluginkit/wire/manifest_identity_test.go b/pluginkit/wire/manifest_identity_test.go index c8e2903..e6a8e6d 100644 --- a/pluginkit/wire/manifest_identity_test.go +++ b/pluginkit/wire/manifest_identity_test.go @@ -13,7 +13,8 @@ import ( ) // everyNewKey is every key a manifest may name beside the ones wire has always read. -const everyNewKey = `"version": "2.0.0", +const everyNewKey = `"description": "Sells seats for the events a site holds.", + "version": "2.0.0", "license": "Apache-2.0", "did": "did:plc:example", "requires": {"app": ">=0.31.0"}, @@ -197,6 +198,10 @@ func todaysErrors() map[string]todaysErrorCase { dir: "listed", manifest: `[]`, want: "json: cannot unmarshal array into Go value of type wire.manifest", }, + "a list at the top level holding a key in another case": { + dir: "listed", manifest: `[{"id": "listed", "Name": "Listed"}]`, + want: "json: cannot unmarshal array into Go value of type wire.manifest", + }, "a missing id": { dir: "anon", manifest: `{"name": "Anon", "backend": "example.com/anon"}`, want: `id "" must match ^[a-z][a-z0-9-]*$`, diff --git a/pluginkit/wire/manifest_index_test.go b/pluginkit/wire/manifest_index_test.go index 83c23a8..8c839a2 100644 --- a/pluginkit/wire/manifest_index_test.go +++ b/pluginkit/wire/manifest_index_test.go @@ -38,6 +38,7 @@ const fullIndex = `[ "name": "Events", "backend": "example.com/myapp/plugins/events", "frontend": "@myapp/plugin-events", + "description": "Sells seats for the events a site holds.", "version": "2.0.0", "license": "Apache-2.0", "did": "did:plc:example", diff --git a/pluginkit/wire/manifest_keys.go b/pluginkit/wire/manifest_keys.go new file mode 100644 index 0000000..9cfbb50 --- /dev/null +++ b/pluginkit/wire/manifest_keys.go @@ -0,0 +1,132 @@ +// SPDX-License-Identifier: Apache-2.0 + +package wire + +import ( + "bytes" + "encoding/json" + "errors" + "fmt" + "regexp" + "slices" + "strings" +) + +// keyShape is the json names of one struct a manifest is read into, and the shape of each entry of a list it holds. +type keyShape struct { + names []string + entries map[string]keyShape +} + +// manifestShape is how a manifest is read, from its top level down to each entry of its lists. +var manifestShape = keyShape{names: typedKeys, entries: map[string]keyShape{ + "defines": {names: []string{"hook", "kind", "fires"}}, + "jobs": {names: []string{"name", "every"}}, + "settings": {names: []string{"key", "type", "default", "label", "help", "min", "max", "options", "of"}}, + "menu": {names: []string{"label", "screen", "parent", "position", "capability", "icon"}}, +}} + +// keyPath is the steps from the top of a manifest down to one value, each a key or the index of a list entry. +type keyPath []any + +// plainKey matches a key a place writes after a dot, any other key being quoted in brackets. +var plainKey = regexp.MustCompile(`^[\pL\pN_-]+$`) + +// stepName returns how a place writes step, as [0] for an index, .key for a plain key and ["key"] for any other. +func stepName(step any) string { + key, isKey := step.(string) + switch { + case !isKey: + return fmt.Sprintf("[%d]", step) + case plainKey.MatchString(key): + return "." + key + } + return fmt.Sprintf("[%q]", key) +} + +// reject returns problem as an error, after the place p names when it sits below the top level. +func (p keyPath) reject(problem string) error { + if len(p) == 0 { + return errors.New(problem) + } + var place strings.Builder + for _, step := range p { + place.WriteString(stepName(step)) + } + return fmt.Errorf("%s: %s", strings.TrimPrefix(place.String(), "."), problem) +} + +// check rejects key when the object at p holds it already, or when it is one of the names of s in another case. +func (s keyShape) check(p keyPath, key string, seen map[string]bool) error { + if seen[key] { + return p.reject(fmt.Sprintf("the key %q appears twice", key)) + } + i := slices.IndexFunc(s.names, func(name string) bool { return strings.EqualFold(key, name) }) + if i >= 0 && s.names[i] != key { + return p.reject(fmt.Sprintf("the key %q must be spelled %q", key, s.names[i])) + } + return nil +} + +// keyWalk reads the tokens of a manifest json.Valid accepted, so no read of a token fails. +type keyWalk struct { + dec *json.Decoder +} + +// checkStrict rejects what encoding/json v2 rejects and v1 reads: bad text, a repeated name or a key in another case. +func checkStrict(data []byte) error { + if !json.Valid(data) { + return nil + } + if err := checkText(data); err != nil { + return err + } + dec := json.NewDecoder(bytes.NewReader(data)) + dec.UseNumber() + return keyWalk{dec: dec}.value(nil, manifestShape, keyShape{}) +} + +// next returns the next token of the manifest. +func (w keyWalk) next() json.Token { + token, _ := w.dec.Token() + return token +} + +// value checks the next value at p, an object in it read as asObject and each entry of a list in it as asEntry. +func (w keyWalk) value(p keyPath, asObject, asEntry keyShape) error { + switch w.next() { + case json.Delim('{'): + return w.object(p, asObject) + case json.Delim('['): + return w.list(p, asEntry) + } + return nil +} + +// object checks each key of an object at p read as s and the value under it, up to its closing brace. +func (w keyWalk) object(p keyPath, s keyShape) error { + seen := map[string]bool{} + for w.dec.More() { + key, _ := w.next().(string) + if err := s.check(p, key, seen); err != nil { + return err + } + seen[key] = true + if err := w.value(append(p, key), keyShape{}, s.entries[key]); err != nil { + return err + } + } + w.next() + return nil +} + +// list checks each entry of a list at p, an object entry read as s, up to its closing bracket. +func (w keyWalk) list(p keyPath, s keyShape) error { + for i := 0; w.dec.More(); i++ { + if err := w.value(append(p, i), s, keyShape{}); err != nil { + return err + } + } + w.next() + return nil +} diff --git a/pluginkit/wire/manifest_keys_test.go b/pluginkit/wire/manifest_keys_test.go new file mode 100644 index 0000000..7fbc8db --- /dev/null +++ b/pluginkit/wire/manifest_keys_test.go @@ -0,0 +1,121 @@ +// SPDX-License-Identifier: Apache-2.0 + +package wire + +import ( + "encoding/json" + "testing" +) + +// wrongCaseKeys lists keys a struct of the manifest reads, spelled in another case, and the text rejecting each. +func wrongCaseKeys() map[string]wrongShape { + return map[string]wrongShape{ + "a top level key in capitals": { + `"DESCRIPTION": "Sells seats"`, `the key "DESCRIPTION" must be spelled "description"`, + }, + "a top level key in mixed case": {`"Version": "2.0.0"`, `the key "Version" must be spelled "version"`}, + "a top level key beside its own spelling": {`"Name": "Other"`, `the key "Name" must be spelled "name"`}, + "a top level key with an underscore": { + `"Screen_Capabilities": {"seats": "a"}`, `the key "Screen_Capabilities" must be spelled "screen_capabilities"`, + }, + "a top level key that folds by Unicode": {`"job` + "ſ" + `": []`, `the key "jobſ" must be spelled "jobs"`}, + "a key in another case before a wrong type": { + `"Version": 5`, `the key "Version" must be spelled "version"`, + }, + "a setting key": { + `"settings": [{"key": "a", "type": "b", "Label": "c"}]`, `settings[0]: the key "Label" must be spelled "label"`, + }, + "a later setting key": { + `"settings": [{"key": "a", "type": "b"}, {"KEY": "c", "type": "d"}]`, + `settings[1]: the key "KEY" must be spelled "key"`, + }, + "a menu entry key": { + `"menu": [{"label": "a", "screen": "b", "Capability": "c"}]`, + `menu[0]: the key "Capability" must be spelled "capability"`, + }, + "a job key": {`"jobs": [{"name": "a", "EVERY": "1h"}]`, `jobs[0]: the key "EVERY" must be spelled "every"`}, + "a define object key": { + `"defines": ["a", {"Hook": "b"}]`, `defines[1]: the key "Hook" must be spelled "hook"`, + }, + } +} + +// repeatedKeys lists objects that hold one name twice, and the text rejecting each. +func repeatedKeys() map[string]wrongShape { + return map[string]wrongShape{ + "a top level key twice": {`"name": "Other"`, `the key "name" appears twice`}, + "an extra key twice": {`"note": 1, "note": 2`, `the key "note" appears twice`}, + "a key twice once written escaped": {`"pages/all": 1, "pages\/all": 2`, `the key "pages/all" appears twice`}, + "a key twice before a wrong type": {`"version": "1", "version": 5`, `the key "version" appears twice`}, + "a list key twice": { + `"defines": [{"hook": "a", "kind": "filter", "fires": "job"}], "defines": ["b"]`, + `the key "defines" appears twice`, + }, + "a list key twice with no hook": { + `"defines": [{"hook": "a"}], "defines": [{"kind": "filter"}]`, `the key "defines" appears twice`, + }, + "a list key twice with a null": {`"defines": [{"hook": "a"}], "defines": [null]`, `the key "defines" appears twice`}, + "a setting key twice": { + `"settings": [{"key": "a", "type": "b", "key": "c"}]`, `settings[0]: the key "key" appears twice`, + }, + "a define object key twice": { + `"defines": [{"hook": "a", "hook": "b"}]`, `defines[0]: the key "hook" appears twice`, + }, + "a requires key twice": {`"requires": {"app": "1", "app": "2"}`, `requires: the key "app" appears twice`}, + "a key twice inside an extra value": { + `"pages": [{"word": "forums"}, {"word": "forums", "word": "topics"}]`, `pages[1]: the key "word" appears twice`, + }, + "a key twice deep inside an extra value": { + `"assets": {"style": {"a": 1, "a": 2}}`, `assets.style: the key "a" appears twice`, + }, + "a key twice after a number past float64": { + `"pages": [1e400, {"a": 1, "a": 2}]`, `pages[1]: the key "a" appears twice`, + }, + "a key twice under an empty key": {`"": {"a": 1, "a": 2}`, `[""]: the key "a" appears twice`}, + "a key twice under a key holding a dot": { + `"a.b": {"c": 1, "c": 2}`, `["a.b"]: the key "c" appears twice`, + }, + "a key twice under a later key holding a bracket": { + `"assets": {"x[0]": [{"c": 1, "c": 2}]}`, `assets["x[0]"][0]: the key "c" appears twice`, + }, + } +} + +func TestLoadReadsAKeyOfDataAsWritten(t *testing.T) { + t.Parallel() + + got := feedWith(t, `"GraphQL": true, "note": 1, "Note": 2, "ver-sion": "a", "ver_sion": "b", `+ + `"pages": [{"Word": "forums", "word": "topics"}], "requires": {"App": ">=1", "app": ">=2"}, `+ + `"screen_capabilities": {"Seats": "events.manage"}, "settings": [{"key": "a", "type": "b", "Note": 1}]`) + + assertSame(t, got.Requires, map[string]string{"App": ">=1", "app": ">=2"}) + assertSame(t, got.ScreenCapabilities, map[string]string{"Seats": "events.manage"}) + assertSame(t, got.Settings, []Setting{{Key: "a", Type: "b"}}) + assertSame(t, got.Extra, map[string]json.RawMessage{ + "GraphQL": json.RawMessage(`true`), + "note": json.RawMessage(`1`), + "Note": json.RawMessage(`2`), + "ver-sion": json.RawMessage(`"a"`), + "ver_sion": json.RawMessage(`"b"`), + "pages": json.RawMessage(`[{"Word": "forums", "word": "topics"}]`), + }) +} + +func TestManifestRejectsAWrongKeyWhenReadBack(t *testing.T) { + t.Parallel() + + tests := map[string]struct{ index, want string }{ + "a key in another case": {`[{"id": "feed", "Name": "Feed"}]`, `the key "Name" must be spelled "name"`}, + "a key twice": {`[{"id": "feed", "id": "other"}]`, `the key "id" appears twice`}, + } + for name, tc := range tests { + t.Run(name, func(t *testing.T) { + t.Parallel() + + var got []Manifest + err := json.Unmarshal([]byte(tc.index), &got) + + assertErrorText(t, err, tc.want) + }) + } +} diff --git a/pluginkit/wire/manifest_test.go b/pluginkit/wire/manifest_test.go index 8103cd8..5069b59 100644 --- a/pluginkit/wire/manifest_test.go +++ b/pluginkit/wire/manifest_test.go @@ -18,6 +18,7 @@ const fullManifest = `{ "name": "Events", "backend": "example.com/myapp/plugins/events", "frontend": "@myapp/plugin-events", + "description": "Sells seats for the events a site holds.", "version": "2.0.0", "license": "Apache-2.0", "did": "did:plc:example", @@ -58,18 +59,19 @@ func position(value int) *int { // fullManifestRead is what fullManifest reads as. func fullManifestRead() Manifest { return Manifest{ - ID: "events", - Name: "Events", - Backend: "example.com/myapp/plugins/events", - Frontend: "@myapp/plugin-events", - Version: "2.0.0", - License: "Apache-2.0", - DID: "did:plc:example", - Requires: map[string]string{"app": ">=0.31.0", "shop": "^2.1"}, - Tested: "0.32", - Engines: []string{"postgres", "sqlite"}, - Uninstall: true, - Hooks: []string{"content.changed", "page.head"}, + ID: "events", + Name: "Events", + Backend: "example.com/myapp/plugins/events", + Frontend: "@myapp/plugin-events", + Description: "Sells seats for the events a site holds.", + Version: "2.0.0", + License: "Apache-2.0", + DID: "did:plc:example", + Requires: map[string]string{"app": ">=0.31.0", "shop": "^2.1"}, + Tested: "0.32", + Engines: []string{"postgres", "sqlite"}, + Uninstall: true, + Hooks: []string{"content.changed", "page.head"}, Defines: []Define{ {Hook: "shop.order-placed"}, {Hook: "forum.post-check", Kind: "filter", Fires: "job"}, @@ -223,20 +225,6 @@ func TestDefineKeepsTheEntryItFailsToRead(t *testing.T) { assertSame(t, got, Define{Hook: "old", Kind: "filter", Fires: "job"}) } -func TestLoadReadsARepeatedDefinesAsTheLastOne(t *testing.T) { - t.Parallel() - - for name, last := range map[string]string{"a plain string": `"b"`, "an object": `{"hook": "b"}`} { - t.Run(name, func(t *testing.T) { - t.Parallel() - - got := feedWith(t, `"defines": [{"hook": "a", "kind": "filter", "fires": "job"}], "defines": [`+last+`]`) - - assertSame(t, got.Defines, []Define{{Hook: "b"}}) - }) - } -} - func TestLoadLeavesAnAbsentFiresEmpty(t *testing.T) { t.Parallel() @@ -286,6 +274,29 @@ func TestLoadKeepsAZeroPositionApartFromAnAbsentOne(t *testing.T) { }) } +func TestLoadReadsADescriptionIntoItsOwnFieldAndNotIntoExtra(t *testing.T) { + t.Parallel() + + got := feedWith(t, `"description": "Serves the published posts as an RSS feed."`) + + assertSame(t, got.Description, "Serves the published posts as an RSS feed.") + assertSame(t, got.Extra, map[string]json.RawMessage(nil)) +} + +func TestADescriptionReachesTheIndexAndReadsBack(t *testing.T) { + t.Parallel() + + written := Manifest{ID: "feed", Name: "Feed", Description: "Serves the published posts as an RSS feed."} + + data, err := json.Marshal(written) + + assertErrorFree(t, err) + assertSame(t, string(data), `{"id":"feed","name":"Feed","description":"Serves the published posts as an RSS feed."}`) + var read Manifest + assertErrorFree(t, json.Unmarshal(data, &read)) + assertSame(t, read, written) +} + func TestLoadKeepsAnUnknownKeyInExtra(t *testing.T) { t.Parallel() @@ -301,8 +312,9 @@ func TestLoadKeepsAnUnknownKeyInExtra(t *testing.T) { func TestLoadReadsANullAsAnAbsentKey(t *testing.T) { t.Parallel() - got := feedWith(t, `"version": null, "requires": null, "engines": null, "uninstall": null, "hooks": null, `+ - `"defines": null, "jobs": null, "settings": null, "menu": null, "screens": null, "screen_capabilities": null`) + got := feedWith(t, `"description": null, "version": null, "requires": null, "engines": null, "uninstall": null, `+ + `"hooks": null, "defines": null, "jobs": null, "settings": null, "menu": null, "screens": null, `+ + `"screen_capabilities": null`) want, err := loadOne(t, "feed", feedManifest) assertErrorFree(t, err) @@ -369,35 +381,40 @@ func TestReadLeavesTheIDsTheGeneratedWiringOwnsToLoad(t *testing.T) { } } -func TestLoadReadsANewKeyInAnyCaseAsEncodingJSONDoes(t *testing.T) { - t.Parallel() - - got := feedWith(t, `"Version": "2.0.0", "ENGINES": ["sqlite"], "job`+"ſ"+`": [{"NAME": "sweep", "Every": "1h"}], `+ - `"defines": [{"HOOK": "a", "Kind": "b", "FIRES": "c"}], "ver-sion": "a", "ver_sion": "b"`) - - assertSame(t, got.Version, "2.0.0") - assertSame(t, got.Engines, []string{"sqlite"}) - assertSame(t, got.Jobs, []Job{{Name: "sweep", Every: "1h"}}) - assertSame(t, got.Defines, []Define{{Hook: "a", Kind: "b", Fires: "c"}}) - assertSame(t, got.Extra, map[string]json.RawMessage{ - "ver-sion": json.RawMessage(`"a"`), - "ver_sion": json.RawMessage(`"b"`), - }) +// shapeOf returns the names encoding/json reads the struct type typ by, from its json tags, and its list entry structs. +func shapeOf(t *testing.T, typ reflect.Type) keyShape { + t.Helper() + var shape keyShape + for i := range typ.NumField() { + field := typ.Field(i) + name, _, _ := strings.Cut(field.Tag.Get("json"), ",") + if name == "-" { + continue + } + shape.names = append(shape.names, name) + inner := field.Type + for inner.Kind() == reflect.Pointer || inner.Kind() == reflect.Slice { + inner = inner.Elem() + } + if inner.Kind() != reflect.Struct { + continue + } + if field.Type.Kind() != reflect.Slice { + t.Errorf("%s.%s reads a struct outside a list, which checkStrict does not read", typ.Name(), field.Name) + } + if shape.entries == nil { + shape.entries = map[string]keyShape{} + } + shape.entries[name] = shapeOf(t, inner) + } + return shape } -func TestTypedKeysNameEveryManifestField(t *testing.T) { +func TestManifestShapeNamesEveryJSONFieldOfEachStruct(t *testing.T) { t.Parallel() - var fromTags []string - fields := reflect.TypeFor[Manifest]() - for i := range fields.NumField() { - name, _, _ := strings.Cut(fields.Field(i).Tag.Get("json"), ",") - if name != "-" { - fromTags = append(fromTags, name) - } - } - - assertSame(t, typedKeys, fromTags) + assertSame(t, manifestShape, shapeOf(t, reflect.TypeFor[Manifest]())) + assertSame(t, manifestShape.names, typedKeys) } // wrongShape is one set of keys a manifest may not hold, and the text refusing them. @@ -406,6 +423,10 @@ type wrongShape struct{ keys, want string } // wrongTypes lists keys of the wrong JSON type, and what the decoder says of each. func wrongTypes() map[string]wrongShape { return map[string]wrongShape{ + "a number for description": { + `"description": 5`, + "json: cannot unmarshal number into Go struct field manifest.description of type string", + }, "a number for version": { `"version": 5`, "json: cannot unmarshal number into Go struct field manifest.version of type string", }, @@ -485,6 +506,10 @@ func wrongEntryTypes() map[string]wrongShape { `"settings": [{"key": "a", "type": "b", "max": "1"}]`, "json: cannot unmarshal string into Go struct field manifest.settings.0.max of type float64", }, + "a list in settings holding a key in another case": { + `"settings": [[{"KEY": "a"}]]`, + "json: cannot unmarshal array into manifest.settings.0 of type wire.Setting", + }, } } @@ -501,6 +526,10 @@ func wrongDefines() map[string]wrongShape { "a list in defines": { `"defines": [["a"]]`, "defines[0]: json: cannot unmarshal array into Go value of type wire.define", }, + "a list in defines holding a key in another case": { + `"defines": [[{"Hook": "a"}]]`, + "defines[0]: json: cannot unmarshal array into Go value of type wire.define", + }, "true in defines": { `"defines": [true]`, "defines[0]: json: cannot unmarshal bool into Go value of type wire.define", }, @@ -532,11 +561,7 @@ func emptyValues() map[string]wrongShape { "an empty string in defines": {`"defines": [""]`, "defines[0]: hook is required"}, "a defines entry with no hook": {`"defines": ["a", {"kind": "filter"}]`, "defines[1]: hook is required"}, "a null in defines": {`"defines": [null]`, "defines[0]: hook is required"}, - "a repeated defines with no hook": { - `"defines": [{"hook": "a"}], "defines": [{"kind": "filter"}]`, "defines[0]: hook is required", - }, - "a repeated defines with a null": {`"defines": [{"hook": "a"}], "defines": [null]`, "defines[0]: hook is required"}, - "a job with no name": {`"jobs": [{"every": "24h"}]`, "jobs[0]: name is required"}, + "a job with no name": {`"jobs": [{"every": "24h"}]`, "jobs[0]: name is required"}, "a job with no interval": { `"jobs": [{"name": "a", "every": "1h"}, {"name": "b"}]`, "jobs[1]: every is required", }, @@ -566,6 +591,10 @@ func wrongScreenTypes() map[string]wrongShape { `"menu": {"label": "a"}`, "json: cannot unmarshal object into Go struct field manifest.menu of type []wire.MenuEntry", }, + "an object for menu holding a key in another case": { + `"menu": {"Label": "a"}`, + "json: cannot unmarshal object into Go struct field manifest.menu of type []wire.MenuEntry", + }, "a number for a menu label": { `"menu": [{"label": 5, "screen": "a", "capability": "b"}]`, "json: cannot unmarshal number into Go struct field manifest.menu.0.label of type string", @@ -678,6 +707,7 @@ func eachWrongShape(t *testing.T, check func(t *testing.T, tc wrongShape)) { t.Helper() for _, shapes := range []map[string]wrongShape{ wrongTypes(), wrongEntryTypes(), wrongDefines(), emptyValues(), wrongScreenTypes(), emptyScreenValues(), + wrongCaseKeys(), repeatedKeys(), invalidText(), } { for name, tc := range shapes { t.Run(name, func(t *testing.T) { diff --git a/pluginkit/wire/manifest_text.go b/pluginkit/wire/manifest_text.go new file mode 100644 index 0000000..ab9a622 --- /dev/null +++ b/pluginkit/wire/manifest_text.go @@ -0,0 +1,59 @@ +// SPDX-License-Identifier: Apache-2.0 + +package wire + +import ( + "bytes" + "errors" + "strconv" + "unicode" + "unicode/utf16" + "unicode/utf8" +) + +// plainEscape and unitEscape are the lengths of an escape such as \n and of one naming a UTF-16 code unit. +const ( + plainEscape = 2 + unitEscape = 6 +) + +// unitPrefix starts an escape naming a UTF-16 code unit by four hex digits. +var unitPrefix = []byte(`\u`) + +// checkText rejects data, JSON json.Valid accepted, when it is not valid UTF-8 or escapes a surrogate with no pair. +func checkText(data []byte) error { + if !utf8.Valid(data) { + return errors.New("the manifest holds text that is not valid UTF-8") + } + rest := data + for at := bytes.IndexByte(rest, '\\'); at >= 0; at = bytes.IndexByte(rest, '\\') { + size, paired := escapeAt(rest[at:]) + if !paired { + return errors.New("the manifest holds an escaped surrogate with no pair") + } + rest = rest[at+size:] + } + return nil +} + +// escapeAt returns the length of the escape at the start of b, and whether each surrogate it names sits in a pair. +func escapeAt(b []byte) (int, bool) { + first := unitAt(b) + switch { + case first < 0: + return plainEscape, true + case !utf16.IsSurrogate(first): + return unitEscape, true + } + return 2 * unitEscape, utf16.DecodeRune(first, unitAt(b[unitEscape:])) != unicode.ReplacementChar +} + +// unitAt returns the UTF-16 code unit an escape at the start of b names, or -1 when b starts with no such escape. +func unitAt(b []byte) rune { + digits, named := bytes.CutPrefix(b, unitPrefix) + if !named { + return -1 + } + unit, _ := strconv.ParseUint(string(digits[:unitEscape-len(unitPrefix)]), 16, 16) + return rune(unit) +} diff --git a/pluginkit/wire/manifest_text_test.go b/pluginkit/wire/manifest_text_test.go new file mode 100644 index 0000000..6f6632b --- /dev/null +++ b/pluginkit/wire/manifest_text_test.go @@ -0,0 +1,55 @@ +// SPDX-License-Identifier: Apache-2.0 + +package wire + +import ( + "fmt" + "strings" + "testing" +) + +// escapes returns each UTF-16 code unit written as a JSON escape of four hex digits. +func escapes(units ...rune) string { + var b strings.Builder + for _, unit := range units { + fmt.Fprintf(&b, `\u%04x`, unit) + } + return b.String() +} + +// notUTF8 is the text rejecting a manifest whose bytes are not valid UTF-8. +const notUTF8 = "the manifest holds text that is not valid UTF-8" + +// unpaired is the text rejecting a manifest that escapes a surrogate with no pair. +const unpaired = "the manifest holds an escaped surrogate with no pair" + +// invalidText lists text that encoding/json v1 reads by replacing it, and the text rejecting each. +func invalidText() map[string]wrongShape { + return map[string]wrongShape{ + "a cut sequence in a value": {`"description": "a` + "\xe2\x82" + `b"`, notUTF8}, + "a cut four byte sequence": {`"description": "a` + "\xf0\x9f\x98" + `b"`, notUTF8}, + "a byte that is never UTF-8": {`"note": "` + "\xff" + `"`, notUTF8}, + "a byte that is not UTF-8 in a key": {`"no` + "\xff" + `te": 1`, notUTF8}, + "a surrogate written as bytes": {`"description": "` + "\xed\xa0\x80" + `"`, notUTF8}, + "a lone high surrogate": {`"description": "` + escapes(0xd800) + `"`, unpaired}, + "a lone low surrogate": {`"description": "` + escapes(0xdc00) + `"`, unpaired}, + "a reversed surrogate pair": {`"description": "` + escapes(0xdc00, 0xd800) + `"`, unpaired}, + "two high surrogates": {`"description": "` + escapes(0xd83d, 0xd83d) + `"`, unpaired}, + "a high surrogate before a letter": {`"description": "` + escapes(0xd83d) + `a"`, unpaired}, + "a lone surrogate in a key": {`"` + escapes(0xd800) + `": 1`, unpaired}, + "a lone surrogate after a pair": { + `"pages": ["` + escapes(0xd83d, 0xde00) + `", "` + escapes(0xde00) + `"]`, unpaired, + }, + "a lone surrogate inside a setting": { + `"settings": [{"key": "a", "type": "b", "label": "` + escapes(0xd800) + `"}]`, unpaired, + }, + } +} + +func TestLoadReadsEscapedText(t *testing.T) { + t.Parallel() + + got := feedWith(t, `"description": "caf`+escapes(0xe9)+` `+escapes(0xd83d, 0xde00)+` \\`+`ud800 \" \/ \n x"`) + + assertSame(t, got.Description, "café 😀 "+`\`+"ud800 \" / \n x") +}