diff --git a/docs/README.md b/docs/README.md index 66af234..9b5d43b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -178,6 +178,7 @@ edit the command's Short, Long, Example or flag usage and run `make docs`. | [`n8n promotion environment disconnect`](n8n_promotion_environment_disconnect.md) | Remove the local checkout of a promotion environment | | [`n8n promotion environment get`](n8n_promotion_environment_get.md) | Show one promotion environment | | [`n8n promotion environment list`](n8n_promotion_environment_list.md) | List promotion environments | +| [`n8n promotion environment missing-projects`](n8n_promotion_environment_missing-projects.md) | List branch projects missing on this instance (n8n 2.47 and later) | | [`n8n promotion environment project add`](n8n_promotion_environment_project_add.md) | Link a project to a promotion environment | | [`n8n promotion environment project list`](n8n_promotion_environment_project_list.md) | List projects linked to a promotion environment | | [`n8n promotion environment project remove`](n8n_promotion_environment_project_remove.md) | Unlink a project from a promotion environment | @@ -203,6 +204,9 @@ edit the command's Short, Long, Example or flag usage and run `make docs`. | [`n8n promotion provider update`](n8n_promotion_provider_update.md) | Update a promotion provider | | [`n8n promotion provider`](n8n_promotion_provider.md) | Manage promotion providers | | [`n8n promotion`](n8n_promotion.md) | Manage promotion providers, environments, connections, and apply/promote sync | +| [`n8n rate-limit get`](n8n_rate-limit_get.md) | Get Public API rate-limit settings | +| [`n8n rate-limit set`](n8n_rate-limit_set.md) | Fully replace Public API rate-limit settings | +| [`n8n rate-limit`](n8n_rate-limit.md) | Manage Public API rate limits | | [`n8n role create`](n8n_role_create.md) | Create a custom role | | [`n8n role delete`](n8n_role_delete.md) | Permanently delete a custom role | | [`n8n role get`](n8n_role_get.md) | Get one role | diff --git a/docs/n8n.md b/docs/n8n.md index 9dc46d3..fb06729 100644 --- a/docs/n8n.md +++ b/docs/n8n.md @@ -71,6 +71,7 @@ n8n [flags] * [n8n package](n8n_package.md) - Export and import n8n packages (beta) * [n8n project](n8n_project.md) - Manage projects and their members * [n8n promotion](n8n_promotion.md) - Manage promotion providers, environments, connections, and apply/promote sync +* [n8n rate-limit](n8n_rate-limit.md) - Manage Public API rate limits * [n8n role](n8n_role.md) - Manage global and project roles * [n8n role-mapping](n8n_role-mapping.md) - Manage identity-provider role-mapping rules * [n8n saml](n8n_saml.md) - Manage licensed SAML SSO settings diff --git a/docs/n8n_package_import-selection.md b/docs/n8n_package_import-selection.md index 7e0d886..ec7aef5 100644 --- a/docs/n8n_package_import-selection.md +++ b/docs/n8n_package_import-selection.md @@ -21,16 +21,24 @@ executions permanently, so prefer archive). --workflow-id may be omitted for a delete-only run. Selected IDs from another project are dropped, absent delete IDs are a no-op, and an ID cannot be both imported and deleted. Folder, tag, and project policies are fixed by the server; only -the workflow conflict, workflow ID, and deletion policies are settable. -A workflow package is rejected with a 400: export a project package with -'n8n package export --project-id'. +the conflict, ID, and deletion policies are settable, and publication +follows match-source. A workflow package is rejected with a 400: export a +project package with 'n8n package export --project-id'. Packages that +contain Agents are rejected before writes on n8n 2.47 and later: import +selected-Agent exports with 'n8n package import'. n8n 2.47 renamed +--workflow-conflict-policy and --workflow-id-policy to --conflict-policy +and --id-policy (the old flags remain as deprecated aliases); older +instances get the old field names automatically, which needs --file +PATH because stdin cannot be sent twice. Beta: breaking changes may still occur without a major version bump. This mutates the instance, so interactive runs ask for confirmation and non-interactive runs require --yes; --file - also requires --yes because stdin cannot answer. Needs workflow:import, plus workflow:delete when -deleting or when an update changes a workflow's archive state, and the -licensed Packages feature. Output is the same import result as +deleting or when an update changes a workflow's archive state, +workflow:activate or workflow:deactivate when match-source changes +publication, and the licensed Packages feature. Output is the same +import result as 'n8n package import'. --idempotency-key KEY makes a retry after a timeout or lost response safe: @@ -46,25 +54,25 @@ n8n package import-selection [flags] ``` n8n package import-selection --file project.n8np --project-id Ox8O54VQrmBrb4qL --workflow-id 2tUt1wbLX592XDdX --workflow-id 7pQr3sTuVwXyZaBc --yes - n8n package import-selection --file project.n8np --project-id Ox8O54VQrmBrb4qL --workflow-id 2tUt1wbLX592XDdX --delete-workflow-id 9xKp2mNqRzAbCdEf --workflow-conflict-policy fail --output json --yes + n8n package import-selection --file project.n8np --project-id Ox8O54VQrmBrb4qL --workflow-id 2tUt1wbLX592XDdX --delete-workflow-id 9xKp2mNqRzAbCdEf --conflict-policy fail --output json --yes n8n package import-selection --file project.n8np --project-id Ox8O54VQrmBrb4qL --delete-workflow-id 9xKp2mNqRzAbCdEf --overwrite-deletion-policy hard-delete ``` ### Options ``` + --conflict-policy string selected workflow that already exists in the target project: new-version updates it, fail rejects the import, skip leaves it unchanged (default: server default new-version) --context string saved context name to use (falls back to N8N_CONTEXT, then the saved current context; see 'n8n config context list') --delete-workflow-id stringArray destination workflow ID to remove from the target project, repeatable; needs workflow:delete and must not match a --workflow-id (default: none) --file string project package archive (.n8np) to import from: a file path, or - for stdin (required; stdin requires --yes) -h, --help help for import-selection + --id-policy string ID for newly created workflows, always sent: source reuses the package ID; new mints a fresh ID but only instances before n8n 2.47 accept it (default: source) (default "source") --idempotency-key string retry key sent as the Idempotency-Key header: 1 to 128 visible ASCII characters, or auto for a random UUID printed on stderr; rerun the same command with the same key to get the first result instead of a second run (default: none, no idempotency) --output string output format: text or json (JSON is the full import result) (default "text") --overwrite-deletion-policy string how --delete-workflow-id removes workflows: archive (recoverable) or hard-delete (also drops executions permanently; prefer archive); needs --delete-workflow-id (default: server default archive) --project-id string source project ID as it appears in the package; also the target project ID, created if missing (required) --url string instance URL override, e.g. https://n8n.example.com (falls back to N8N_URL, then the selected context URL) - --workflow-conflict-policy string selected workflow that already exists in the target project: new-version updates it, fail rejects the import, skip leaves it unchanged (default: server default new-version) --workflow-id stringArray source workflow ID to import from --project-id, repeatable (default: none, for a delete-only run with --delete-workflow-id) - --workflow-id-policy string ID for newly created workflows, always sent: source reuses the package ID, new mints a fresh ID (default: source) (default "source") --yes confirm importing and deleting the listed workflows without prompting (required when stdin is not interactive) ``` diff --git a/docs/n8n_package_import.md b/docs/n8n_package_import.md index 2fce09c..0ed08e8 100644 --- a/docs/n8n_package_import.md +++ b/docs/n8n_package_import.md @@ -4,16 +4,26 @@ Import an n8n package into a project (beta) ### Synopsis -Import a gzip-compressed tar package (.n8np) into the target project. -Send the archive with --file FILE or --file - for stdin, route it with ---project-id and --folder-id (omit both for the caller's personal project -root), and state --workflow-conflict-policy explicitly: new-version -updates matching workflows, fail rejects the import when any matches, and -skip leaves matching workflows unchanged. +Import a gzip-compressed tar package (.n8np) into the target project: +Agent-only, workflow-only, mixed, or whole-project packages (Agents need +the Agents module). Send the archive with --file FILE or --file - for +stdin, route it with --project-id and --folder-id (omit both for the +caller's personal project root), and state --conflict-policy explicitly: +new-version replaces matching Agents and workflows (and saves a changed +skill of an imported Agent as a new version, which every Agent following +that skill picks up), fail rejects the import when any matches, and skip +leaves them unchanged. + +n8n 2.47 renamed the workflow-only policies to --conflict-policy, +--id-policy, and --publishing-policy, which cover Agents and workflows; +the old --workflow-* flags remain as deprecated aliases. Older instances +get the old field names automatically, which needs --file PATH: stdin +cannot be sent twice. Beta: breaking changes may still occur without a major version bump. -This mutates the instance: imported workflows arrive per ---workflow-publishing-policy, new-version follows the package archive +This mutates the instance: imported Agents and workflows arrive per +--publishing-policy (a failed publication keeps the imported definition +and is reported per entity), new-version follows the package archive state (archiving needs workflow:delete), folder overwrite can remove workflows the package does not contain (archive is recoverable, hard-delete also drops executions permanently, so prefer archive), @@ -27,11 +37,15 @@ Interactive runs ask for confirmation and non-interactive runs require --yes; --file - also requires --yes because stdin cannot answer. Credentials created from incomplete package data are reported on stderr and keep their workflows unpublished until completed. When the -import is blocked (409 or 422), each issue is listed on stderr. Needs -workflow:import plus, depending on the package and the policies, -credential, variable, tag, data-table, folder, and delete scopes, and -the Packages, Variables, and Folders features where the contents -require them. +import is blocked (409 or 422), each issue is listed on stderr, and +Agent channels that need setup are listed with their setup URL. Needs +workflow:import for workflows and agent:import plus agent:read for +Agents (both for mixed packages; agent:create, agent:update, +agent:publish, or agent:unpublish for the planned Agent actions), +workflow:activate or workflow:deactivate when publication changes, plus, +depending on the package and the policies, credential, variable, tag, +data-table, folder, skill, and delete scopes, and the Packages, +Variables, and Folders features where the contents require them. --idempotency-key KEY makes a retry after a timeout or lost response safe: the same request with the same key returns the first result instead of @@ -45,15 +59,16 @@ n8n package import [flags] ### Examples ``` - n8n package import --file workflows.n8np --workflow-conflict-policy new-version --yes - n8n package import --file project.n8np --workflow-conflict-policy fail --project-id Ox8O54VQrmBrb4qL --yes --output json - n8n package import --file update.n8np --workflow-conflict-policy skip --workflow-publishing-policy publish-all --yes + n8n package import --file workflows.n8np --conflict-policy new-version --yes + n8n package import --file project.n8np --conflict-policy fail --project-id Ox8O54VQrmBrb4qL --yes --output json + n8n package import --file agent.n8np --conflict-policy skip --publishing-policy match-source --yes ``` ### Options ``` --bindings string explicit credential bindings as JSON, e.g. '{"credentials":{"pkg-id":"target-id"}}' (default: server default {}) + --conflict-policy string matching Agent and workflow handling, required: new-version, fail, or skip (before n8n 2.47 workflows only) --context string saved context name to use (falls back to N8N_CONTEXT, then the saved current context; see 'n8n config context list') --credential-conflict-policy string matched credential whose package values differ: keep-existing never changes it, overwrite writes the package name and expression values to credentials a project of the import owns (keeps secrets, other fields, and OAuth connections; reported in credentials.updated), fail rejects the import with a 409 credential-conflict; overwrite and fail need credential:update on matched credentials (default: server default keep-existing) --credential-matching-mode string how package credential references match: id-only, name-and-type, or type-only (default: server default id-only) @@ -65,21 +80,20 @@ n8n package import [flags] --folder-conflict-policy string existing folder handling: merge, fail, or overwrite; empty follows --project-conflict-policy on project packages, merge otherwise (default: follow) --folder-id string folder within the target project, from 'n8n folder list PROJECT_ID' (default: the project root) -h, --help help for import + --id-policy string ID for newly created Agents and workflows, always sent: source reuses the package ID; new mints a fresh ID but only instances before n8n 2.47 accept it (default: source) (default "source") --idempotency-key string retry key sent as the Idempotency-Key header: 1 to 128 visible ASCII characters, or auto for a random UUID printed on stderr; rerun the same command with the same key to get the first result instead of a second run (default: none, no idempotency) --missing-node-type-mode string unknown node type handling: fail rejects before anything is written, import-anyway imports without publishing those workflows (default: server default fail) --output string output format: text or json (JSON is the full import result) (default "text") --overwrite-deletion-policy string how folder overwrite removes missing workflows: archive (recoverable) or hard-delete (also drops executions; prefer archive) (default: server default archive) --project-conflict-policy string existing project handling for project packages: merge, fail, or overwrite (default: server default merge) --project-id string target project ID, from 'n8n project list' (default: the caller's personal project) + --publishing-policy string post-import publishing of Agents and workflows: preserve-published-state, match-source, publish-all, or unpublish-all (default: server default preserve-published-state) --tag-conflict-policy string conflicted tag handling: skip, fail, or rename (default: server default skip) --tag-missing-mode string missing tag handling: create or do-nothing (default: server default create) --url string instance URL override, e.g. https://n8n.example.com (falls back to N8N_URL, then the selected context URL) --variable-conflict-policy string differing variable value handling: keep-existing, overwrite (may rewrite globals), or fail (default: server default keep-existing) --variable-missing-mode string missing variable handling: do-nothing, must-preexist, create-stub, or create-with-value (default: server default create-with-value) --variable-parent-policy string where workflow and folder packages create missing variables: project or global; omit for project packages, which reject it (default: import target project) - --workflow-conflict-policy string matching workflow handling, required: new-version, fail, or skip - --workflow-id-policy string ID for newly created workflows, always sent: source reuses the package ID for promotions, new mints a fresh ID for repeat imports (default: source) (default "source") - --workflow-publishing-policy string post-import publishing: preserve-published-state, match-source, publish-all, or unpublish-all (default: server default preserve-published-state) --yes confirm importing, publishing, archiving, deleting, and overwriting without prompting (required when stdin is not interactive) ``` diff --git a/docs/n8n_promotion_environment.md b/docs/n8n_promotion_environment.md index d31562c..56d7099 100644 --- a/docs/n8n_promotion_environment.md +++ b/docs/n8n_promotion_environment.md @@ -19,7 +19,7 @@ each direction. Sync the whole instance through the connected instance-scope environment: 'promote' pushes every team project to a promote environment; 'apply' imports an apply environment's branch, and -'apply-continue' finishes an apply that preflight blocked. For selected +'apply-continue' finishes an apply that its check blocked. For selected workflows of one project use 'n8n promotion project changes', 'apply', and 'promote'. @@ -59,6 +59,7 @@ n8n promotion environment [flags] * [n8n promotion environment disconnect](n8n_promotion_environment_disconnect.md) - Remove the local checkout of a promotion environment * [n8n promotion environment get](n8n_promotion_environment_get.md) - Show one promotion environment * [n8n promotion environment list](n8n_promotion_environment_list.md) - List promotion environments +* [n8n promotion environment missing-projects](n8n_promotion_environment_missing-projects.md) - List branch projects missing on this instance (n8n 2.47 and later) * [n8n promotion environment project](n8n_promotion_environment_project.md) - Manage projects linked to a promotion environment * [n8n promotion environment promote](n8n_promotion_environment_promote.md) - Promote team projects to an environment's Git remote * [n8n promotion environment update](n8n_promotion_environment_update.md) - Update a promotion environment diff --git a/docs/n8n_promotion_environment_apply-continue.md b/docs/n8n_promotion_environment_apply-continue.md index e0676a1..5c65a08 100644 --- a/docs/n8n_promotion_environment_apply-continue.md +++ b/docs/n8n_promotion_environment_apply-continue.md @@ -5,12 +5,12 @@ Continue a reviewed environment apply after binding setup ### Synopsis Continue a full environment apply (n8n 2.46 and later) after resolving its -preflight items. Start with 'n8n promotion environment apply ENVIRONMENT_ID +check items. Start with 'n8n promotion environment apply ENVIRONMENT_ID --output json'. The instance-scope apply environment must still be connected. Every team project is synchronized: workflows, folders, credentials, tables, variables, and tags can be created, updated, moved, -renamed, or removed to match. Requires gitConnection:pull and the same -permissions as the initial apply. +renamed, or removed to match. Requires promotions:apply (gitConnection:pull +before n8n 2.47) and the same permissions as the initial apply. Use --expected-from FILE|- with changes JSON or a blocked apply result, or supply --expected-environment-id, --expected-branch, and @@ -24,10 +24,12 @@ columns and loss of their values; rows and other columns remain. It also permits deleting team projects with everything in them. This covers every such change at continue time, including changes absent from the reviewed result. -Exit codes: 0 applied, 3 blocked, 4 source-changed, 1 other error. Only -applied writes content. Resolve blocked bindings before apply-continue; -review source-changed results again. JSON prints the full status result; -text shows preflight details or counts and warnings. Hints go to stderr. +Exit codes: 0 applied, 3 blocked, 4 source-changed or preview-changed +(n8n 2.47 and later), 1 other error. Only applied writes content. +Resolve blocked items before apply-continue; review source-changed and +preview-changed results again. JSON prints the full status result; text +shows the blocking check (preflight before n8n 2.47) or counts and +warnings. Hints go to stderr. Read request JSON with --input FILE|- (maximum 1 MiB). Input and document flags are mutually exclusive. Interactive runs ask for confirmation; non-interactive runs and stdin input require --yes. JSON returns the server result; text diff --git a/docs/n8n_promotion_environment_apply.md b/docs/n8n_promotion_environment_apply.md index 0e89286..5209830 100644 --- a/docs/n8n_promotion_environment_apply.md +++ b/docs/n8n_promotion_environment_apply.md @@ -16,7 +16,7 @@ or removed to match, workflows and folders move within their project, folders take the branch name, and credential gaps become stubs. Existing variable values are kept. A workflow or folder the branch and the instance hold in different projects is refused with 409 before any -write. Requires gitConnection:pull. +write. Requires promotions:apply (gitConnection:pull before n8n 2.47). Use --expected-from FILE|- with changes JSON or a blocked apply result, or supply --expected-environment-id, --expected-branch, and @@ -24,10 +24,12 @@ or supply --expected-environment-id, --expected-branch, and null commit cannot be used. --expected-from passes through the identifier the instance returned: environmentId. Expected source is optional; supply it to detect changes after review. -Exit codes: 0 applied, 3 blocked, 4 source-changed, 1 other error. Only -applied writes content. Resolve blocked bindings before apply-continue; -review source-changed results again. JSON prints the full status result; -text shows preflight details or counts and warnings. Hints go to stderr. +Exit codes: 0 applied, 3 blocked, 4 source-changed or preview-changed +(n8n 2.47 and later), 1 other error. Only applied writes content. +Resolve blocked items before apply-continue; review source-changed and +preview-changed results again. JSON prints the full status result; text +shows the blocking check (preflight before n8n 2.47) or counts and +warnings. Hints go to stderr. Read request JSON with --input FILE|- (maximum 1 MiB). Input and document flags are mutually exclusive. Interactive runs ask for confirmation; non-interactive runs and stdin input require --yes. JSON returns the server result; text diff --git a/docs/n8n_promotion_environment_connect.md b/docs/n8n_promotion_environment_connect.md index fc3cdff..b32459e 100644 --- a/docs/n8n_promotion_environment_connect.md +++ b/docs/n8n_promotion_environment_connect.md @@ -12,7 +12,7 @@ ready. Connecting is safe to repeat and changes no project content by itself, so it needs no confirmation. Connect again after 'get' reports a checkout that does not match the environment. Requires -gitConnection:clone. +promotions:connect (gitConnection:clone on n8n 2.46). ``` n8n promotion environment connect [flags] diff --git a/docs/n8n_promotion_environment_create.md b/docs/n8n_promotion_environment_create.md index 920823c..a660a4b 100644 --- a/docs/n8n_promotion_environment_create.md +++ b/docs/n8n_promotion_environment_create.md @@ -19,8 +19,8 @@ the provider base URL. Read-only fields from 'environment get --output json' (id, provider, checkout, createdAt, updatedAt, remote.repositoryPath) are dropped with a note on stderr; other unknown fields and trailing JSON documents are refused before transport. -Requires gitConnection:create. Follow with 'n8n promotion environment -connect ENVIRONMENT_ID'. +Requires promotions:create (gitConnection:create on n8n 2.46). Follow +with 'n8n promotion environment connect ENVIRONMENT_ID'. ``` n8n promotion environment create [flags] diff --git a/docs/n8n_promotion_environment_delete.md b/docs/n8n_promotion_environment_delete.md index cde3e1e..a70431c 100644 --- a/docs/n8n_promotion_environment_delete.md +++ b/docs/n8n_promotion_environment_delete.md @@ -13,7 +13,7 @@ created and connected again. This cannot be undone. To keep the environment and drop only the checkout, use 'n8n promotion environment disconnect' instead. Interactive runs ask for confirmation; non-interactive runs require --yes. Requires -gitConnection:delete. +promotions:delete (gitConnection:delete on n8n 2.46). ``` n8n promotion environment delete [flags] diff --git a/docs/n8n_promotion_environment_disconnect.md b/docs/n8n_promotion_environment_disconnect.md index 5ac460f..e8e82fb 100644 --- a/docs/n8n_promotion_environment_disconnect.md +++ b/docs/n8n_promotion_environment_disconnect.md @@ -10,7 +10,7 @@ project links are kept, but promote and apply through it stop working until 'connect' runs again. Interactive runs ask for confirmation; non-interactive runs require ---yes. Requires gitConnection:clone. +--yes. Requires promotions:connect (gitConnection:clone on n8n 2.46). ``` n8n promotion environment disconnect [flags] diff --git a/docs/n8n_promotion_environment_get.md b/docs/n8n_promotion_environment_get.md index bcfd2ae..7745d70 100644 --- a/docs/n8n_promotion_environment_get.md +++ b/docs/n8n_promotion_environment_get.md @@ -8,7 +8,8 @@ Show one promotion environment by ID: its name, scope, direction, remote, provider, settings, local checkout state, and timestamps. Secrets are never returned. Find the ID with 'n8n promotion environment list'. The --output json document can be edited and passed to 'update' -as is: its read-only fields are dropped. Requires gitConnection:read. +as is: its read-only fields are dropped. Requires promotions:read +(gitConnection:read on n8n 2.46). ``` n8n promotion environment get [flags] diff --git a/docs/n8n_promotion_environment_list.md b/docs/n8n_promotion_environment_list.md index 7c819a3..50760f0 100644 --- a/docs/n8n_promotion_environment_list.md +++ b/docs/n8n_promotion_environment_list.md @@ -11,7 +11,7 @@ are preserved across --all. Use --all to follow every cursor, capped at 10,000 environments. Use a returned ID with get, update, delete, connect, disconnect, and -project. Requires gitConnection:list. +project. Requires promotions:list (gitConnection:list on n8n 2.46). With --all, JSON output adds a collection object. Its truncated field is true, and a warning goes to stderr, when the walk stopped at the 10,000-item limit diff --git a/docs/n8n_promotion_environment_missing-projects.md b/docs/n8n_promotion_environment_missing-projects.md new file mode 100644 index 0000000..043f3db --- /dev/null +++ b/docs/n8n_promotion_environment_missing-projects.md @@ -0,0 +1,42 @@ +## n8n promotion environment missing-projects + +List branch projects missing on this instance (n8n 2.47 and later) + +### Synopsis + +Read the package at the branch tip of a connected instance-scope apply +environment and list its team projects whose IDs do not exist on this +instance. Projects match by ID, not by name; an ID a personal project +uses counts as existing. Nothing changes. + +Create each listed project with its ID, e.g. 'n8n project create NAME +--id PROJECT_ID', then apply its content with the project apply flow. +An empty list means no setup is needed. Find the environment ID with +'n8n promotion environment list --scope instance --direction apply' and +connect it first with 'n8n promotion environment connect'. The route +exists from n8n 2.47. Requires promotions:read. + +``` +n8n promotion environment missing-projects [flags] +``` + +### Examples + +``` + n8n promotion environment missing-projects ENVIRONMENT_ID + n8n promotion environment missing-projects ENVIRONMENT_ID --output json +``` + +### Options + +``` + --context string saved context name to use (falls back to N8N_CONTEXT, then the saved current context; see 'n8n config context list') + -h, --help help for missing-projects + --output string output format: text or json (JSON is the server result: environmentId, git, and data) (default "text") + --url string instance URL override, e.g. https://n8n.example.com (falls back to N8N_URL, then the selected context URL) +``` + +### SEE ALSO + +* [n8n promotion environment](n8n_promotion_environment.md) - Manage promotion environments (n8n 2.46 and later) + diff --git a/docs/n8n_promotion_environment_project.md b/docs/n8n_promotion_environment_project.md index d7a0386..c6f8f85 100644 --- a/docs/n8n_promotion_environment_project.md +++ b/docs/n8n_promotion_environment_project.md @@ -12,8 +12,8 @@ or 'remove' one. Removing unlinks the project; its instance content is untouched. Project IDs come from 'n8n project list'. Listing needs -gitConnection:read; adding and removing need -gitConnection:manageProjects. +promotions:read; adding and removing need promotions:manageProjects +(gitConnection:read and gitConnection:manageProjects on n8n 2.46). ``` n8n promotion environment project [flags] diff --git a/docs/n8n_promotion_environment_project_add.md b/docs/n8n_promotion_environment_project_add.md index 4cfff05..da3684c 100644 --- a/docs/n8n_promotion_environment_project_add.md +++ b/docs/n8n_promotion_environment_project_add.md @@ -8,7 +8,8 @@ Link one team project to one projects-scope promotion environment, so project-level sync in that direction uses this environment instead of the instance environment. A project can have one environment for each direction: adding a project that already has one for this direction -answers 409. Requires gitConnection:manageProjects. +answers 409. Requires promotions:manageProjects +(gitConnection:manageProjects on n8n 2.46). ``` n8n promotion environment project add [flags] diff --git a/docs/n8n_promotion_environment_project_list.md b/docs/n8n_promotion_environment_project_list.md index 0ed08f5..5537731 100644 --- a/docs/n8n_promotion_environment_project_list.md +++ b/docs/n8n_promotion_environment_project_list.md @@ -6,7 +6,8 @@ List projects linked to a promotion environment List the team projects linked to one projects-scope promotion environment. Find the environment ID with 'n8n promotion environment -list --scope projects'. Requires gitConnection:read. +list --scope projects'. Requires promotions:read (gitConnection:read on +n8n 2.46). ``` n8n promotion environment project list [flags] diff --git a/docs/n8n_promotion_environment_project_remove.md b/docs/n8n_promotion_environment_project_remove.md index 261f688..869c2d9 100644 --- a/docs/n8n_promotion_environment_project_remove.md +++ b/docs/n8n_promotion_environment_project_remove.md @@ -11,7 +11,8 @@ environment. Re-link it later with 'n8n promotion environment project add'. Interactive runs ask for confirmation; non-interactive runs require ---yes. Requires gitConnection:manageProjects. +--yes. Requires promotions:manageProjects (gitConnection:manageProjects +on n8n 2.46). ``` n8n promotion environment project remove [flags] diff --git a/docs/n8n_promotion_environment_promote.md b/docs/n8n_promotion_environment_promote.md index 6b520bf..96e8062 100644 --- a/docs/n8n_promotion_environment_promote.md +++ b/docs/n8n_promotion_environment_promote.md @@ -20,8 +20,8 @@ server-generated message). Without --force a promote the remote would reject is refused with 409 and nothing is pushed; --force pushes anyway and rewrites remote history. This mutates the remote branch. Interactive runs ask for confirmation and non-interactive runs require ---yes. Requires gitConnection:push, plus variable:list when workflows -reference variables. +--yes. Requires promotions:promote (gitConnection:push on n8n 2.46), +plus variable:list when workflows reference variables. Text shows the commit, branch, counts, and any review the Git host opened; JSON is the full result. Advisory warnings go to stderr in both diff --git a/docs/n8n_promotion_environment_update.md b/docs/n8n_promotion_environment_update.md index e33199b..241a106 100644 --- a/docs/n8n_promotion_environment_update.md +++ b/docs/n8n_promotion_environment_update.md @@ -19,7 +19,8 @@ means the provider changed during the update: reload and retry. A new remote or branch can leave the local checkout stale, so interactive runs ask for confirmation; non-interactive runs and ---input - require --yes. Requires gitConnection:update. +--input - require --yes. Requires promotions:update +(gitConnection:update on n8n 2.46). ``` n8n promotion environment update [flags] diff --git a/docs/n8n_promotion_project_apply-continue.md b/docs/n8n_promotion_project_apply-continue.md index 99663a1..a113be7 100644 --- a/docs/n8n_promotion_project_apply-continue.md +++ b/docs/n8n_promotion_project_apply-continue.md @@ -14,7 +14,8 @@ On 2.46 a selected workflow also moves within the project to match the branch, with the folders that hold it, which take the branch name; one the branch and the instance hold in different projects is refused with 409 before any write. Unselected content stays unchanged. Duplicate or -invalid IDs reject the whole request. Requires gitConnection:pull. +invalid IDs reject the whole request. Requires promotions:apply +(gitConnection:pull before n8n 2.47). Use --expected-from FILE|- with changes JSON or a blocked apply result, or supply --expected-environment-id (n8n 2.46 and later) or --expected-config-id (older; mutually exclusive), --expected-branch, and @@ -28,10 +29,15 @@ Resend the same full workflow ID selection used for the initial apply. columns and loss of their values; rows and other columns remain. This covers every such change at continue time, including changes absent from the reviewed result. -Exit codes: 0 applied, 3 blocked, 4 source-changed, 1 other error. Only -applied writes content. Resolve blocked bindings before apply-continue; -review source-changed results again. JSON prints the full status result; -text shows preflight details or counts and warnings. Hints go to stderr. +--expected-preview-revision (n8n 2.47 and later) pins the reviewed Apply +preview; when this instance changed since, the server answers +preview-changed and writes nothing. Older instances reject it. +Exit codes: 0 applied, 3 blocked, 4 source-changed or preview-changed +(n8n 2.47 and later), 1 other error. Only applied writes content. +Resolve blocked items before apply-continue; review source-changed and +preview-changed results again. JSON prints the full status result; text +shows the blocking check (preflight before n8n 2.47) or counts and +warnings. Hints go to stderr. Pass repeated --workflow-id flags, or use a strict JSON request. Read request JSON with --input FILE|- (maximum 1 MiB). Input and document flags are @@ -57,20 +63,21 @@ n8n promotion project apply-continue [flags] ### Options ``` - --confirm-destructive-changes allow all destructive changes at continue time, including unreviewed column value loss and, for full apply, team-project deletion (default: false) - --context string saved context name to use (falls back to N8N_CONTEXT, then the saved current context; see 'n8n config context list') - --expected-branch string reviewed branch name (default: omitted; requires the expected ID and commit) - --expected-commit string reviewed lowercase full 40- or 64-digit hex commit SHA (default: omitted; requires the expected ID and branch) - --expected-config-id string reviewed config ID on n8n 2.45 and earlier, 1 to 36 characters (default: omitted; requires expected branch and commit; excludes --expected-environment-id) - --expected-environment-id string reviewed environment ID on n8n 2.46 and later, 1 to 36 characters (default: omitted; requires expected branch and commit; excludes --expected-config-id) - --expected-from string changes or blocked-apply JSON file, or - for stdin (default: explicit expected-source flags; stdin requires --yes) - -h, --help help for apply-continue - --idempotency-key string retry key sent as the Idempotency-Key header: 1 to 128 visible ASCII characters, or auto for a random UUID printed on stderr; rerun the same command with the same key to get the first result instead of a second run (default: none, no idempotency) - --input string request JSON file path or - for stdin, maximum 1 MiB (default: use document flags; stdin requires --yes) - --output string output format: text or json (default: text; JSON is the full server result) (default "text") - --url string instance URL override, e.g. https://n8n.example.com (falls back to N8N_URL, then the selected context URL) - --workflow-id stringArray selected workflow ID, 1 to 36 characters; repeat for each ID (default: none; required unless --input is used) - --yes confirm content changes without prompting (default: prompt; required for non-interactive or stdin input) + --confirm-destructive-changes allow all destructive changes at continue time, including unreviewed column value loss and, for full apply, team-project deletion (default: false) + --context string saved context name to use (falls back to N8N_CONTEXT, then the saved current context; see 'n8n config context list') + --expected-branch string reviewed branch name (default: omitted; requires the expected ID and commit) + --expected-commit string reviewed lowercase full 40- or 64-digit hex commit SHA (default: omitted; requires the expected ID and branch) + --expected-config-id string reviewed config ID on n8n 2.45 and earlier, 1 to 36 characters (default: omitted; requires expected branch and commit; excludes --expected-environment-id) + --expected-environment-id string reviewed environment ID on n8n 2.46 and later, 1 to 36 characters (default: omitted; requires expected branch and commit; excludes --expected-config-id) + --expected-from string changes or blocked-apply JSON file, or - for stdin (default: explicit expected-source flags; stdin requires --yes) + --expected-preview-revision string revision of the reviewed Apply preview, 64 lowercase hex digits; a changed preview answers preview-changed and writes nothing (n8n 2.47 and later; default: omitted) + -h, --help help for apply-continue + --idempotency-key string retry key sent as the Idempotency-Key header: 1 to 128 visible ASCII characters, or auto for a random UUID printed on stderr; rerun the same command with the same key to get the first result instead of a second run (default: none, no idempotency) + --input string request JSON file path or - for stdin, maximum 1 MiB (default: use document flags; stdin requires --yes) + --output string output format: text or json (default: text; JSON is the full server result) (default "text") + --url string instance URL override, e.g. https://n8n.example.com (falls back to N8N_URL, then the selected context URL) + --workflow-id stringArray selected workflow ID, 1 to 36 characters; repeat for each ID (default: none; required unless --input is used) + --yes confirm content changes without prompting (default: prompt; required for non-interactive or stdin input) ``` ### SEE ALSO diff --git a/docs/n8n_promotion_project_apply.md b/docs/n8n_promotion_project_apply.md index 17beffa..9523073 100644 --- a/docs/n8n_promotion_project_apply.md +++ b/docs/n8n_promotion_project_apply.md @@ -14,7 +14,8 @@ On 2.46 a selected workflow also moves within the project to match the branch, with the folders that hold it, which take the branch name; one the branch and the instance hold in different projects is refused with 409 before any write. Unselected content stays unchanged. Duplicate or -invalid IDs reject the whole request. Requires gitConnection:pull. +invalid IDs reject the whole request. Requires promotions:apply +(gitConnection:pull before n8n 2.47). Use --expected-from FILE|- with changes JSON or a blocked apply result, or supply --expected-environment-id (n8n 2.46 and later) or --expected-config-id (older; mutually exclusive), --expected-branch, and @@ -22,10 +23,15 @@ or supply --expected-environment-id (n8n 2.46 and later) or null commit cannot be used. --expected-from passes through the identifier the instance returned: environmentId (2.46) or configId (older). Expected source is optional; supply it to detect changes after review. -Exit codes: 0 applied, 3 blocked, 4 source-changed, 1 other error. Only -applied writes content. Resolve blocked bindings before apply-continue; -review source-changed results again. JSON prints the full status result; -text shows preflight details or counts and warnings. Hints go to stderr. +--expected-preview-revision (n8n 2.47 and later) pins the reviewed Apply +preview; when this instance changed since, the server answers +preview-changed and writes nothing. Older instances reject it. +Exit codes: 0 applied, 3 blocked, 4 source-changed or preview-changed +(n8n 2.47 and later), 1 other error. Only applied writes content. +Resolve blocked items before apply-continue; review source-changed and +preview-changed results again. JSON prints the full status result; text +shows the blocking check (preflight before n8n 2.47) or counts and +warnings. Hints go to stderr. Pass repeated --workflow-id flags, or use a strict JSON request. Read request JSON with --input FILE|- (maximum 1 MiB). Input and document flags are @@ -51,19 +57,20 @@ n8n promotion project apply [flags] ### Options ``` - --context string saved context name to use (falls back to N8N_CONTEXT, then the saved current context; see 'n8n config context list') - --expected-branch string reviewed branch name (default: omitted; requires the expected ID and commit) - --expected-commit string reviewed lowercase full 40- or 64-digit hex commit SHA (default: omitted; requires the expected ID and branch) - --expected-config-id string reviewed config ID on n8n 2.45 and earlier, 1 to 36 characters (default: omitted; requires expected branch and commit; excludes --expected-environment-id) - --expected-environment-id string reviewed environment ID on n8n 2.46 and later, 1 to 36 characters (default: omitted; requires expected branch and commit; excludes --expected-config-id) - --expected-from string changes or blocked-apply JSON file, or - for stdin (default: explicit expected-source flags; stdin requires --yes) - -h, --help help for apply - --idempotency-key string retry key sent as the Idempotency-Key header: 1 to 128 visible ASCII characters, or auto for a random UUID printed on stderr; rerun the same command with the same key to get the first result instead of a second run (default: none, no idempotency) - --input string request JSON file path or - for stdin, maximum 1 MiB (default: use document flags; stdin requires --yes) - --output string output format: text or json (default: text; JSON is the full server result) (default "text") - --url string instance URL override, e.g. https://n8n.example.com (falls back to N8N_URL, then the selected context URL) - --workflow-id stringArray selected workflow ID, 1 to 36 characters; repeat for each ID (default: none; required unless --input is used) - --yes confirm content changes without prompting (default: prompt; required for non-interactive or stdin input) + --context string saved context name to use (falls back to N8N_CONTEXT, then the saved current context; see 'n8n config context list') + --expected-branch string reviewed branch name (default: omitted; requires the expected ID and commit) + --expected-commit string reviewed lowercase full 40- or 64-digit hex commit SHA (default: omitted; requires the expected ID and branch) + --expected-config-id string reviewed config ID on n8n 2.45 and earlier, 1 to 36 characters (default: omitted; requires expected branch and commit; excludes --expected-environment-id) + --expected-environment-id string reviewed environment ID on n8n 2.46 and later, 1 to 36 characters (default: omitted; requires expected branch and commit; excludes --expected-config-id) + --expected-from string changes or blocked-apply JSON file, or - for stdin (default: explicit expected-source flags; stdin requires --yes) + --expected-preview-revision string revision of the reviewed Apply preview, 64 lowercase hex digits; a changed preview answers preview-changed and writes nothing (n8n 2.47 and later; default: omitted) + -h, --help help for apply + --idempotency-key string retry key sent as the Idempotency-Key header: 1 to 128 visible ASCII characters, or auto for a random UUID printed on stderr; rerun the same command with the same key to get the first result instead of a second run (default: none, no idempotency) + --input string request JSON file path or - for stdin, maximum 1 MiB (default: use document flags; stdin requires --yes) + --output string output format: text or json (default: text; JSON is the full server result) (default "text") + --url string instance URL override, e.g. https://n8n.example.com (falls back to N8N_URL, then the selected context URL) + --workflow-id stringArray selected workflow ID, 1 to 36 characters; repeat for each ID (default: none; required unless --input is used) + --yes confirm content changes without prompting (default: prompt; required for non-interactive or stdin input) ``` ### SEE ALSO diff --git a/docs/n8n_promotion_project_changes.md b/docs/n8n_promotion_project_changes.md index 9f68569..fcbaeaa 100644 --- a/docs/n8n_promotion_project_changes.md +++ b/docs/n8n_promotion_project_changes.md @@ -9,8 +9,9 @@ Start with 'n8n project list' for the project ID. The project's own environment (n8n 2.46 and later) or connection (older) for the direction takes precedence over the instance one. Prepare the checkout first: 'n8n promotion environment connect' on 2.46, 'n8n promotion checkout clone' -before. Apply requires gitConnection:pull; promote requires -gitConnection:push. Text lists workflow IDs, statuses, and dependency +before. Apply requires promotions:apply; promote requires +promotions:promote (gitConnection:pull and gitConnection:push before +n8n 2.47). Text lists workflow IDs, statuses, and dependency counts; JSON includes changes, source (environmentId on 2.46, configId before), and nullable commitSha. On 2.46 a deleted or new promote row can be a workflow that moved between projects; promoting it is refused until diff --git a/docs/n8n_promotion_project_promote.md b/docs/n8n_promotion_project_promote.md index 795bf80..ce89c6e 100644 --- a/docs/n8n_promotion_project_promote.md +++ b/docs/n8n_promotion_project_promote.md @@ -13,7 +13,8 @@ workflows remain archived on the branch; workflows gone from the instance leave the branch. On 2.46 a workflow that moved into or out of the project since the branch was written is refused with 400; move it back first. Unknown deletions reject the whole request. Requires -gitConnection:push, plus variable:list when workflows use variables. +promotions:promote (gitConnection:push before n8n 2.47), plus +variable:list when workflows use variables. Commit message is optional; the server supplies a default. Force pushing is not supported. The result can name a review the Git host opened; advisory warnings go to stderr. diff --git a/docs/n8n_promotion_provider_branches.md b/docs/n8n_promotion_provider_branches.md index 8be69dc..1f44471 100644 --- a/docs/n8n_promotion_provider_branches.md +++ b/docs/n8n_promotion_provider_branches.md @@ -4,7 +4,8 @@ List branches of a GitLab repository ### Synopsis -Discover GitLab repositories or branches using a saved provider with gitConnection:discover. +Discover GitLab repositories or branches using a saved provider with promotions:discover +(gitConnection:discover before n8n 2.47). Start with 'n8n promotion provider list', then repositories, then branches. Pass the raw fullPath (for example org/repo) or GitLab project ID to branches; the CLI escapes it. Use remoteUrl from repositories as an environment remote diff --git a/docs/n8n_promotion_provider_create.md b/docs/n8n_promotion_provider_create.md index 83de40d..40038c8 100644 --- a/docs/n8n_promotion_provider_create.md +++ b/docs/n8n_promotion_provider_create.md @@ -23,8 +23,8 @@ gitlab), auth {"authType":"ssh-key"} with an optional keyType (ed25519 or rsa, default ed25519) or {"authType":"token", "password":"..."} plus username for git, and the optional config. Unknown fields and trailing JSON documents are refused before -transport. Requires gitConnection:create. Follow with 'n8n promotion -connection create'. +transport. Requires promotions:create (gitConnection:create before +n8n 2.47). Follow with 'n8n promotion connection create'. ``` n8n promotion provider create [flags] diff --git a/docs/n8n_promotion_provider_delete.md b/docs/n8n_promotion_provider_delete.md index 6b120ed..1735324 100644 --- a/docs/n8n_promotion_provider_delete.md +++ b/docs/n8n_promotion_provider_delete.md @@ -10,7 +10,8 @@ connection (older) cannot be deleted: the instance answers 409 and nothing changes, so delete or move those first. This cannot be undone. Interactive runs ask for confirmation; non-interactive runs require ---yes. Requires gitConnection:delete. +--yes. Requires promotions:delete (gitConnection:delete before n8n +2.47). ``` n8n promotion provider delete [flags] diff --git a/docs/n8n_promotion_provider_get.md b/docs/n8n_promotion_provider_get.md index 255809d..f520903 100644 --- a/docs/n8n_promotion_provider_get.md +++ b/docs/n8n_promotion_provider_get.md @@ -7,7 +7,7 @@ Show one promotion provider Show one promotion provider by ID. The response is the public provider document: name, type, auth type, configuration, and timestamps. Secrets are never returned. Find the ID with 'n8n promotion provider -list'. Requires gitConnection:read. +list'. Requires promotions:read (gitConnection:read before n8n 2.47). ``` n8n promotion provider get [flags] diff --git a/docs/n8n_promotion_provider_list.md b/docs/n8n_promotion_provider_list.md index f634efb..52ecc6a 100644 --- a/docs/n8n_promotion_provider_list.md +++ b/docs/n8n_promotion_provider_list.md @@ -9,7 +9,7 @@ cursor-paginated page at a time. Use --all to follow every cursor, capped at 10,000 providers. Use a returned ID with get, update, delete, and 'connection create'. -Requires gitConnection:list. +Requires promotions:list (gitConnection:list before n8n 2.47). With --all, JSON output adds a collection object. Its truncated field is true, and a warning goes to stderr, when the walk stopped at the 10,000-item limit diff --git a/docs/n8n_promotion_provider_repositories.md b/docs/n8n_promotion_provider_repositories.md index de611ec..7206d7c 100644 --- a/docs/n8n_promotion_provider_repositories.md +++ b/docs/n8n_promotion_provider_repositories.md @@ -4,7 +4,8 @@ List repositories available to a GitLab provider ### Synopsis -Discover GitLab repositories or branches using a saved provider with gitConnection:discover. +Discover GitLab repositories or branches using a saved provider with promotions:discover +(gitConnection:discover before n8n 2.47). Start with 'n8n promotion provider list', then repositories, then branches. Pass the raw fullPath (for example org/repo) or GitLab project ID to branches; the CLI escapes it. Use remoteUrl from repositories as an environment remote diff --git a/docs/n8n_promotion_provider_update.md b/docs/n8n_promotion_provider_update.md index 66ed2b7..3edab1b 100644 --- a/docs/n8n_promotion_provider_update.md +++ b/docs/n8n_promotion_provider_update.md @@ -17,7 +17,8 @@ later) or connection (older) that uses this provider, so interactive runs ask for confirmation and non-interactive runs require --yes. Credentials travel only as --input because secrets are never flags. A 409 means another request changed the provider first: reload it and -retry. Requires gitConnection:update. +retry. Requires promotions:update (gitConnection:update before n8n +2.47). ``` n8n promotion provider update [flags] diff --git a/docs/n8n_rate-limit.md b/docs/n8n_rate-limit.md new file mode 100644 index 0000000..72decbd --- /dev/null +++ b/docs/n8n_rate-limit.md @@ -0,0 +1,39 @@ +## n8n rate-limit + +Manage Public API rate limits + +### Synopsis + +Read or replace the Public API rate-limit settings: whether limiting is on, +and per-API-key read and write limits across all endpoints (global) and on +one endpoint, each with its own window in seconds. A limit of 0 means no +limit. Requests to these routes count against the limits too. + +Fields set by environment variables are listed in envManagedFields: they +report their effective value and cannot be changed through the API. +Requires securitySettings:manage and n8n 2.47 or later. + +``` +n8n rate-limit [flags] +``` + +### Examples + +``` + n8n rate-limit get + n8n rate-limit get --output json > rate-limits.json + n8n rate-limit set --input rate-limits.json --global-write-limit 60 +``` + +### Options + +``` + -h, --help help for rate-limit +``` + +### SEE ALSO + +* [n8n](n8n.md) - Command-line client for the n8n API +* [n8n rate-limit get](n8n_rate-limit_get.md) - Get Public API rate-limit settings +* [n8n rate-limit set](n8n_rate-limit_set.md) - Fully replace Public API rate-limit settings + diff --git a/docs/n8n_rate-limit_get.md b/docs/n8n_rate-limit_get.md new file mode 100644 index 0000000..c19a337 --- /dev/null +++ b/docs/n8n_rate-limit_get.md @@ -0,0 +1,37 @@ +## n8n rate-limit get + +Get Public API rate-limit settings + +### Synopsis + +Get the effective Public API rate-limit settings and the fields environment +variables manage. --output json is the starting point for 'set --input': it +round-trips, and set drops the read-only envManagedFields before sending. + +Requires securitySettings:manage and n8n 2.47 or later. + +``` +n8n rate-limit get [flags] +``` + +### Examples + +``` + n8n rate-limit get + n8n rate-limit get --output json + n8n rate-limit get --output json > rate-limits.json +``` + +### Options + +``` + --context string saved context name to use (falls back to N8N_CONTEXT, then the saved current context; see 'n8n config context list') + -h, --help help for get + --output string output format: text or json (JSON is the complete settings document with envManagedFields) (default "text") + --url string instance URL override, e.g. https://n8n.example.com (falls back to N8N_URL, then the selected context URL) +``` + +### SEE ALSO + +* [n8n rate-limit](n8n_rate-limit.md) - Manage Public API rate limits + diff --git a/docs/n8n_rate-limit_set.md b/docs/n8n_rate-limit_set.md new file mode 100644 index 0000000..f756f04 --- /dev/null +++ b/docs/n8n_rate-limit_set.md @@ -0,0 +1,62 @@ +## n8n rate-limit set + +Fully replace Public API rate-limit settings + +### Synopsis + +Fully replace the Public API rate-limit settings. This is a PUT, not a patch: +enabled and all eight limit and window fields are required. Take them from +--input (start from 'n8n rate-limit get --output json'), from flags, or both; +a flag overrides the --input value. Limits are request counts per API key, +at least 0 (0 for no limit); windows are seconds, at least 1. When limiting +is enabled, at least one limit must be above 0. + +envManagedFields in --input is read-only: it is dropped before sending and +reported on stderr. Fields set by environment variables can be repeated with +their current value but not changed; a different value answers 409 and +nothing changes. + +New limits apply at once to every API key, including the one this CLI uses, +so interactive runs ask for confirmation and non-interactive runs require +--yes. --input - also requires --yes because stdin cannot hold both JSON and +a confirmation answer. Requires securitySettings:manage and n8n 2.47 or later. + +``` +n8n rate-limit set [flags] +``` + +### Examples + +``` + n8n rate-limit get --output json > rate-limits.json + n8n rate-limit set --input rate-limits.json --global-write-limit 60 + n8n rate-limit set --input - --yes < rate-limits.json + n8n rate-limit set --enabled=false --global-read-limit 0 --global-read-window-seconds 60 \ + --global-write-limit 0 --global-write-window-seconds 60 --endpoint-read-limit 0 \ + --endpoint-read-window-seconds 60 --endpoint-write-limit 0 --endpoint-write-window-seconds 60 --yes +``` + +### Options + +``` + --context string saved context name to use (falls back to N8N_CONTEXT, then the saved current context; see 'n8n config context list') + --enabled turn Public API rate limiting on or off; true or false, overrides enabled in --input (default: the --input value) + --endpoint-read-limit int requests allowed per API key in the window, 0 for no limit; overrides endpointReadLimit in --input (default: the --input value) + --endpoint-read-window-seconds int window in seconds, at least 1; overrides endpointReadWindowSeconds in --input (default: the --input value) + --endpoint-write-limit int requests allowed per API key in the window, 0 for no limit; overrides endpointWriteLimit in --input (default: the --input value) + --endpoint-write-window-seconds int window in seconds, at least 1; overrides endpointWriteWindowSeconds in --input (default: the --input value) + --global-read-limit int requests allowed per API key in the window, 0 for no limit; overrides globalReadLimit in --input (default: the --input value) + --global-read-window-seconds int window in seconds, at least 1; overrides globalReadWindowSeconds in --input (default: the --input value) + --global-write-limit int requests allowed per API key in the window, 0 for no limit; overrides globalWriteLimit in --input (default: the --input value) + --global-write-window-seconds int window in seconds, at least 1; overrides globalWriteWindowSeconds in --input (default: the --input value) + -h, --help help for set + --input string full rate-limit settings JSON file path, or - for stdin, e.g. from 'n8n rate-limit get --output json' (default: none; flags supply every field; maximum 1 MiB) + --output string output format: text or json (JSON is the effective settings returned after replacement) (default "text") + --url string instance URL override, e.g. https://n8n.example.com (falls back to N8N_URL, then the selected context URL) + --yes confirm replacing the limits, which apply at once to every API key, without prompting (required when stdin is not interactive) +``` + +### SEE ALSO + +* [n8n rate-limit](n8n_rate-limit.md) - Manage Public API rate limits + diff --git a/internal/cli/cli.go b/internal/cli/cli.go index b1907e7..c850994 100644 --- a/internal/cli/cli.go +++ b/internal/cli/cli.go @@ -30,7 +30,8 @@ const ( // preflight: the result was printed and nothing was written. ExitPromotionBlocked = 3 // ExitPromotionSourceChanged is a promotion apply whose branch moved since - // the review: the result was printed and nothing was written. + // the review, or (n8n 2.47 and later) whose Apply preview changed: the + // result was printed and nothing was written. ExitPromotionSourceChanged = 4 ExitCanceled = 130 ) @@ -194,11 +195,28 @@ func report(w io.Writer, err error) int { return ExitCanceled default: fmt.Fprintf(w, "n8n: %v\n", err) + if n8n.IsRateLimited(err) { + fmt.Fprintln(w, rateLimitHint(err)) + } fmt.Fprintln(w, "Run 'n8n --help' for usage.") return ExitError } } +// rateLimitHint states the fix for a 429, whichever command produced it: wait +// for the window the server named, then retry. +func rateLimitHint(err error) string { + wait := "a moment" + if d, ok := n8n.RetryAfterOf(err); ok { + wait = d.String() + if d == 0 { + wait = "a moment" + } + } + return "The instance rate-limited this API key (429): wait " + wait + " and retry. " + + "An instance owner can view or change the Public API limits with 'n8n rate-limit get' and 'n8n rate-limit set' (n8n 2.47 and later)." +} + // NewRootCommand builds the root command and its subcommands. func NewRootCommand(opts Options) *cobra.Command { root := &cobra.Command{ @@ -272,6 +290,7 @@ func NewRootCommand(opts Options) *cobra.Command { newNodePolicyCommand(opts), newCredentialPolicyCommand(opts), newSecurityPolicyCommand(opts), + newRateLimitCommand(opts), newOtelCommand(opts), newLogStreamCommand(opts), newLDAPCommand(opts), diff --git a/internal/cli/help_test.go b/internal/cli/help_test.go index eb30b83..42ba2f2 100644 --- a/internal/cli/help_test.go +++ b/internal/cli/help_test.go @@ -214,6 +214,9 @@ func TestHelpSucceedsAtEveryLevel(t *testing.T) { {"security-policy"}, {"security-policy", "get"}, {"security-policy", "set"}, + {"rate-limit"}, + {"rate-limit", "get"}, + {"rate-limit", "set"}, {"otel"}, {"otel", "get"}, {"otel", "set"}, @@ -291,6 +294,7 @@ func TestHelpSucceedsAtEveryLevel(t *testing.T) { {"promotion", "environment", "apply"}, {"promotion", "environment", "apply-continue"}, {"promotion", "environment", "promote"}, + {"promotion", "environment", "missing-projects"}, {"promotion", "connection"}, {"promotion", "connection", "list"}, {"promotion", "connection", "create"}, diff --git a/internal/cli/idempotency_test.go b/internal/cli/idempotency_test.go index abf7cc7..89dbb19 100644 --- a/internal/cli/idempotency_test.go +++ b/internal/cli/idempotency_test.go @@ -47,7 +47,7 @@ func idempotentCommands() []idempotentCommand { {"environment apply", fixed("promotion", "environment", "apply", cliEnvironmentID, "--yes"), n8n.PromotionEnvironmentsPath + "/" + cliEnvironmentID + "/apply", applied}, {"environment apply-continue", fixed(append([]string{"promotion", "environment", "apply-continue", cliEnvironmentID, "--yes"}, envExpectedFlags()...)...), n8n.PromotionEnvironmentsPath + "/" + cliEnvironmentID + "/apply/continue", applied}, {"package import", func(t *testing.T) []string { - return []string{"package", "import", "--file", writePackageArchive(t, cliPackageArchive), "--workflow-conflict-policy", "fail", "--yes"} + return []string{"package", "import", "--file", writePackageArchive(t, cliPackageArchive), "--conflict-policy", "fail", "--yes"} }, n8n.N8nPackageImportPath, cliPackageImportResult}, {"package import-selection", func(t *testing.T) []string { return []string{"package", "import-selection", "--file", writePackageArchive(t, cliPackageArchive), "--project-id", "p1", "--workflow-id", "wf-1", "--yes"} diff --git a/internal/cli/n8n_package.go b/internal/cli/n8n_package.go index de2dca8..ead3fde 100644 --- a/internal/cli/n8n_package.go +++ b/internal/cli/n8n_package.go @@ -4,6 +4,7 @@ import ( "bytes" "context" "encoding/json" + "errors" "fmt" "io" "maps" @@ -64,6 +65,48 @@ const ( packageLegacyVersionPolicyFlag = "workflow-version-policy" ) +// Import policy flags n8n 2.47 renamed when the policies grew to cover +// Agents. The old names stay as deprecated aliases. +const ( + packageConflictPolicyFlag = "conflict-policy" + packageIDPolicyFlag = "id-policy" + packagePublishingPolicyFlag = "publishing-policy" + packageLegacyConflictPolicyFlag = "workflow-conflict-policy" + packageLegacyIDPolicyFlag = "workflow-id-policy" + packageLegacyPublishingPolicyFlag = "workflow-publishing-policy" +) + +// aliasedFlag pairs a flag with its deprecated alias. Each has its own +// variable, so a conflicting pair can be told apart from a repeated value. +type aliasedFlag struct { + name, legacy string + value, legacyValue *string +} + +// registerAliasedFlag registers name and its deprecated alias legacy with +// the same default. +func registerAliasedFlag(cmd *cobra.Command, name, legacy string, value, legacyValue *string, def, usage string) { + cmd.Flags().StringVar(value, name, def, usage) + cmd.Flags().StringVar(legacyValue, legacy, def, "deprecated alias of --"+name+", same values") + _ = cmd.Flags().MarkDeprecated(legacy, "use --"+name) +} + +// resolveAliasedFlags copies a deprecated alias into its flag when only the +// alias was set, and refuses the pair when both were set to different values. +func resolveAliasedFlags(cmd *cobra.Command, flags ...aliasedFlag) error { + for _, flag := range flags { + current, legacy := cmd.Flags().Changed(flag.name), cmd.Flags().Changed(flag.legacy) + switch { + case current && legacy && strings.TrimSpace(*flag.value) != strings.TrimSpace(*flag.legacyValue): + return fmt.Errorf("--%s %q and its deprecated alias --%s %q disagree: pass only --%s", + flag.name, *flag.value, flag.legacy, *flag.legacyValue, flag.name) + case legacy && !current: + *flag.value = *flag.legacyValue + } + } + return nil +} + type packageExportFlags struct { instance instanceFlags agentIDs []string @@ -367,10 +410,13 @@ type packageImportFlags struct { credentialMissing string credentialConflict string bindings string - workflowConflict string - workflowIDPolicy string + conflictPolicy string + idPolicy string missingNodeMode string publishingPolicy string + legacyConflict string + legacyIDPolicy string + legacyPublishing string projectConflict string folderConflict string deletionPolicy string @@ -392,15 +438,24 @@ func newPackageImportCommand(opts Options) *cobra.Command { cmd := &cobra.Command{ Use: "import", Short: "Import an n8n package into a project (beta)", - Long: "Import a gzip-compressed tar package (.n8np) into the target project.\n" + - "Send the archive with --file FILE or --file - for stdin, route it with\n" + - "--project-id and --folder-id (omit both for the caller's personal project\n" + - "root), and state --workflow-conflict-policy explicitly: new-version\n" + - "updates matching workflows, fail rejects the import when any matches, and\n" + - "skip leaves matching workflows unchanged.\n\n" + + Long: "Import a gzip-compressed tar package (.n8np) into the target project:\n" + + "Agent-only, workflow-only, mixed, or whole-project packages (Agents need\n" + + "the Agents module). Send the archive with --file FILE or --file - for\n" + + "stdin, route it with --project-id and --folder-id (omit both for the\n" + + "caller's personal project root), and state --conflict-policy explicitly:\n" + + "new-version replaces matching Agents and workflows (and saves a changed\n" + + "skill of an imported Agent as a new version, which every Agent following\n" + + "that skill picks up), fail rejects the import when any matches, and skip\n" + + "leaves them unchanged.\n\n" + + "n8n 2.47 renamed the workflow-only policies to --conflict-policy,\n" + + "--id-policy, and --publishing-policy, which cover Agents and workflows;\n" + + "the old --workflow-* flags remain as deprecated aliases. Older instances\n" + + "get the old field names automatically, which needs --file PATH: stdin\n" + + "cannot be sent twice.\n\n" + "Beta: breaking changes may still occur without a major version bump.\n" + - "This mutates the instance: imported workflows arrive per\n" + - "--workflow-publishing-policy, new-version follows the package archive\n" + + "This mutates the instance: imported Agents and workflows arrive per\n" + + "--publishing-policy (a failed publication keeps the imported definition\n" + + "and is reported per entity), new-version follows the package archive\n" + "state (archiving needs workflow:delete), folder overwrite can remove\n" + "workflows the package does not contain (archive is recoverable,\n" + "hard-delete also drops executions permanently, so prefer archive),\n" + @@ -414,21 +469,35 @@ func newPackageImportCommand(opts Options) *cobra.Command { "--yes; --file - also requires --yes because stdin cannot answer.\n" + "Credentials created from incomplete package data are reported on\n" + "stderr and keep their workflows unpublished until completed. When the\n" + - "import is blocked (409 or 422), each issue is listed on stderr. Needs\n" + - "workflow:import plus, depending on the package and the policies,\n" + - "credential, variable, tag, data-table, folder, and delete scopes, and\n" + - "the Packages, Variables, and Folders features where the contents\n" + - "require them.\n\n" + + "import is blocked (409 or 422), each issue is listed on stderr, and\n" + + "Agent channels that need setup are listed with their setup URL. Needs\n" + + "workflow:import for workflows and agent:import plus agent:read for\n" + + "Agents (both for mixed packages; agent:create, agent:update,\n" + + "agent:publish, or agent:unpublish for the planned Agent actions),\n" + + "workflow:activate or workflow:deactivate when publication changes, plus,\n" + + "depending on the package and the policies, credential, variable, tag,\n" + + "data-table, folder, skill, and delete scopes, and the Packages,\n" + + "Variables, and Folders features where the contents require them.\n\n" + idempotencyHelp + " A retry must send\n" + "the same archive under the same file name with the same flags.", - Example: " n8n package import --file workflows.n8np --workflow-conflict-policy new-version --yes\n" + - " n8n package import --file project.n8np --workflow-conflict-policy fail --project-id Ox8O54VQrmBrb4qL --yes --output json\n" + - " n8n package import --file update.n8np --workflow-conflict-policy skip --workflow-publishing-policy publish-all --yes", + Example: " n8n package import --file workflows.n8np --conflict-policy new-version --yes\n" + + " n8n package import --file project.n8np --conflict-policy fail --project-id Ox8O54VQrmBrb4qL --yes --output json\n" + + " n8n package import --file agent.n8np --conflict-policy skip --publishing-policy match-source --yes", Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, _ []string) error { + if err := resolveAliasedFlags(cmd, + aliasedFlag{packageConflictPolicyFlag, packageLegacyConflictPolicyFlag, &f.conflictPolicy, &f.legacyConflict}, + aliasedFlag{packageIDPolicyFlag, packageLegacyIDPolicyFlag, &f.idPolicy, &f.legacyIDPolicy}, + aliasedFlag{packagePublishingPolicyFlag, packageLegacyPublishingPolicyFlag, &f.publishingPolicy, &f.legacyPublishing}, + ); err != nil { + return err + } return runPackageImport(cmd.Context(), opts, f) }, } + // Deprecation notices go to the flag set output; cobra would otherwise + // print them on stdout, which carries the import result. + cmd.Flags().SetOutput(opts.Streams.Err) f.instance.register(cmd) cmd.Flags().StringVar(&f.file, "file", "", "package archive (.n8np) to import: a file path, or - for stdin (required; stdin requires --yes)") cmd.Flags().StringVar(&f.projectID, "project-id", "", "target project ID, from 'n8n project list' (default: the caller's personal project)") @@ -437,10 +506,13 @@ func newPackageImportCommand(opts Options) *cobra.Command { cmd.Flags().StringVar(&f.credentialMissing, "credential-missing-mode", "", "unresolvable credential handling: must-preexist rejects, create-stub creates empty placeholders, create-with-values seeds them from the package's expression values (needs credential:create; unconfirmed data lands in credentials.incomplete and blocks publishing) (default: server default create-stub)") cmd.Flags().StringVar(&f.credentialConflict, "credential-conflict-policy", "", "matched credential whose package values differ: keep-existing never changes it, overwrite writes the package name and expression values to credentials a project of the import owns (keeps secrets, other fields, and OAuth connections; reported in credentials.updated), fail rejects the import with a 409 credential-conflict; overwrite and fail need credential:update on matched credentials (default: server default keep-existing)") cmd.Flags().StringVar(&f.bindings, "bindings", "", "explicit credential bindings as JSON, e.g. '{\"credentials\":{\"pkg-id\":\"target-id\"}}' (default: server default {})") - cmd.Flags().StringVar(&f.workflowConflict, "workflow-conflict-policy", "", "matching workflow handling, required: new-version, fail, or skip") - cmd.Flags().StringVar(&f.workflowIDPolicy, "workflow-id-policy", n8n.ImportWorkflowIDSource, "ID for newly created workflows, always sent: source reuses the package ID for promotions, new mints a fresh ID for repeat imports (default: source)") + registerAliasedFlag(cmd, packageConflictPolicyFlag, packageLegacyConflictPolicyFlag, &f.conflictPolicy, &f.legacyConflict, "", + "matching Agent and workflow handling, required: new-version, fail, or skip (before n8n 2.47 workflows only)") + registerAliasedFlag(cmd, packageIDPolicyFlag, packageLegacyIDPolicyFlag, &f.idPolicy, &f.legacyIDPolicy, n8n.ImportIDSource, + "ID for newly created Agents and workflows, always sent: source reuses the package ID; new mints a fresh ID but only instances before n8n 2.47 accept it (default: source)") cmd.Flags().StringVar(&f.missingNodeMode, "missing-node-type-mode", "", "unknown node type handling: fail rejects before anything is written, import-anyway imports without publishing those workflows (default: server default fail)") - cmd.Flags().StringVar(&f.publishingPolicy, "workflow-publishing-policy", "", "post-import publishing: preserve-published-state, match-source, publish-all, or unpublish-all (default: server default preserve-published-state)") + registerAliasedFlag(cmd, packagePublishingPolicyFlag, packageLegacyPublishingPolicyFlag, &f.publishingPolicy, &f.legacyPublishing, "", + "post-import publishing of Agents and workflows: preserve-published-state, match-source, publish-all, or unpublish-all (default: server default preserve-published-state)") cmd.Flags().StringVar(&f.projectConflict, "project-conflict-policy", "", "existing project handling for project packages: merge, fail, or overwrite (default: server default merge)") cmd.Flags().StringVar(&f.folderConflict, "folder-conflict-policy", "", "existing folder handling: merge, fail, or overwrite; empty follows --project-conflict-policy on project packages, merge otherwise (default: follow)") cmd.Flags().StringVar(&f.deletionPolicy, "overwrite-deletion-policy", "", "how folder overwrite removes missing workflows: archive (recoverable) or hard-delete (also drops executions; prefer archive) (default: server default archive)") @@ -469,27 +541,27 @@ func runPackageImport(ctx context.Context, opts Options, f packageImportFlags) e return fmt.Errorf("--file - consumes stdin and cannot answer the import confirmation: pass --yes after reviewing the package and policies") } request := n8n.ImportPackageRequest{ - ProjectID: strings.TrimSpace(f.projectID), - FolderID: strings.TrimSpace(f.folderID), - CredentialMatchingMode: strings.TrimSpace(f.credentialMatching), - CredentialMissingMode: strings.TrimSpace(f.credentialMissing), - CredentialConflict: strings.TrimSpace(f.credentialConflict), - Bindings: strings.TrimSpace(f.bindings), - WorkflowConflictPolicy: strings.TrimSpace(f.workflowConflict), - WorkflowIDPolicy: strings.TrimSpace(f.workflowIDPolicy), - MissingNodeTypeMode: strings.TrimSpace(f.missingNodeMode), - WorkflowPublishingPolicy: strings.TrimSpace(f.publishingPolicy), - ProjectConflictPolicy: strings.TrimSpace(f.projectConflict), - FolderConflictPolicy: strings.TrimSpace(f.folderConflict), - OverwriteDeletionPolicy: strings.TrimSpace(f.deletionPolicy), - DataTableMatchingMode: strings.TrimSpace(f.dataTableMatching), - DataTableMissingMode: strings.TrimSpace(f.dataTableMissing), - DataTableSchemaConflict: strings.TrimSpace(f.dataTableSchema), - VariableMissingMode: strings.TrimSpace(f.variableMissing), - VariableConflictPolicy: strings.TrimSpace(f.variableConflict), - VariableParentPolicy: strings.TrimSpace(f.variableParent), - TagMissingMode: strings.TrimSpace(f.tagMissing), - TagConflictPolicy: strings.TrimSpace(f.tagConflict), + ProjectID: strings.TrimSpace(f.projectID), + FolderID: strings.TrimSpace(f.folderID), + CredentialMatchingMode: strings.TrimSpace(f.credentialMatching), + CredentialMissingMode: strings.TrimSpace(f.credentialMissing), + CredentialConflict: strings.TrimSpace(f.credentialConflict), + Bindings: strings.TrimSpace(f.bindings), + ConflictPolicy: strings.TrimSpace(f.conflictPolicy), + IDPolicy: strings.TrimSpace(f.idPolicy), + MissingNodeTypeMode: strings.TrimSpace(f.missingNodeMode), + PublishingPolicy: strings.TrimSpace(f.publishingPolicy), + ProjectConflictPolicy: strings.TrimSpace(f.projectConflict), + FolderConflictPolicy: strings.TrimSpace(f.folderConflict), + OverwriteDeletionPolicy: strings.TrimSpace(f.deletionPolicy), + DataTableMatchingMode: strings.TrimSpace(f.dataTableMatching), + DataTableMissingMode: strings.TrimSpace(f.dataTableMissing), + DataTableSchemaConflict: strings.TrimSpace(f.dataTableSchema), + VariableMissingMode: strings.TrimSpace(f.variableMissing), + VariableConflictPolicy: strings.TrimSpace(f.variableConflict), + VariableParentPolicy: strings.TrimSpace(f.variableParent), + TagMissingMode: strings.TrimSpace(f.tagMissing), + TagConflictPolicy: strings.TrimSpace(f.tagConflict), } if err := request.Validate(); err != nil { return err @@ -515,7 +587,7 @@ func runPackageImport(ctx context.Context, opts Options, f packageImportFlags) e return refused } writeImportIssues(opts.Streams.Err, err) - return packageAPIError(err, resolution, "import", allOf("workflow:import")) + return packageAPIError(err, resolution, "import", anyOf("workflow:import", "agent:import")) } if f.output == outputJSON { return writeJSON(opts.Streams.Out, result) @@ -546,8 +618,8 @@ func packageImportQuestion(f packageImportFlags, resolution config.Resolution) s case strings.TrimSpace(f.folderID) != "": target = fmt.Sprintf("folder %q", strings.TrimSpace(f.folderID)) } - question := fmt.Sprintf("Import package %q into %s on %s? Matching workflows use %q and new workflows take %q IDs.", - displayPackageName(f.file), target, resolution.URL, conflictOrUnset(f.workflowConflict), idPolicyOrUnset(f.workflowIDPolicy)) + question := fmt.Sprintf("Import package %q into %s on %s? Matching Agents and workflows use %q and new ones take %q IDs.", + displayPackageName(f.file), target, resolution.URL, conflictOrUnset(f.conflictPolicy), idPolicyOrUnset(f.idPolicy)) if strings.TrimSpace(f.publishingPolicy) != "" { question += fmt.Sprintf(" Publishing uses %q.", strings.TrimSpace(f.publishingPolicy)) } @@ -609,6 +681,11 @@ func writePackageImportText(opts Options, resolution config.Resolution, result * skipped++ } } + if len(result.Agents) > 0 || result.Counts != nil { + agents := agentCounts(result) + fmt.Fprintf(tw, "Agents:\t%d (%d created, %d updated, %d skipped)\n", + max(len(result.Agents), agents.Created+agents.Updated+agents.Skipped), agents.Created, agents.Updated, agents.Skipped) + } fmt.Fprintf(tw, "Imported:\t%d workflows (%d created, %d updated, %d skipped)\n", len(result.Workflows), created, updated, skipped) fmt.Fprintf(tw, "Removed:\t%d workflows, %d folders\n", len(result.RemovedWorkflows), len(result.RemovedFolders)) fmt.Fprintf(tw, "Shells:\t%d folders, %d projects\n", len(result.Folders), len(result.Projects)) @@ -620,6 +697,14 @@ func writePackageImportText(opts Options, resolution config.Resolution, result * fmt.Fprintf(tw, "Tags:\t%d matched, %d created, %d renamed, %d reconciled, %d skipped\n", len(result.Tags.Matched), len(result.Tags.Created), len(result.Tags.Renamed), len(result.Tags.Reconciled), len(result.Tags.Skipped)) fmt.Fprintf(tw, "Instance:\t%s\n", resolution.URL) + if len(result.Agents) > 0 { + fmt.Fprintln(tw, "\nSOURCE AGENT\tLOCAL ID\tNAME\tSTATUS\tPUBLISHING") + for _, agent := range result.Agents { + fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\n", + emptyDash(agent.SourceAgentID), emptyDash(agent.LocalID), + emptyDash(agent.Name), emptyDash(agent.Status), emptyDash(agent.Publishing.State)) + } + } if len(result.Workflows) > 0 { fmt.Fprintln(tw, "\nSOURCE WORKFLOW\tLOCAL ID\tNAME\tSTATUS") for _, workflow := range result.Workflows { @@ -631,6 +716,7 @@ func writePackageImportText(opts Options, resolution config.Resolution, result * if err := tw.Flush(); err != nil { return err } + writeImportPublishingHints(opts.Streams.Err, result) if len(result.Credentials.Incomplete) > 0 { fmt.Fprintf(opts.Streams.Err, "%d credential(s) created from package data that may be incomplete (%s): workflows using them stay unpublished until you complete each with 'n8n credential update '; see credentials.incomplete in --output json.\n", len(result.Credentials.Incomplete), strings.Join(targetCredentialIDs(result, result.Credentials.Incomplete), ", ")) @@ -657,6 +743,56 @@ func writePackageImportText(opts Options, resolution config.Resolution, result * return nil } +// agentCounts prefers the server's totals (counts.agents) and falls back to +// counting the agents list. +func agentCounts(result *n8n.ImportPackageResult) n8n.ImportEntityCounts { + if result.Counts != nil { + return result.Counts.Agents + } + var counts n8n.ImportEntityCounts + for _, agent := range result.Agents { + switch agent.Status { + case "created": + counts.Created++ + case "updated": + counts.Updated++ + default: + counts.Skipped++ + } + } + return counts +} + +// writeImportPublishingHints lists Agent channels that need setup and +// counts Agents and workflows whose publication was blocked or failed. The +// definitions were imported either way. +func writeImportPublishingHints(w io.Writer, result *n8n.ImportPackageResult) { + unpublished := 0 + for _, agent := range result.Agents { + for _, channel := range agent.Channels { + if channel.Status != n8n.ImportChannelSetupRequired { + continue + } + fmt.Fprintf(w, "Agent %q (%s): %s channel needs setup (%s)", agent.Name, emptyDash(agent.LocalID), emptyDash(channel.Type), emptyDash(channel.Reason)) + if channel.SetupURL != "" { + fmt.Fprintf(w, ": open %s", channel.SetupURL) + } + fmt.Fprintln(w) + } + if state := agent.Publishing.State; state == n8n.ImportPublishingBlocked || state == n8n.ImportPublishingFailed { + unpublished++ + } + } + for _, workflow := range result.Workflows { + if state := workflow.Publishing.State; state == n8n.ImportPublishingBlocked || state == n8n.ImportPublishingFailed { + unpublished++ + } + } + if unpublished > 0 { + fmt.Fprintf(w, "%d Agent(s) or workflow(s) were imported but not published (blocked or failed): see publishing.state and its reason in --output json, fix the cause, then publish them.\n", unpublished) + } +} + // targetCredentialIDs maps source credential IDs to their IDs on this // instance, keeping the source ID when no binding names one. func targetCredentialIDs(result *n8n.ImportPackageResult, sources []string) []string { @@ -685,17 +821,19 @@ func writeImportIssues(w io.Writer, err error) { } type packageImportSelectionFlags struct { - instance instanceFlags - file string - projectID string - workflowIDs []string - deletedIDs []string - workflowConflict string - workflowIDPolicy string - deletionPolicy string - yes bool - output string - idempotency idempotencyFlag + instance instanceFlags + file string + projectID string + workflowIDs []string + deletedIDs []string + conflictPolicy string + idPolicy string + legacyConflict string + legacyIDPolicy string + deletionPolicy string + yes bool + output string + idempotency idempotencyFlag } func newPackageImportSelectionCommand(opts Options) *cobra.Command { @@ -719,33 +857,50 @@ func newPackageImportSelectionCommand(opts Options) *cobra.Command { "for a delete-only run. Selected IDs from another project are dropped,\n" + "absent delete IDs are a no-op, and an ID cannot be both imported and\n" + "deleted. Folder, tag, and project policies are fixed by the server; only\n" + - "the workflow conflict, workflow ID, and deletion policies are settable.\n" + - "A workflow package is rejected with a 400: export a project package with\n" + - "'n8n package export --project-id'.\n\n" + + "the conflict, ID, and deletion policies are settable, and publication\n" + + "follows match-source. A workflow package is rejected with a 400: export a\n" + + "project package with 'n8n package export --project-id'. Packages that\n" + + "contain Agents are rejected before writes on n8n 2.47 and later: import\n" + + "selected-Agent exports with 'n8n package import'. n8n 2.47 renamed\n" + + "--workflow-conflict-policy and --workflow-id-policy to --conflict-policy\n" + + "and --id-policy (the old flags remain as deprecated aliases); older\n" + + "instances get the old field names automatically, which needs --file\n" + + "PATH because stdin cannot be sent twice.\n\n" + "Beta: breaking changes may still occur without a major version bump.\n" + "This mutates the instance, so interactive runs ask for confirmation and\n" + "non-interactive runs require --yes; --file - also requires --yes because\n" + "stdin cannot answer. Needs workflow:import, plus workflow:delete when\n" + - "deleting or when an update changes a workflow's archive state, and the\n" + - "licensed Packages feature. Output is the same import result as\n" + + "deleting or when an update changes a workflow's archive state,\n" + + "workflow:activate or workflow:deactivate when match-source changes\n" + + "publication, and the licensed Packages feature. Output is the same\n" + + "import result as\n" + "'n8n package import'.\n\n" + idempotencyHelp + " A retry must send\n" + "the same archive under the same file name with the same flags.", Example: " n8n package import-selection --file project.n8np --project-id Ox8O54VQrmBrb4qL --workflow-id 2tUt1wbLX592XDdX --workflow-id 7pQr3sTuVwXyZaBc --yes\n" + - " n8n package import-selection --file project.n8np --project-id Ox8O54VQrmBrb4qL --workflow-id 2tUt1wbLX592XDdX --delete-workflow-id 9xKp2mNqRzAbCdEf --workflow-conflict-policy fail --output json --yes\n" + + " n8n package import-selection --file project.n8np --project-id Ox8O54VQrmBrb4qL --workflow-id 2tUt1wbLX592XDdX --delete-workflow-id 9xKp2mNqRzAbCdEf --conflict-policy fail --output json --yes\n" + " n8n package import-selection --file project.n8np --project-id Ox8O54VQrmBrb4qL --delete-workflow-id 9xKp2mNqRzAbCdEf --overwrite-deletion-policy hard-delete", Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, _ []string) error { + if err := resolveAliasedFlags(cmd, + aliasedFlag{packageConflictPolicyFlag, packageLegacyConflictPolicyFlag, &f.conflictPolicy, &f.legacyConflict}, + aliasedFlag{packageIDPolicyFlag, packageLegacyIDPolicyFlag, &f.idPolicy, &f.legacyIDPolicy}, + ); err != nil { + return err + } return runPackageImportSelection(cmd.Context(), opts, f) }, } + cmd.Flags().SetOutput(opts.Streams.Err) f.instance.register(cmd) cmd.Flags().StringVar(&f.file, "file", "", "project package archive (.n8np) to import from: a file path, or - for stdin (required; stdin requires --yes)") cmd.Flags().StringVar(&f.projectID, "project-id", "", "source project ID as it appears in the package; also the target project ID, created if missing (required)") cmd.Flags().StringArrayVar(&f.workflowIDs, "workflow-id", nil, "source workflow ID to import from --project-id, repeatable (default: none, for a delete-only run with --delete-workflow-id)") cmd.Flags().StringArrayVar(&f.deletedIDs, "delete-workflow-id", nil, "destination workflow ID to remove from the target project, repeatable; needs workflow:delete and must not match a --workflow-id (default: none)") - cmd.Flags().StringVar(&f.workflowConflict, "workflow-conflict-policy", "", "selected workflow that already exists in the target project: new-version updates it, fail rejects the import, skip leaves it unchanged (default: server default new-version)") - cmd.Flags().StringVar(&f.workflowIDPolicy, "workflow-id-policy", n8n.ImportWorkflowIDSource, "ID for newly created workflows, always sent: source reuses the package ID, new mints a fresh ID (default: source)") + registerAliasedFlag(cmd, packageConflictPolicyFlag, packageLegacyConflictPolicyFlag, &f.conflictPolicy, &f.legacyConflict, "", + "selected workflow that already exists in the target project: new-version updates it, fail rejects the import, skip leaves it unchanged (default: server default new-version)") + registerAliasedFlag(cmd, packageIDPolicyFlag, packageLegacyIDPolicyFlag, &f.idPolicy, &f.legacyIDPolicy, n8n.ImportIDSource, + "ID for newly created workflows, always sent: source reuses the package ID; new mints a fresh ID but only instances before n8n 2.47 accept it (default: source)") cmd.Flags().StringVar(&f.deletionPolicy, "overwrite-deletion-policy", "", "how --delete-workflow-id removes workflows: archive (recoverable) or hard-delete (also drops executions permanently; prefer archive); needs --delete-workflow-id (default: server default archive)") cmd.Flags().BoolVar(&f.yes, "yes", false, "confirm importing and deleting the listed workflows without prompting (required when stdin is not interactive)") cmd.Flags().StringVar(&f.output, "output", outputText, "output format: text or json (JSON is the full import result)") @@ -773,8 +928,8 @@ func runPackageImportSelection(ctx context.Context, opts Options, f packageImpor ProjectID: strings.TrimSpace(f.projectID), WorkflowIDs: trimmedIDs(f.workflowIDs), DeletedWorkflowIDs: trimmedIDs(f.deletedIDs), - WorkflowConflictPolicy: strings.TrimSpace(f.workflowConflict), - WorkflowIDPolicy: strings.TrimSpace(f.workflowIDPolicy), + ConflictPolicy: strings.TrimSpace(f.conflictPolicy), + IDPolicy: strings.TrimSpace(f.idPolicy), OverwriteDeletionPolicy: strings.TrimSpace(f.deletionPolicy), } if err := request.Validate(); err != nil { @@ -830,11 +985,11 @@ func packageImportSelectionQuestion(file string, request n8n.ImportPackageSelect question := fmt.Sprintf("Import %d workflow(s) from source project %q of package %q into project %q on %s (the instance project with the same ID, created if missing)?", len(request.WorkflowIDs), request.ProjectID, displayPackageName(file), request.ProjectID, resolution.URL) if len(request.WorkflowIDs) > 0 { - conflict := request.WorkflowConflictPolicy + conflict := request.ConflictPolicy if conflict == "" { - conflict = n8n.ImportWorkflowConflictNewVersion + " (server default)" + conflict = n8n.ImportConflictNewVersion + " (server default)" } - question += fmt.Sprintf(" Existing workflows use %q and new workflows take %q IDs.", conflict, request.WorkflowIDPolicy) + question += fmt.Sprintf(" Existing workflows use %q and new workflows take %q IDs.", conflict, request.IDPolicy) } switch { case len(request.DeletedWorkflowIDs) == 0: @@ -852,15 +1007,21 @@ func packageImportSelectionQuestion(file string, request n8n.ImportPackageSelect // packageAPIError restates the fix for a failed export or import. need is the // scope requirement reported on a 403. func packageAPIError(err error, resolution config.Resolution, action string, need scopeNeed) error { + if errors.Is(err, n8n.ErrImportArchiveNotRewindable) { + return fmt.Errorf("%s predates n8n 2.47 and needs the package %s resent with the older workflow-prefixed policy fields, but stdin cannot be sent twice; nothing was written: pass the archive with --file PATH instead of --file -: %w", resolution.URL, action, err) + } + if apiErr, ok := errors.AsType[*n8n.APIError](err); ok && apiErr.StatusCode == http.StatusBadRequest && slices.Contains(apiErr.Fields, "idPolicy") && action != "export" { + return fmt.Errorf("%s rejected the package %s (400): n8n 2.47 and later accept only --id-policy source (new works only on older instances), so drop --id-policy or pass source: %w", resolution.URL, action, err) + } if blocked, ok := n8n.AsImportBlocked(err); ok && action == "import-selection" { if blocked.StatusCode == http.StatusConflict { - return fmt.Errorf("%s rejected the selection import (409): %d conflict issue(s) and nothing was written; a workflow-removal-conflict means a --delete-workflow-id matches a selected workflow's destination, so drop it from one list, and a workflow conflict under fail needs --workflow-conflict-policy new-version or skip: %w", resolution.URL, len(blocked.Issues), err) + return fmt.Errorf("%s rejected the selection import (409): %d conflict issue(s) and nothing was written; a workflow-removal-conflict means a --delete-workflow-id matches a selected workflow's destination, so drop it from one list, and a workflow conflict under fail needs --conflict-policy new-version or skip: %w", resolution.URL, len(blocked.Issues), err) } return fmt.Errorf("%s rejected the selection import (422): %d blocking issue(s); workflow-removal-forbidden needs the workflow:delete scope, and unresolved credentials or unknown node types must exist on this instance first, then retry: %w", resolution.URL, len(blocked.Issues), err) } if blocked, ok := n8n.AsImportBlocked(err); ok && action == "import" { if blocked.StatusCode == http.StatusConflict { - return fmt.Errorf("%s rejected the package import (409): %d conflict issue(s); nothing matched with fail stays unchanged, so adjust a conflict policy such as --workflow-conflict-policy, --project-conflict-policy, --folder-conflict-policy, --tag-conflict-policy, --variable-conflict-policy, or --credential-conflict-policy and retry: %w", resolution.URL, len(blocked.Issues), err) + return fmt.Errorf("%s rejected the package import (409): %d conflict issue(s); nothing matched with fail stays unchanged, so adjust a conflict policy such as --conflict-policy, --project-conflict-policy, --folder-conflict-policy, --tag-conflict-policy, --variable-conflict-policy, or --credential-conflict-policy and retry: %w", resolution.URL, len(blocked.Issues), err) } return fmt.Errorf("%s rejected the package import (422): %d blocking issue(s) such as unresolved credentials or variables, unknown node types, or variable quota; create the missing references, pass --credential-missing-mode, --missing-node-type-mode import-anyway, or a variable mode that creates them (credential-update-forbidden needs credential:update on the matched credential, or --credential-conflict-policy keep-existing), and retry: %w", resolution.URL, len(blocked.Issues), err) } @@ -883,7 +1044,7 @@ func packageAPIError(err error, resolution config.Resolution, action string, nee "workflow:delete is also needed when an update changes a workflow's archive state, and the instance needs the licensed Packages feature.", packageResource) } return forbiddenScopeError(err, resolution, "package import", need, - "the import also needs the credential (credential:create for create-with-values, credential:update for --credential-conflict-policy overwrite or fail), variable, tag, data-table (dataTable:update for schema overwrite), folder and delete scopes the package and policies require, and the instance needs the licensed Packages feature.", packageResource) + "workflow packages need workflow:import, Agent packages agent:import and agent:read (plus agent:create, agent:update, agent:publish, or agent:unpublish for the planned Agent actions), and mixed packages both; publication changes need workflow:activate or workflow:deactivate, and the import also needs the credential (credential:create for create-with-values, credential:update for --credential-conflict-policy overwrite or fail), variable, tag, data-table (dataTable:update for schema overwrite), folder, skill, and delete scopes the package and policies require, and the instance needs the licensed Packages feature.", packageResource) case n8n.IsNotFound(err): return fmt.Errorf("%s does not serve n8n packages (404): it needs the licensed Packages feature; run %s to see what this instance offers: %w", resolution.URL, discoverHint(packageResource), err) diff --git a/internal/cli/n8n_package_247_test.go b/internal/cli/n8n_package_247_test.go new file mode 100644 index 0000000..bfcdd59 --- /dev/null +++ b/internal/cli/n8n_package_247_test.go @@ -0,0 +1,175 @@ +package cli + +import ( + "bytes" + "encoding/json" + "fmt" + "net/http" + "strings" + "testing" + "time" + + "github.com/SomeoneWithOptions/n8n-cli/internal/config" + "github.com/SomeoneWithOptions/n8n-cli/internal/n8n" +) + +const cliPackageImportAgentsResult = `{ + "package":{"sourceN8nVersion":"2.47.3","sourceId":"pkg-4"}, + "agents":[ + {"sourceAgentId":"ag-src","localId":"ag-local","name":"Helper","projectId":"p1","activeVersionId":null,"status":"created", + "publishing":{"state":"blocked","blockedReason":"channel-setup-required"}, + "channels":[{"type":"slack","status":"setup-required","reason":"new-channel","setupUrl":"https://n8n.example/agents/ag-local/channels"}]} + ], + "counts":{"agents":{"created":1,"updated":0,"skipped":0}}, + "workflows":[ + {"sourceWorkflowId":"wf-src","localId":"wf-local","name":"Example","projectId":"p1","parentFolderId":null,"activeVersionId":null,"isArchived":false,"publishing":{"state":"failed","error":"boom"},"status":"created"} + ], + "removedWorkflows":[],"removedFolders":[],"folders":[],"projects":[], + "bindings":{"agents":{"ag-src":"ag-local"},"workflows":{"wf-src":"wf-local"},"credentials":{}}, + "credentials":{"matched":[],"stubbed":[],"seeded":[],"incomplete":[]}, + "dataTables":{"matched":0,"created":0,"updated":0}, + "variables":{"matched":[],"missing":[],"created":[],"stubbed":[],"updated":[]}, + "tags":{"matched":[],"created":[],"renamed":[],"reconciled":[],"skipped":[]} +}` + +func TestPackageImportDeprecatedPolicyAliases(t *testing.T) { + f := packageFixture(t, cliPackageImportResult) + archive := writePackageArchive(t, cliPackageArchive) + + got := f.run("package", "import", "--file", archive, + "--workflow-conflict-policy", "skip", "--workflow-publishing-policy", "publish-all", "--yes", "--output", "json") + if got.code != ExitSuccess { + t.Fatalf("exit = %d, stderr: %s", got.code, got.stderr) + } + fields, _, _ := parseCLIImportMultipart(t, f) + if fields["conflictPolicy"] != "skip" || fields["publishingPolicy"] != "publish-all" || fields["idPolicy"] != "source" { + t.Errorf("fields = %v, want the aliases sent under the 2.47 names", fields) + } + if !strings.Contains(got.stderr, "deprecated") || !strings.Contains(got.stderr, "--conflict-policy") { + t.Errorf("stderr = %q, want a deprecation notice naming the new flag", got.stderr) + } + if !json.Valid([]byte(got.stdout)) { + t.Errorf("stdout = %q, want only the JSON result", got.stdout) + } + + got = f.run("package", "import-selection", "--file", archive, "--project-id", "p1", "--workflow-id", "a", + "--workflow-id-policy", "source", "--workflow-conflict-policy", "fail", "--yes", "--output", "json") + if got.code != ExitSuccess { + t.Fatalf("selection exit = %d, stderr: %s", got.code, got.stderr) + } + fields, _, _ = parseCLIImportMultipart(t, f) + if fields["conflictPolicy"] != "fail" || fields["idPolicy"] != "source" { + t.Errorf("selection fields = %v, want the 2.47 names", fields) + } + + before := f.requestCount() + got = f.run("package", "import", "--file", archive, "--conflict-policy", "skip", "--workflow-conflict-policy", "fail", "--yes") + if got.code != ExitError || !strings.Contains(got.stderr, "disagree") || f.requestCount() != before { + t.Errorf("disagreeing aliases = %+v, requests %d want %d", got, f.requestCount(), before) + } + got = f.run("package", "import", "--file", archive, "--conflict-policy", "skip", "--workflow-conflict-policy", "skip", "--yes", "--output", "json") + if got.code != ExitSuccess { + t.Errorf("agreeing aliases exit = %d, stderr: %s", got.code, got.stderr) + } +} + +func TestPackageImportResendsLegacyFieldsToOlderInstance(t *testing.T) { + f := packageFixture(t, cliPackageImportResult) + archive := writePackageArchive(t, cliPackageArchive) + f.route = func(_ *http.Request, page int) (int, string) { + if page == 0 { + return http.StatusBadRequest, `{"code":"invalid_type","path":["workflowConflictPolicy"],"message":"Required"}` + } + return http.StatusOK, cliPackageImportResult + } + got := f.run("package", "import", "--file", archive, "--conflict-policy", "new-version", "--yes", "--output", "json") + if got.code != ExitSuccess { + t.Fatalf("exit = %d, stderr: %s", got.code, got.stderr) + } + if f.pages != 2 { + t.Fatalf("requests = %d, want the 2.47 attempt and one legacy retry", f.pages) + } + fields, fileBytes, _ := parseCLIImportMultipart(t, f) + if fields["workflowConflictPolicy"] != "new-version" || fields["workflowIdPolicy"] != "source" || fileBytes != cliPackageArchive { + t.Errorf("retry fields = %v (archive %q), want legacy names and the full archive", fields, fileBytes) + } +} + +func TestPackageImportTextShowsAgentsAndSetupHints(t *testing.T) { + f := packageFixture(t, cliPackageImportAgentsResult) + archive := writePackageArchive(t, cliPackageArchive) + + got := f.run("package", "import", "--file", archive, "--conflict-policy", "skip", "--yes") + if got.code != ExitSuccess { + t.Fatalf("exit = %d, stderr: %s", got.code, got.stderr) + } + for _, want := range []string{"Agents:", "1 (1 created, 0 updated, 0 skipped)", "SOURCE AGENT", "ag-local", "Helper", "blocked"} { + if !strings.Contains(got.stdout, want) { + t.Errorf("stdout missing %q:\n%s", want, got.stdout) + } + } + for _, want := range []string{`Agent "Helper" (ag-local): slack channel needs setup (new-channel): open https://n8n.example/agents/ag-local/channels`, "2 Agent(s) or workflow(s) were imported but not published"} { + if !strings.Contains(got.stderr, want) { + t.Errorf("stderr missing %q:\n%s", want, got.stderr) + } + } + if strings.Contains(got.stdout, "https://") { + t.Errorf("stdout = %q, want hints on stderr only", got.stdout) + } +} + +func TestPackageImportScopeAndVersionErrors(t *testing.T) { + f := packageFixture(t, cliPackageImportResult) + archive := writePackageArchive(t, cliPackageArchive) + + f.route = func(*http.Request, int) (int, string) { return http.StatusForbidden, `{"message":"Forbidden"}` } + got := f.run("package", "import", "--file", archive, "--conflict-policy", "skip", "--yes") + for _, want := range []string{"either one", "workflow:import", "agent:import", "agent:read"} { + if got.code != ExitError || !strings.Contains(got.stderr, want) { + t.Errorf("403 stderr missing %q: %+v", want, got) + } + } + + f.route = func(*http.Request, int) (int, string) { + return http.StatusBadRequest, `{"code":"invalid_enum_value","options":["source"],"path":["idPolicy"],"message":"Invalid enum value. Expected 'source', received 'new'"}` + } + got = f.run("package", "import", "--file", archive, "--conflict-policy", "skip", "--id-policy", "new", "--yes") + if got.code != ExitError || !strings.Contains(got.stderr, "accept only --id-policy source") { + t.Errorf("idPolicy 400 = %+v, want the fix", got) + } +} + +func TestPackageAPIErrorNonRewindableArchive(t *testing.T) { + apiErr := &n8n.APIError{StatusCode: http.StatusBadRequest, Fields: []string{"workflowConflictPolicy"}} + err := packageAPIError(fmt.Errorf("n8n: POST /n8n-packages/import: %w: %w", n8n.ErrImportArchiveNotRewindable, apiErr), + config.Resolution{URL: "https://n8n.example.com"}, "import", allOf("workflow:import")) + for _, want := range []string{"predates n8n 2.47", "--file PATH instead of --file -", "nothing was written"} { + if !strings.Contains(err.Error(), want) { + t.Errorf("error = %q, want %q", err.Error(), want) + } + } +} + +func TestReportRateLimitHint(t *testing.T) { + f := newFixture(t) + f.login() + f.route = func(*http.Request, int) (int, string) { + return http.StatusTooManyRequests, `{"message":"Too many requests"}` + } + got := f.run("package", "import", "--file", writePackageArchive(t, cliPackageArchive), "--conflict-policy", "skip", "--yes") + if got.code != ExitError || !strings.Contains(got.stderr, "rate-limited this API key (429)") || !strings.Contains(got.stderr, "'n8n rate-limit get'") { + t.Errorf("429 result = %+v, want the rate-limit fix", got) + } + + var errOut bytes.Buffer + err := fmt.Errorf("list workflows: %w", &n8n.APIError{StatusCode: http.StatusTooManyRequests, + RateLimit: &n8n.RateLimit{RetryAfter: 12 * time.Second, HasRetryAfter: true}}) + if code := report(&errOut, err); code != ExitError || !strings.Contains(errOut.String(), "wait 12s and retry") { + t.Errorf("report = %d, %q, want the wait named", code, errOut.String()) + } + errOut.Reset() + report(&errOut, fmt.Errorf("boom")) + if strings.Contains(errOut.String(), "rate-limit") { + t.Errorf("report(non-429) = %q, want no rate-limit hint", errOut.String()) + } +} diff --git a/internal/cli/n8n_package_test.go b/internal/cli/n8n_package_test.go index 1f83f2c..0a70fde 100644 --- a/internal/cli/n8n_package_test.go +++ b/internal/cli/n8n_package_test.go @@ -339,7 +339,7 @@ func TestPackageImportConfirmationPolicyAndBody(t *testing.T) { before := f.requestCount() f.stdin = "no\n" - got := f.run("package", "import", "--file", archive, "--workflow-conflict-policy", "new-version") + got := f.run("package", "import", "--file", archive, "--conflict-policy", "new-version") if got.code != ExitError || !strings.Contains(got.stderr, "aborted") || f.requestCount() != before { t.Errorf("declined result = %+v, requests = %d want %d", got, f.requestCount(), before) } @@ -350,13 +350,13 @@ func TestPackageImportConfirmationPolicyAndBody(t *testing.T) { } f.interactive = false - got = f.run("package", "import", "--file", archive, "--workflow-conflict-policy", "new-version") + got = f.run("package", "import", "--file", archive, "--conflict-policy", "new-version") if got.code != ExitError || !strings.Contains(got.stderr, "pass --yes") || f.requestCount() != before { t.Errorf("non-interactive result = %+v, requests = %d want %d", got, f.requestCount(), before) } got = f.run("package", "import", "--file", archive, - "--workflow-conflict-policy", "new-version", + "--conflict-policy", "new-version", "--project-id", "p1", "--tag-conflict-policy", "rename", "--yes", "--output", "json") @@ -368,7 +368,7 @@ func TestPackageImportConfirmationPolicyAndBody(t *testing.T) { t.Errorf("request = %s %s", req.Method, req.URL.Path) } fields, fileBytes, filename := parseCLIImportMultipart(t, f) - if fields["workflowConflictPolicy"] != "new-version" || fields["workflowIdPolicy"] != "source" { + if fields["conflictPolicy"] != "new-version" || fields["idPolicy"] != "source" { t.Errorf("fields = %v, want conflict new-version and explicit id source", fields) } if fields["projectId"] != "p1" || fields["tagConflictPolicy"] != "rename" { @@ -387,7 +387,7 @@ func TestPackageImportTextWarnsAboutDroppedItems(t *testing.T) { f := packageFixture(t, cliPackageImportResult) archive := writePackageArchive(t, cliPackageArchive) - got := f.run("package", "import", "--file", archive, "--workflow-conflict-policy", "skip", "--yes") + got := f.run("package", "import", "--file", archive, "--conflict-policy", "skip", "--yes") if got.code != ExitSuccess { t.Fatalf("exit = %d, stderr: %s", got.code, got.stderr) } @@ -412,7 +412,7 @@ func TestPackageImportReportsIncompleteCredentials(t *testing.T) { f := packageFixture(t, body) archive := writePackageArchive(t, cliPackageArchive) - got := f.run("package", "import", "--file", archive, "--workflow-conflict-policy", "skip", + got := f.run("package", "import", "--file", archive, "--conflict-policy", "skip", "--credential-missing-mode", "create-with-values", "--data-table-schema-policy", "overwrite-non-destructive", "--yes") if got.code != ExitSuccess { t.Fatalf("exit = %d, stderr: %s", got.code, got.stderr) @@ -432,7 +432,7 @@ func TestPackageImportReportsIncompleteCredentials(t *testing.T) { } } - got = f.run("package", "import", "--file", archive, "--workflow-conflict-policy", "skip", "--yes", "--output", "json") + got = f.run("package", "import", "--file", archive, "--conflict-policy", "skip", "--yes", "--output", "json") if got.code != ExitSuccess { t.Fatalf("json exit = %d, stderr: %s", got.code, got.stderr) } @@ -461,7 +461,7 @@ func TestPackageImportSchemaOverwriteWarns(t *testing.T) { f.stdin = "no\n" got := f.run("package", "import", "--file", archive, - "--workflow-conflict-policy", "new-version", + "--conflict-policy", "new-version", "--data-table-schema-policy", "overwrite", "--credential-missing-mode", "create-with-values") if got.code != ExitError || f.requestCount() != before { @@ -479,13 +479,13 @@ func TestPackageImportStdinRequiresYes(t *testing.T) { f.stdin = cliPackageArchive before := f.requestCount() - got := f.run("package", "import", "--file", "-", "--workflow-conflict-policy", "skip") + got := f.run("package", "import", "--file", "-", "--conflict-policy", "skip") if got.code != ExitError || !strings.Contains(got.stderr, "--yes") || f.requestCount() != before { t.Errorf("stdin without --yes result = %+v, requests = %d want %d", got, f.requestCount(), before) } f.stdin = cliPackageArchive - got = f.run("package", "import", "--file", "-", "--workflow-conflict-policy", "skip", "--yes", "--output", "json") + got = f.run("package", "import", "--file", "-", "--conflict-policy", "skip", "--yes", "--output", "json") if got.code != ExitSuccess { t.Fatalf("stdin exit = %d, stderr: %s", got.code, got.stderr) } @@ -501,7 +501,7 @@ func TestPackageImportHardDeleteWarnsStronger(t *testing.T) { f.stdin = "no\n" got := f.run("package", "import", "--file", archive, - "--workflow-conflict-policy", "new-version", + "--conflict-policy", "new-version", "--folder-conflict-policy", "overwrite", "--overwrite-deletion-policy", "hard-delete") if got.code != ExitError { @@ -518,14 +518,14 @@ func TestPackageImportRejectsBadPoliciesBeforeTransport(t *testing.T) { before := f.requestCount() cases := [][]string{ - {"package", "import", "--workflow-conflict-policy", "new-version", "--yes"}, + {"package", "import", "--conflict-policy", "new-version", "--yes"}, {"package", "import", "--file", archive, "--yes"}, - {"package", "import", "--file", archive, "--workflow-conflict-policy", "sometimes", "--yes"}, - {"package", "import", "--file", archive, "--workflow-conflict-policy", "new-version", "--workflow-id-policy", "sometimes", "--yes"}, - {"package", "import", "--file", archive, "--workflow-conflict-policy", "new-version", "--bindings", "not-json", "--yes"}, - {"package", "import", "--file", archive, "--workflow-conflict-policy", "new-version", "--variable-parent-policy", "sometimes", "--yes"}, - {"package", "import", "--file", archive, "--workflow-conflict-policy", "new-version", "--yes", "--output", "yaml"}, - {"package", "import", "--file", filepath.Join(t.TempDir(), "missing.n8np"), "--workflow-conflict-policy", "new-version", "--yes"}, + {"package", "import", "--file", archive, "--conflict-policy", "sometimes", "--yes"}, + {"package", "import", "--file", archive, "--conflict-policy", "new-version", "--id-policy", "sometimes", "--yes"}, + {"package", "import", "--file", archive, "--conflict-policy", "new-version", "--bindings", "not-json", "--yes"}, + {"package", "import", "--file", archive, "--conflict-policy", "new-version", "--variable-parent-policy", "sometimes", "--yes"}, + {"package", "import", "--file", archive, "--conflict-policy", "new-version", "--yes", "--output", "yaml"}, + {"package", "import", "--file", filepath.Join(t.TempDir(), "missing.n8np"), "--conflict-policy", "new-version", "--yes"}, } for _, args := range cases { got := f.run(args...) @@ -544,14 +544,14 @@ func TestPackageImportBlockedPointsAtPolicies(t *testing.T) { f.status = http.StatusConflict f.body = `{"message":"import blocked","issues":[{"type":"workflow-conflict","sourceWorkflowId":"a"}]}` archive := writePackageArchive(t, cliPackageArchive) - got := f.run("package", "import", "--file", archive, "--workflow-conflict-policy", "fail", "--yes") - if got.code != ExitError || !strings.Contains(got.stderr, "409") || !strings.Contains(got.stderr, "--workflow-conflict-policy") { + got := f.run("package", "import", "--file", archive, "--conflict-policy", "fail", "--yes") + if got.code != ExitError || !strings.Contains(got.stderr, "409") || !strings.Contains(got.stderr, "--conflict-policy") { t.Errorf("409 result = %+v, want the conflict remediation", got) } f.body = `{"message":"missing credentials","issues":[{"type":"credential-missing"}]}` f.status = http.StatusUnprocessableEntity - got = f.run("package", "import", "--file", archive, "--workflow-conflict-policy", "skip", "--yes") + got = f.run("package", "import", "--file", archive, "--conflict-policy", "skip", "--yes") if got.code != ExitError || !strings.Contains(got.stderr, "422") || !strings.Contains(got.stderr, "--credential-missing-mode") { t.Errorf("422 result = %+v, want the missing-reference remediation", got) } @@ -569,7 +569,7 @@ func TestPackageDenialsAreReported(t *testing.T) { archive := writePackageArchive(t, cliPackageArchive) f.status = http.StatusForbidden - got = f.run("package", "import", "--file", archive, "--workflow-conflict-policy", "skip", "--yes") + got = f.run("package", "import", "--file", archive, "--conflict-policy", "skip", "--yes") if got.code != ExitError || !strings.Contains(got.stderr, "workflow:import") || !strings.Contains(got.stderr, "n8n discover --resource n8npackage") { t.Errorf("403 result = %+v, want scope and discover hint", got) } @@ -581,7 +581,7 @@ func TestPackageDenialsAreReported(t *testing.T) { } f.status = http.StatusBadRequest - got = f.run("package", "import", "--file", archive, "--workflow-conflict-policy", "skip", "--yes") + got = f.run("package", "import", "--file", archive, "--conflict-policy", "skip", "--yes") if got.code != ExitError || !strings.Contains(got.stderr, "400") { t.Errorf("400 result = %+v, want the bad-request guidance", got) } @@ -637,7 +637,7 @@ func TestPackageImportSelectionConfirmationAndBody(t *testing.T) { t.Errorf("non-interactive result = %+v, requests = %d want %d", got, f.requestCount(), before) } - got = f.run(append(args, "--workflow-conflict-policy", "skip", "--yes", "--output", "json")...) + got = f.run(append(args, "--conflict-policy", "skip", "--yes", "--output", "json")...) if got.code != ExitSuccess { t.Fatalf("confirmed exit = %d, stderr: %s", got.code, got.stderr) } @@ -647,11 +647,11 @@ func TestPackageImportSelectionConfirmationAndBody(t *testing.T) { } fields, fileBytes, filename := parseCLIImportMultipart(t, f) want := map[string]string{ - "selectedProjectId": "src-p", - "selectedWorkflowIds": `["wf-1","wf-2"]`, - "deletedWorkflowIds": `["wf-9"]`, - "workflowConflictPolicy": "skip", - "workflowIdPolicy": "source", + "selectedProjectId": "src-p", + "selectedWorkflowIds": `["wf-1","wf-2"]`, + "deletedWorkflowIds": `["wf-9"]`, + "conflictPolicy": "skip", + "idPolicy": "source", } for name, value := range want { if fields[name] != value { @@ -742,8 +742,8 @@ func TestPackageImportSelectionRejectsBadInputBeforeTransport(t *testing.T) { {cmd("--file", archive, "--project-id", "p", "--delete-workflow-id", "b", "--delete-workflow-id", "b"), "more than once"}, {cmd("--file", archive, "--project-id", "p", "--workflow-id", "a", "--delete-workflow-id", "a"), "both selected for import and listed for deletion"}, {cmd("--file", archive, "--project-id", "p", "--workflow-id", ""), "must not be empty"}, - {cmd("--file", archive, "--project-id", "p", "--workflow-id", "a", "--workflow-conflict-policy", "sometimes"), "workflow-conflict policy"}, - {cmd("--file", archive, "--project-id", "p", "--workflow-id", "a", "--workflow-id-policy", "sometimes"), "workflow-id policy"}, + {cmd("--file", archive, "--project-id", "p", "--workflow-id", "a", "--conflict-policy", "sometimes"), "conflict policy"}, + {cmd("--file", archive, "--project-id", "p", "--workflow-id", "a", "--id-policy", "sometimes"), "ID policy"}, {cmd("--file", archive, "--project-id", "p", "--delete-workflow-id", "b", "--overwrite-deletion-policy", "purge"), "overwrite-deletion policy"}, {cmd("--file", archive, "--project-id", "p", "--workflow-id", "a", "--overwrite-deletion-policy", "archive"), "only applies to deleted workflow IDs"}, {cmd("--file", archive, "--project-id", "p", "--workflow-id", "a", "--output", "yaml"), "yaml"}, @@ -815,7 +815,7 @@ func TestPackageImportCredentialConflictPolicy(t *testing.T) { archive := writePackageArchive(t, cliPackageArchive) before := f.requestCount() - got := f.run("package", "import", "--file", archive, "--workflow-conflict-policy", "skip", "--credential-conflict-policy", "replace", "--yes") + got := f.run("package", "import", "--file", archive, "--conflict-policy", "skip", "--credential-conflict-policy", "replace", "--yes") if got.code != ExitError || f.requestCount() != before { t.Fatalf("bad policy result = %+v, requests = %d want %d", got, f.requestCount(), before) } @@ -826,12 +826,12 @@ func TestPackageImportCredentialConflictPolicy(t *testing.T) { } f.stdin = "no\n" - got = f.run("package", "import", "--file", archive, "--workflow-conflict-policy", "skip", "--credential-conflict-policy", "overwrite") + got = f.run("package", "import", "--file", archive, "--conflict-policy", "skip", "--credential-conflict-policy", "overwrite") if got.code != ExitError || f.requestCount() != before || !strings.Contains(got.stderr, "Credential overwrite writes the package's names and expression values") { t.Errorf("declined overwrite result = %+v, want the overwrite warning in the prompt and no request", got) } - got = f.run("package", "import", "--file", archive, "--workflow-conflict-policy", "skip", "--credential-conflict-policy", "overwrite", "--yes") + got = f.run("package", "import", "--file", archive, "--conflict-policy", "skip", "--credential-conflict-policy", "overwrite", "--yes") if got.code != ExitSuccess { t.Fatalf("exit = %d, stderr: %s", got.code, got.stderr) } @@ -851,7 +851,7 @@ func TestPackageImportCredentialConflictPolicy(t *testing.T) { t.Errorf("stdout = %q, want the overwrite note on stderr only", got.stdout) } - got = f.run("package", "import", "--file", archive, "--workflow-conflict-policy", "skip", "--yes") + got = f.run("package", "import", "--file", archive, "--conflict-policy", "skip", "--yes") if got.code != ExitSuccess { t.Fatalf("unset exit = %d, stderr: %s", got.code, got.stderr) } @@ -860,7 +860,7 @@ func TestPackageImportCredentialConflictPolicy(t *testing.T) { t.Errorf("fields = %v, want credentialConflictPolicy omitted when the flag is unset", fields) } - got = f.run("package", "import", "--file", archive, "--workflow-conflict-policy", "skip", "--yes", "--output", "json") + got = f.run("package", "import", "--file", archive, "--conflict-policy", "skip", "--yes", "--output", "json") if got.code != ExitSuccess { t.Fatalf("json exit = %d, stderr: %s", got.code, got.stderr) } @@ -879,7 +879,7 @@ func TestPackageImportToleratesAbsentCredentialsUpdated(t *testing.T) { archive := writePackageArchive(t, cliPackageArchive) for _, args := range [][]string{ - {"package", "import", "--file", archive, "--workflow-conflict-policy", "skip", "--yes"}, + {"package", "import", "--file", archive, "--conflict-policy", "skip", "--yes"}, {"package", "import-selection", "--file", archive, "--project-id", "p1", "--workflow-id", "wf-src", "--yes"}, } { got := f.run(args...) @@ -932,8 +932,8 @@ func TestPackageImportBlockedListsIssues(t *testing.T) { args []string want string }{ - {"import 409", http.StatusConflict, []string{"package", "import", "--file", archive, "--workflow-conflict-policy", "fail", "--yes"}, "--credential-conflict-policy"}, - {"import 422", http.StatusUnprocessableEntity, []string{"package", "import", "--file", archive, "--workflow-conflict-policy", "fail", "--yes"}, "credential:update"}, + {"import 409", http.StatusConflict, []string{"package", "import", "--file", archive, "--conflict-policy", "fail", "--yes"}, "--credential-conflict-policy"}, + {"import 422", http.StatusUnprocessableEntity, []string{"package", "import", "--file", archive, "--conflict-policy", "fail", "--yes"}, "credential:update"}, {"selection 409", http.StatusConflict, []string{"package", "import-selection", "--file", archive, "--project-id", "p1", "--workflow-id", "wf-1", "--yes"}, "409"}, {"selection 422", http.StatusUnprocessableEntity, []string{"package", "import-selection", "--file", archive, "--project-id", "p1", "--workflow-id", "wf-1", "--yes"}, "422"}, } { diff --git a/internal/cli/promotion.go b/internal/cli/promotion.go index 5345337..09e2049 100644 --- a/internal/cli/promotion.go +++ b/internal/cli/promotion.go @@ -138,7 +138,7 @@ func newPromotionProviderListCommand(opts Options) *cobra.Command { "cursor-paginated page at a time. Use --all to follow every cursor,\n" + "capped at 10,000 providers.\n\n" + "Use a returned ID with get, update, delete, and 'connection create'.\n" + - "Requires gitConnection:list.\n\n" + cursorCollectionHelp, + "Requires promotions:list (gitConnection:list before n8n 2.47).\n\n" + cursorCollectionHelp, Example: " n8n promotion provider list\n" + " n8n promotion provider list --limit 50 --output json\n" + " n8n promotion provider list --all", @@ -253,8 +253,8 @@ func newPromotionProviderCreateCommand(opts Options) *cobra.Command { "(ed25519 or rsa, default ed25519) or {\"authType\":\"token\",\n" + "\"password\":\"...\"} plus username for git, and the optional config.\n" + "Unknown fields and trailing JSON documents are refused before\n" + - "transport. Requires gitConnection:create. Follow with 'n8n promotion\n" + - "connection create'.", + "transport. Requires promotions:create (gitConnection:create before\n" + + "n8n 2.47). Follow with 'n8n promotion connection create'.", Example: " n8n promotion provider create --name github --type git --auth-type ssh-key\n" + " printf '%s\\n' \"$GITLAB_TOKEN\" | n8n promotion provider create --name gitlab --type gitlab --base-url https://gitlab.example.com --auth-type token --password-stdin\n" + " n8n promotion provider create --input provider.json --output json", @@ -373,7 +373,7 @@ func newPromotionProviderGetCommand(opts Options) *cobra.Command { Long: "Show one promotion provider by ID. The response is the public provider\n" + "document: name, type, auth type, configuration, and timestamps.\n" + "Secrets are never returned. Find the ID with 'n8n promotion provider\n" + - "list'. Requires gitConnection:read.", + "list'. Requires promotions:read (gitConnection:read before n8n 2.47).", Example: " n8n promotion provider get PROVIDER_ID\n" + " n8n promotion provider get PROVIDER_ID --output json", Args: cobra.ExactArgs(1), @@ -431,7 +431,8 @@ func newPromotionProviderUpdateCommand(opts Options) *cobra.Command { "runs ask for confirmation and non-interactive runs require --yes.\n" + "Credentials travel only as --input because secrets are never flags. A\n" + "409 means another request changed the provider first: reload it and\n" + - "retry. Requires gitConnection:update.", + "retry. Requires promotions:update (gitConnection:update before n8n\n" + + "2.47).", Example: " n8n promotion provider update PROVIDER_ID --input provider-update.json\n" + " printf '%s\\n' '{\"name\":\"github-new\"}' | n8n promotion provider update PROVIDER_ID --input -\n" + " n8n promotion provider update PROVIDER_ID --input provider-update.json --yes --output json", @@ -498,7 +499,8 @@ func newPromotionProviderDeleteCommand(opts Options) *cobra.Command { "connection (older) cannot be deleted: the instance answers 409 and\n" + "nothing changes, so delete or move those first. This cannot be undone.\n\n" + "Interactive runs ask for confirmation; non-interactive runs require\n" + - "--yes. Requires gitConnection:delete.", + "--yes. Requires promotions:delete (gitConnection:delete before n8n\n" + + "2.47).", Example: " n8n promotion provider delete PROVIDER_ID\n" + " n8n promotion provider delete PROVIDER_ID --yes --output json", Args: cobra.ExactArgs(1), @@ -1681,7 +1683,8 @@ func runPromotionApply(ctx context.Context, opts Options, id string, f promotion } // promotionApplyStoppedError is returned after an apply answered 200 without -// importing: blocked at preflight, the source moved, or a status this CLI does +// importing: blocked by its check, the source or the preview moved, or a status +// this CLI does // not know. The result was already printed; Run reports the message and maps // the status to its own exit code so scripts can tell these apart from // transport and validation errors. @@ -1696,9 +1699,11 @@ func (e *promotionApplyStoppedError) Error() string { target := cmp.Or(e.target, promotionTargetConnection) switch e.status { case n8n.PromotionApplyStatusBlocked: - return fmt.Sprintf("promotion apply of %s %s was blocked at preflight; nothing was applied", target, e.id) + return fmt.Sprintf("promotion apply of %s %s was blocked by its pre-import check; nothing was applied", target, e.id) case n8n.PromotionApplyStatusSourceChanged: return fmt.Sprintf("promotion apply of %s %s stopped because the source branch moved; nothing was applied", target, e.id) + case n8n.PromotionApplyStatusPreviewChanged: + return fmt.Sprintf("promotion apply of %s %s stopped because the instance changed since the Apply preview was reviewed; nothing was applied", target, e.id) default: return fmt.Sprintf("promotion apply of %s %s answered unknown status %q; check the instance before assuming anything was applied", target, e.id, e.status) } @@ -1708,7 +1713,7 @@ func (e *promotionApplyStoppedError) exitCode() int { switch e.status { case n8n.PromotionApplyStatusBlocked: return ExitPromotionBlocked - case n8n.PromotionApplyStatusSourceChanged: + case n8n.PromotionApplyStatusSourceChanged, n8n.PromotionApplyStatusPreviewChanged: return ExitPromotionSourceChanged default: return ExitError @@ -1733,8 +1738,8 @@ func finishPromotionApplyTarget(opts Options, id string, result *n8n.ApplyPromot source := result.ExpectedSource() switch result.Status { case n8n.PromotionApplyStatusBlocked: - fmt.Fprintln(opts.Streams.Err, "Nothing was applied: preflight found items to resolve first. Create the missing projects, bind the missing credentials and variables, and grant the listed access.") - if promotionNeedsConfirmation(result.Preflight) { + fmt.Fprintln(opts.Streams.Err, "Nothing was applied: the pre-import check found items to resolve first. Create the missing projects, bind the missing credentials and variables, grant the listed access, and resolve the conflicts.") + if promotionNeedsConfirmation(result.Blockers()) { fmt.Fprintln(opts.Streams.Err, "project-deletion and destructive-change conflicts are applied only with explicit confirmation when the apply is continued.") } idField, idValue := "configId", source.ConfigID @@ -1748,17 +1753,19 @@ func finishPromotionApplyTarget(opts Options, id string, result *n8n.ApplyPromot } case n8n.PromotionApplyStatusSourceChanged: fmt.Fprintf(opts.Streams.Err, "Nothing was applied: the branch moved since it was reviewed. Review the branch again, then re-run '%sapply %s'.\n", prefix, id) + case n8n.PromotionApplyStatusPreviewChanged: + fmt.Fprintf(opts.Streams.Err, "Nothing was applied: this instance changed since the Apply preview was reviewed, for example after a local edit. Review the changes again, then re-run '%sapply %s' with the new preview.\n", prefix, id) default: fmt.Fprintln(opts.Streams.Err, "This CLI does not know the apply status; read the full result with --output json.") } return &promotionApplyStoppedError{id: id, status: result.Status, target: target} } -func promotionNeedsConfirmation(preflight *n8n.PromotionApplyPreflight) bool { - if preflight == nil { +func promotionNeedsConfirmation(check *n8n.PromotionApplyPreflight) bool { + if check == nil { return false } - for _, conflict := range preflight.Conflicts { + for _, conflict := range check.Conflicts { if conflict.Code == n8n.PromotionConflictProjectDeletion || conflict.Code == n8n.PromotionConflictDestructiveChange { return true } @@ -2072,29 +2079,30 @@ func writePromotionOptionalCount(tw *tabwriter.Writer, entity, detail string, co } func writePromotionBlockedResult(opts Options, resolution config.Resolution, result *n8n.ApplyPromotionResult) error { - var preflight n8n.PromotionApplyPreflight - if result.Preflight != nil { - preflight = *result.Preflight + // n8n 2.47 and later send check, older instances preflight. + var check n8n.PromotionApplyPreflight + if blockers := result.Blockers(); blockers != nil { + check = *blockers } tw := tabwriter.NewWriter(opts.Streams.Out, 0, 0, 2, ' ', 0) writePromotionApplyHeader(tw, resolution, result) - if len(preflight.MissingProjects) > 0 { - fmt.Fprintf(tw, "\nMISSING PROJECTS (%d)\nID\tNAME\n", len(preflight.MissingProjects)) - for _, project := range preflight.MissingProjects { + if len(check.MissingProjects) > 0 { + fmt.Fprintf(tw, "\nMISSING PROJECTS (%d)\nID\tNAME\n", len(check.MissingProjects)) + for _, project := range check.MissingProjects { fmt.Fprintf(tw, "%s\t%s\n", emptyDash(project.ID), emptyDash(project.Name)) } } - writePromotionIssues(tw, "Missing bindings", preflight.MissingBindings) - writePromotionIssues(tw, "Access requirements", preflight.AccessRequirements) - writePromotionIssues(tw, "Conflicts", preflight.Conflicts) - writePromotionIssues(tw, "Warnings", preflight.Warnings) - if preflight.Empty() { - fmt.Fprintln(tw, "\nPreflight:\tno items reported") + writePromotionIssues(tw, "Missing bindings", check.MissingBindings) + writePromotionIssues(tw, "Access requirements", check.AccessRequirements) + writePromotionIssues(tw, "Conflicts", check.Conflicts) + writePromotionIssues(tw, "Warnings", check.Warnings) + if check.Empty() { + fmt.Fprintln(tw, "\nCheck:\tno items reported") } return tw.Flush() } -// writePromotionIssues renders one preflight group as a table: kind, code, +// writePromotionIssues renders one check group as a table: kind, code, // name, a one-line detail, and which workflows use the item. func writePromotionIssues(tw *tabwriter.Writer, title string, issues []n8n.PromotionApplyIssue) { if len(issues) == 0 { @@ -2125,6 +2133,11 @@ func promotionIssueDetail(issue n8n.PromotionApplyIssue) string { parts = append(parts, promotionChangeText(change)) } } + case n8n.PromotionConflictMoved: + parts = append(parts, promotionMovedText(issue)) + } + if issue.Reason != "" { + parts = append(parts, issue.Reason) } if issue.CredentialType != "" { parts = append(parts, "type "+issue.CredentialType) @@ -2148,7 +2161,7 @@ func promotionIssueDetail(issue n8n.PromotionApplyIssue) string { if issue.SourceID != nil && *issue.SourceID != "" { parts = append(parts, "source ID "+*issue.SourceID) } - if issue.Project != nil && issue.Code != n8n.PromotionConflictProjectDeletion { + if issue.Project != nil && issue.Code != n8n.PromotionConflictProjectDeletion && issue.Code != n8n.PromotionConflictMoved { parts = append(parts, "project "+issue.Project.ID) } if issue.OwnerProject != nil { @@ -2157,6 +2170,29 @@ func promotionIssueDetail(issue n8n.PromotionApplyIssue) string { return strings.Join(parts, "; ") } +// promotionMovedText describes a moved conflict (n8n 2.47 and later): the +// branch holds the workflow or folder in one project, the instance in another. +func promotionMovedText(issue n8n.PromotionApplyIssue) string { + branch := "-" + if issue.Project != nil { + branch = cmp.Or(issue.Project.Name, issue.Project.ID) + if issue.Project.ID != "" && issue.Project.Name != "" { + branch += " (" + issue.Project.ID + ")" + } + } + if issue.ProjectExists != nil && !*issue.ProjectExists { + branch += ", not on this instance" + } + here := "-" + if issue.InstanceProject != nil { + here = cmp.Or(issue.InstanceProject.Name, issue.InstanceProject.ID) + if issue.InstanceProject.ID != "" && issue.InstanceProject.Name != "" { + here += " (" + issue.InstanceProject.ID + ")" + } + } + return fmt.Sprintf("branch project %s, instance project %s; move it back into one project", branch, here) +} + func promotionChangeText(change n8n.PromotionDataTableChange) string { switch { case change.Column != "" && change.From != "" && change.To != "": @@ -2261,7 +2297,8 @@ func promotionAPIError(err error, resolution config.Resolution, action string, s case n8n.IsStatus(err, http.StatusUnprocessableEntity): return fmt.Errorf("%s rejected the promotion %s (422): the remote content cannot be imported as-is (missing references or unresolvable content); resolve the references and retry: %w", resolution.URL, action, err) case n8n.IsForbidden(err): - return forbiddenScopeError(err, resolution, "promotion "+action, allOf(promotionScope(action)), "", promotionResource) + need, extra := promotionScopeNeed(action) + return forbiddenScopeError(err, resolution, "promotion "+action, need, extra, promotionResource) case n8n.IsNotFound(err) && subject.what != "" && !promotionRouteMissing(err): return fmt.Errorf("%s has no %s (404): check the ID with %s: %w", resolution.URL, subject.what, subject.find, err) case n8n.IsNotFound(err) && subject.what != "": @@ -2305,29 +2342,81 @@ func promotionMovesContent(action string) bool { return false } +// promotionScopeNames maps a promotion action to the scope current n8n checks +// and the scope instances before n8n 2.47 checked. n8n 2.47 renamed the +// gitConnection:* scopes of the provider, environment, and project-sync routes +// to promotions:*; the connection routes (before n8n 2.46) keep +// gitConnection:*, so both names are the same there. +var promotionScopeNames = map[string][2]string{ + "provider list": {"promotions:list", "gitConnection:list"}, + "environment list": {"promotions:list", "gitConnection:list"}, + "provider create": {"promotions:create", "gitConnection:create"}, + "environment create": {"promotions:create", "gitConnection:create"}, + "provider get": {"promotions:read", "gitConnection:read"}, + "environment get": {"promotions:read", "gitConnection:read"}, + "environment project list": {"promotions:read", "gitConnection:read"}, + "environment missing-projects": {"promotions:read", "promotions:read"}, + "provider update": {"promotions:update", "gitConnection:update"}, + "environment update": {"promotions:update", "gitConnection:update"}, + "provider delete": {"promotions:delete", "gitConnection:delete"}, + "environment delete": {"promotions:delete", "gitConnection:delete"}, + "environment connect": {"promotions:connect", "gitConnection:clone"}, + "environment disconnect": {"promotions:connect", "gitConnection:clone"}, + "environment project add": {"promotions:manageProjects", "gitConnection:manageProjects"}, + "environment project remove": {"promotions:manageProjects", "gitConnection:manageProjects"}, + "project promote": {"promotions:promote", "gitConnection:push"}, + "project changes promote": {"promotions:promote", "gitConnection:push"}, + "environment promote": {"promotions:promote", "gitConnection:push"}, + "project apply": {"promotions:apply", "gitConnection:pull"}, + "project apply-continue": {"promotions:apply", "gitConnection:pull"}, + "project changes apply": {"promotions:apply", "gitConnection:pull"}, + "environment apply": {"promotions:apply", "gitConnection:pull"}, + "environment apply-continue": {"promotions:apply", "gitConnection:pull"}, + "provider repositories": {"promotions:discover", "gitConnection:discover"}, + "provider branches": {"promotions:discover", "gitConnection:discover"}, + + "connection list": {"gitConnection:list", "gitConnection:list"}, + "connection create": {"gitConnection:create", "gitConnection:create"}, + "connection get": {"gitConnection:read", "gitConnection:read"}, + "project list": {"gitConnection:read", "gitConnection:read"}, + "connection update": {"gitConnection:update", "gitConnection:update"}, + "config apply set": {"gitConnection:update", "gitConnection:update"}, + "config promote set": {"gitConnection:update", "gitConnection:update"}, + "config delete": {"gitConnection:update", "gitConnection:update"}, + "connection delete": {"gitConnection:delete", "gitConnection:delete"}, + "checkout clone": {"gitConnection:clone", "gitConnection:clone"}, + "checkout disconnect": {"gitConnection:clone", "gitConnection:clone"}, + "project add": {"gitConnection:manageProjects", "gitConnection:manageProjects"}, + "project remove": {"gitConnection:manageProjects", "gitConnection:manageProjects"}, + "promote": {"gitConnection:push", "gitConnection:push"}, + "apply": {"gitConnection:pull", "gitConnection:pull"}, + "apply-continue": {"gitConnection:pull", "gitConnection:pull"}, +} + +// promotionScope is the scope current n8n checks for a promotion action. func promotionScope(action string) string { - switch action { - case "provider list", "connection list", "environment list": - return "gitConnection:list" - case "provider create", "connection create", "environment create": - return "gitConnection:create" - case "provider get", "connection get", "project list", "environment get", "environment project list": - return "gitConnection:read" - case "provider update", "connection update", "config apply set", "config promote set", "config delete", "environment update": - return "gitConnection:update" - case "provider delete", "connection delete", "environment delete": - return "gitConnection:delete" - case "checkout clone", "checkout disconnect", "environment connect", "environment disconnect": - return "gitConnection:clone" - case "project add", "project remove", "environment project add", "environment project remove": - return "gitConnection:manageProjects" - case "promote", "project promote", "project changes promote", "environment promote": - return "gitConnection:push" - case "apply", "apply-continue", "project apply", "project apply-continue", "project changes apply", "environment apply", "environment apply-continue": - return "gitConnection:pull" - case "provider repositories", "provider branches": - return "gitConnection:discover" - default: - return "gitConnection:*" + if names, ok := promotionScopeNames[action]; ok { + return names[0] + } + return "promotions:*" +} + +// promotionLegacyScope is the scope instances before n8n 2.47 checked for a +// promotion action; it equals [promotionScope] where the name did not change. +func promotionLegacyScope(action string) string { + if names, ok := promotionScopeNames[action]; ok { + return names[1] + } + return "gitConnection:*" +} + +// promotionScopeNeed is the 403 requirement for a promotion action: the +// current scope, plus the pre-2.47 name and a sentence saying which instance +// checks which when the name changed. +func promotionScopeNeed(action string) (scopeNeed, string) { + current, legacy := promotionScope(action), promotionLegacyScope(action) + if current == legacy { + return allOf(current), "" } + return anyOf(current, legacy), fmt.Sprintf("n8n 2.47 and later check %s; older instances check %s, so the key needs the one its instance checks", current, legacy) } diff --git a/internal/cli/promotion_apply_test.go b/internal/cli/promotion_apply_test.go index 36e0c16..e4e445c 100644 --- a/internal/cli/promotion_apply_test.go +++ b/internal/cli/promotion_apply_test.go @@ -87,7 +87,7 @@ func TestPromotionApplyBlocked(t *testing.T) { if !sameJSON(t, got.stdout, cliPromotionBlockedBody) { t.Errorf("stdout = %s, want the full blocked result", got.stdout) } - for _, want := range []string{"Nothing was applied", "configId=cfg-apply", "branchName=main", "commitSha=0123456789abcdef0123456789abcdef01234567", "explicit confirmation", "blocked at preflight"} { + for _, want := range []string{"Nothing was applied", "configId=cfg-apply", "branchName=main", "commitSha=0123456789abcdef0123456789abcdef01234567", "explicit confirmation", "blocked by its pre-import check"} { if !strings.Contains(got.stderr, want) { t.Errorf("stderr missing %q:\n%s", want, got.stderr) } @@ -330,8 +330,11 @@ func TestPromotionNotFoundNamesTheMissingResource(t *testing.T) { func TestPromotionScopeCoversDiscover(t *testing.T) { for _, action := range []string{"provider repositories", "provider branches"} { - if got := promotionScope(action); got != "gitConnection:discover" { - t.Errorf("promotionScope(%q) = %q, want gitConnection:discover", action, got) + if got := promotionScope(action); got != "promotions:discover" { + t.Errorf("promotionScope(%q) = %q, want promotions:discover", action, got) + } + if got := promotionLegacyScope(action); got != "gitConnection:discover" { + t.Errorf("promotionLegacyScope(%q) = %q, want gitConnection:discover", action, got) } } } diff --git a/internal/cli/promotion_check_test.go b/internal/cli/promotion_check_test.go new file mode 100644 index 0000000..9aabbda --- /dev/null +++ b/internal/cli/promotion_check_test.go @@ -0,0 +1,248 @@ +package cli + +import ( + "net/http" + "strings" + "testing" +) + +// n8n 2.47 shapes: blocked carries check, preview-changed joins the statuses, +// project apply takes expectedPreviewRevision, scopes moved to promotions:*, +// and environments list their missing projects. + +const cliPreviewRevision = "abcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcd" + +const cliCheckBlockedBody = `{ + "environmentId":"` + cliEnvironmentID + `", + "git":{"commitSha":"` + cliSelectionSHA + `","branchName":"main"}, + "status":"blocked", + "check":{ + "missingProjects":[{"id":"p-9","name":"Ops"}], + "missingBindings":[], + "accessRequirements":[], + "conflicts":[ + {"kind":"workflow","code":"lineage-conflict","reason":"history diverged","consumers":[{"project":{"id":"p1","name":"Sales"},"workflows":[{"id":"w1","name":"Lead"}]}]}, + {"kind":"project","code":"project-not-on-branch","project":{"id":"p2","name":"Ops"},"reason":"absent from the branch"}, + {"kind":"folder","code":"moved","id":"f1","name":"Inbox","project":{"id":"p1","name":"Sales"},"projectExists":false,"instanceProject":{"id":"p3","name":"Support"}}, + {"kind":"data-table","code":"destructive-change","id":"dt1","name":"Leads","changes":[{"kind":"remove-column","column":"score","destructive":true}]} + ], + "warnings":[] + } +}` + +const cliPreviewChangedBody = `{ + "environmentId":"` + cliEnvironmentID + `", + "git":{"commitSha":"` + cliSelectionSHA + `","branchName":"main"}, + "status":"preview-changed" +}` + +func TestPromotionApplyRendersCheck(t *testing.T) { + for _, args := range [][]string{ + {"promotion", "environment", "apply", cliEnvironmentID, "--yes"}, + {"promotion", "project", "apply", "p", "--workflow-id", "w", "--yes"}, + } { + f := promotionFixture(t, cliCheckBlockedBody) + got := f.run(args...) + if got.code != ExitPromotionBlocked { + t.Fatalf("%v: exit = %d, stderr: %s", args, got.code, got.stderr) + } + for _, want := range []string{ + "MISSING PROJECTS (1)", "p-9", + "CONFLICTS (4)", "lineage-conflict", "history diverged", "1 workflow(s) in 1 project(s)", + "project-not-on-branch", "absent from the branch", "project p2", + "moved", "branch project Sales (p1), not on this instance, instance project Support (p3)", + "remove-column score", + } { + if !strings.Contains(got.stdout, want) { + t.Errorf("%v: stdout missing %q:\n%s", args, want, got.stdout) + } + } + if strings.Contains(got.stdout, "no items reported") { + t.Errorf("%v: stdout = %s, want the check items", args, got.stdout) + } + for _, want := range []string{"pre-import check", "explicit confirmation", "apply-continue", "environmentId=" + cliEnvironmentID} { + if !strings.Contains(got.stderr, want) { + t.Errorf("%v: stderr missing %q:\n%s", args, want, got.stderr) + } + } + got = f.run(append(args, "--output", "json")...) + if got.code != ExitPromotionBlocked || !sameJSON(t, got.stdout, cliCheckBlockedBody) { + t.Errorf("%v: json = %+v", args, got) + } + } + + // An empty check says so rather than printing nothing. + f := promotionFixture(t, strings.Replace(cliEnvBlockedBody, `"preflight"`, `"check"`, 1)) + f.body = strings.Replace(f.body, `[{"id":"p-9","name":"Ops"}]`, `[]`, 1) + if got := f.run("promotion", "environment", "apply", cliEnvironmentID, "--yes"); got.code != ExitPromotionBlocked || !strings.Contains(got.stdout, "Check:") { + t.Errorf("empty check = %+v", got) + } +} + +func TestPromotionApplyPreviewChanged(t *testing.T) { + for _, tc := range []struct { + args []string + hint string + }{ + {[]string{"promotion", "environment", "apply", cliEnvironmentID}, "n8n promotion environment apply " + cliEnvironmentID}, + {append([]string{"promotion", "environment", "apply-continue", cliEnvironmentID}, envExpectedFlags()...), "n8n promotion environment apply " + cliEnvironmentID}, + {[]string{"promotion", "project", "apply", "p", "--workflow-id", "w"}, "n8n promotion project apply p"}, + {append([]string{"promotion", "project", "apply-continue", "p", "--workflow-id", "w"}, envExpectedFlags()...), "n8n promotion project apply p"}, + } { + f := promotionFixture(t, cliPreviewChangedBody) + got := f.run(append(tc.args, "--yes", "--output", "json")...) + if got.code != ExitPromotionSourceChanged || !sameJSON(t, got.stdout, cliPreviewChangedBody) { + t.Errorf("%v: result = %+v, want exit %d", tc.args, got, ExitPromotionSourceChanged) + } + for _, want := range []string{"Apply preview was reviewed", tc.hint, "nothing was applied"} { + if !strings.Contains(got.stderr, want) { + t.Errorf("%v: stderr missing %q:\n%s", tc.args, want, got.stderr) + } + } + if got = f.run(append(tc.args, "--yes")...); got.code != ExitPromotionSourceChanged || !strings.Contains(got.stdout, "preview-changed") { + t.Errorf("%v text = %+v", tc.args, got) + } + } + if code := (&promotionApplyStoppedError{status: "preview-changed"}).exitCode(); code != ExitPromotionSourceChanged { + t.Errorf("preview-changed exit = %d, want %d", code, ExitPromotionSourceChanged) + } +} + +func TestPromotionProjectApplyExpectedPreviewRevision(t *testing.T) { + f := promotionFixture(t, cliEnvAppliedBody) + for _, tc := range []struct { + args []string + path, body string + }{ + {[]string{"promotion", "project", "apply", "p", "--workflow-id", "w", "--expected-preview-revision", cliPreviewRevision}, + "/promotions/projects/p/apply", `{"workflowIds":["w"],"expectedPreviewRevision":"` + cliPreviewRevision + `"}`}, + {append([]string{"promotion", "project", "apply-continue", "p", "--workflow-id", "w", "--expected-preview-revision", cliPreviewRevision}, envExpectedFlags()...), + "/promotions/projects/p/apply/continue", `{"workflowIds":["w"],"expectedSource":` + cliEnvSource + `,"expectedPreviewRevision":"` + cliPreviewRevision + `"}`}, + {[]string{"promotion", "project", "apply", "p", "--workflow-id", "w"}, + "/promotions/projects/p/apply", `{"workflowIds":["w"]}`}, + } { + if got := f.run(append(tc.args, "--yes")...); got.code != ExitSuccess { + t.Fatalf("%v: %+v", tc.args, got) + } + req := f.lastRequest() + if req.URL.EscapedPath() != "/api/v1"+tc.path || f.lastBody() != tc.body { + t.Errorf("%v: request = %s %s", tc.args, req.URL.EscapedPath(), f.lastBody()) + } + } + + input := writePromotionInput(t, f, "revision.json", `{"workflowIds":["w"],"expectedPreviewRevision":"`+cliPreviewRevision+`"}`) + if got := f.run("promotion", "project", "apply", "p", "--input", input, "--yes"); got.code != ExitSuccess || f.lastBody() != `{"workflowIds":["w"],"expectedPreviewRevision":"`+cliPreviewRevision+`"}` { + t.Errorf("input = %+v body=%s", got, f.lastBody()) + } + + before := f.requestCount() + for _, args := range [][]string{ + {"promotion", "project", "apply", "p", "--workflow-id", "w", "--expected-preview-revision", "ABC", "--yes"}, + {"promotion", "project", "apply", "p", "--input", writePromotionInput(t, f, "bad.json", `{"workflowIds":["w"],"expectedPreviewRevision":"nope"}`), "--yes"}, + {"promotion", "project", "apply", "p", "--input", input, "--expected-preview-revision", cliPreviewRevision, "--yes"}, + } { + if got := f.run(args...); got.code == ExitSuccess { + t.Errorf("%v accepted: %+v", args, got) + } + } + if f.requestCount() != before { + t.Errorf("invalid revisions reached the instance") + } + for _, args := range [][]string{ + {"promotion", "environment", "apply", cliEnvironmentID, "--expected-preview-revision", cliPreviewRevision, "--yes"}, + {"promotion", "project", "promote", "p", "--workflow-id", "w", "--expected-preview-revision", cliPreviewRevision, "--yes"}, + } { + if got := f.run(args...); got.code == ExitSuccess || !strings.Contains(got.stderr, "unknown flag") { + t.Errorf("%v = %+v, want unknown flag", args, got) + } + } +} + +func TestPromotionScopesNameBothGenerations(t *testing.T) { + for _, tc := range []struct { + args []string + current, prev string + }{ + {[]string{"promotion", "environment", "apply", cliEnvironmentID, "--yes"}, "promotions:apply", "gitConnection:pull"}, + {[]string{"promotion", "environment", "disconnect", cliEnvironmentID, "--yes"}, "promotions:connect", "gitConnection:clone"}, + {[]string{"promotion", "provider", "list"}, "promotions:list", "gitConnection:list"}, + {[]string{"promotion", "project", "promote", "p", "--workflow-id", "w", "--yes"}, "promotions:promote", "gitConnection:push"}, + } { + f := promotionFixture(t, `{"message":"Forbidden"}`) + f.status = http.StatusForbidden + got := f.run(tc.args...) + for _, want := range []string{tc.current, tc.prev, "either one", "n8n 2.47 and later check " + tc.current} { + if got.code != ExitError || !strings.Contains(got.stderr, want) { + t.Errorf("%v: stderr missing %q:\n%s", tc.args, want, got.stderr) + } + } + } + // Connection routes predate the rename and keep one scope. + f := promotionFixture(t, `{"message":"Forbidden"}`) + f.status = http.StatusForbidden + got := f.run("promotion", "connection", "list") + if got.code != ExitError || !strings.Contains(got.stderr, "gitConnection:list") || strings.Contains(got.stderr, "promotions:") { + t.Errorf("connection 403 = %+v", got) + } +} + +const cliMissingProjectsBody = `{ + "environmentId":"` + cliEnvironmentID + `", + "git":{"commitSha":"` + cliSelectionSHA + `","branchName":"main"}, + "data":[{"id":"p-9","name":"Ops","icon":{"type":"emoji","value":"📣"},"description":"Operations\nteam","customTelemetryTags":[{"key":"team","value":"ops"}]}] +}` + +func TestPromotionEnvironmentMissingProjects(t *testing.T) { + f := promotionFixture(t, cliMissingProjectsBody) + got := f.run("promotion", "environment", "missing-projects", cliEnvironmentID) + if got.code != ExitSuccess { + t.Fatalf("exit = %d, stderr: %s", got.code, got.stderr) + } + req := f.lastRequest() + if req.Method != http.MethodGet || req.URL.EscapedPath() != cliEnvironmentPath+"/missing-projects" { + t.Errorf("request = %s %s", req.Method, req.URL.EscapedPath()) + } + for _, want := range []string{"Missing projects:", "p-9", "Ops", "Operations team", cliSelectionSHA, "main"} { + if !strings.Contains(got.stdout, want) { + t.Errorf("stdout missing %q:\n%s", want, got.stdout) + } + } + if !strings.Contains(got.stderr, "n8n project create NAME --id PROJECT_ID") { + t.Errorf("stderr = %s, want the create hint", got.stderr) + } + + got = f.run("promotion", "environment", "missing-projects", cliEnvironmentID, "--output", "json") + if got.code != ExitSuccess || !sameJSON(t, got.stdout, cliMissingProjectsBody) { + t.Errorf("json = %+v", got) + } + + f.body = `{"environmentId":"` + cliEnvironmentID + `","git":null,"data":[]}` + got = f.run("promotion", "environment", "missing-projects", cliEnvironmentID) + if got.code != ExitSuccess || !strings.Contains(got.stdout, "no package yet") || !strings.Contains(got.stderr, "no setup is needed") { + t.Errorf("empty = %+v", got) + } + + before := f.requestCount() + if got = f.run("promotion", "environment", "missing-projects", "conn-1"); got.code == ExitSuccess || f.requestCount() != before { + t.Errorf("invalid ID = %+v", got) + } + + answer := func(status int, body string) { + f.route = func(*http.Request, int) (int, string) { return status, body } + } + answer(http.StatusNotFound, `{"message":"Not Found"}`) + got = f.run("promotion", "environment", "missing-projects", cliEnvironmentID) + if got.code != ExitError || !strings.Contains(got.stderr, "predates n8n 2.47") { + t.Errorf("route 404 = %+v", got) + } + answer(http.StatusNotFound, `{"message":"Promotion environment not found"}`) + got = f.run("promotion", "environment", "missing-projects", cliEnvironmentID) + if got.code != ExitError || !strings.Contains(got.stderr, "has no promotion environment") { + t.Errorf("environment 404 = %+v", got) + } + answer(http.StatusForbidden, `{"message":"Forbidden"}`) + got = f.run("promotion", "environment", "missing-projects", cliEnvironmentID) + if got.code != ExitError || !strings.Contains(got.stderr, "promotions:read") || strings.Contains(got.stderr, "gitConnection") { + t.Errorf("403 = %+v", got) + } +} diff --git a/internal/cli/promotion_environment.go b/internal/cli/promotion_environment.go index 2d4809d..c953e75 100644 --- a/internal/cli/promotion_environment.go +++ b/internal/cli/promotion_environment.go @@ -2,6 +2,7 @@ package cli import ( "bytes" + "cmp" "context" "encoding/json" "fmt" @@ -48,7 +49,7 @@ func newPromotionEnvironmentCommand(opts Options) *cobra.Command { "Sync the whole instance through the connected instance-scope\n" + "environment: 'promote' pushes every team project to a promote\n" + "environment; 'apply' imports an apply environment's branch, and\n" + - "'apply-continue' finishes an apply that preflight blocked. For selected\n" + + "'apply-continue' finishes an apply that its check blocked. For selected\n" + "workflows of one project use 'n8n promotion project changes', 'apply',\n" + "and 'promote'.\n\n" + "Deleting an environment removes its project links and local checkout;\n" + @@ -72,6 +73,7 @@ func newPromotionEnvironmentCommand(opts Options) *cobra.Command { newPromotionEnvironmentConnectCommand(opts), newPromotionEnvironmentDisconnectCommand(opts), newPromotionEnvironmentProjectCommand(opts), + newPromotionEnvironmentMissingProjectsCommand(opts), newPromotionEnvironmentPromoteCommand(opts), newPromotionSelectionCommand(opts, "apply", promotionTargetEnvironment), newPromotionSelectionCommand(opts, "apply-continue", promotionTargetEnvironment), @@ -101,7 +103,7 @@ func newPromotionEnvironmentListCommand(opts Options) *cobra.Command { "are preserved across --all. Use --all to follow every cursor, capped at\n" + "10,000 environments.\n\n" + "Use a returned ID with get, update, delete, connect, disconnect, and\n" + - "project. Requires gitConnection:list.\n\n" + cursorCollectionHelp, + "project. Requires promotions:list (gitConnection:list on n8n 2.46).\n\n" + cursorCollectionHelp, Example: " n8n promotion environment list\n" + " n8n promotion environment list --scope instance --direction apply\n" + " n8n promotion environment list --provider-id PROVIDER_ID --output json\n" + @@ -222,8 +224,8 @@ func newPromotionEnvironmentCreateCommand(opts Options) *cobra.Command { "json' (id, provider, checkout, createdAt, updatedAt,\n" + "remote.repositoryPath) are dropped with a note on stderr; other unknown\n" + "fields and trailing JSON documents are refused before transport.\n" + - "Requires gitConnection:create. Follow with 'n8n promotion environment\n" + - "connect ENVIRONMENT_ID'.", + "Requires promotions:create (gitConnection:create on n8n 2.46). Follow\n" + + "with 'n8n promotion environment connect ENVIRONMENT_ID'.", Example: " n8n promotion environment create --input environment.json\n" + " printf '%s\\n' '{\"name\":\"prod\",\"scope\":\"instance\",\"providerId\":\"PROVIDER_ID\",\"remote\":{\"schemaVersion\":1,\"remoteUrl\":\"git@example.com:org/repo.git\"},\"direction\":\"apply\",\"settings\":{\"schemaVersion\":1,\"branchName\":\"main\"}}' | n8n promotion environment create --input -", Args: cobra.NoArgs, @@ -275,7 +277,8 @@ func newPromotionEnvironmentGetCommand(opts Options) *cobra.Command { "remote, provider, settings, local checkout state, and timestamps.\n" + "Secrets are never returned. Find the ID with 'n8n promotion environment\n" + "list'. The --output json document can be edited and passed to 'update'\n" + - "as is: its read-only fields are dropped. Requires gitConnection:read.", + "as is: its read-only fields are dropped. Requires promotions:read\n" + + "(gitConnection:read on n8n 2.46).", Example: " n8n promotion environment get ENVIRONMENT_ID\n" + " n8n promotion environment get ENVIRONMENT_ID --output json", Args: cobra.ExactArgs(1), @@ -331,7 +334,8 @@ func newPromotionEnvironmentUpdateCommand(opts Options) *cobra.Command { "means the provider changed during the update: reload and retry.\n\n" + "A new remote or branch can leave the local checkout stale, so\n" + "interactive runs ask for confirmation; non-interactive runs and\n" + - "--input - require --yes. Requires gitConnection:update.", + "--input - require --yes. Requires promotions:update\n" + + "(gitConnection:update on n8n 2.46).", Example: " n8n promotion environment update ENVIRONMENT_ID --input environment-update.json\n" + " printf '%s\\n' '{\"name\":\"staging\"}' | n8n promotion environment update ENVIRONMENT_ID --input - --yes\n" + " n8n promotion environment update ENVIRONMENT_ID --input environment.json --yes --output json", @@ -423,7 +427,7 @@ func newPromotionEnvironmentDeleteCommand(opts Options) *cobra.Command { "To keep the environment and drop only the checkout, use 'n8n promotion\n" + "environment disconnect' instead. Interactive runs ask for\n" + "confirmation; non-interactive runs require --yes. Requires\n" + - "gitConnection:delete.", + "promotions:delete (gitConnection:delete on n8n 2.46).", Example: " n8n promotion environment delete ENVIRONMENT_ID\n" + " n8n promotion environment delete ENVIRONMENT_ID --yes --output json", Args: cobra.ExactArgs(1), @@ -475,7 +479,7 @@ func newPromotionEnvironmentConnectCommand(opts Options) *cobra.Command { "Connecting is safe to repeat and changes no project content by itself,\n" + "so it needs no confirmation. Connect again after 'get' reports a\n" + "checkout that does not match the environment. Requires\n" + - "gitConnection:clone.", + "promotions:connect (gitConnection:clone on n8n 2.46).", Example: " n8n promotion environment connect ENVIRONMENT_ID\n" + " n8n promotion environment connect ENVIRONMENT_ID --output json", Args: cobra.ExactArgs(1), @@ -516,7 +520,7 @@ func newPromotionEnvironmentDisconnectCommand(opts Options) *cobra.Command { "project links are kept, but promote and apply through it stop working\n" + "until 'connect' runs again.\n\n" + "Interactive runs ask for confirmation; non-interactive runs require\n" + - "--yes. Requires gitConnection:clone.", + "--yes. Requires promotions:connect (gitConnection:clone on n8n 2.46).", Example: " n8n promotion environment disconnect ENVIRONMENT_ID\n" + " n8n promotion environment disconnect ENVIRONMENT_ID --yes --output json", Args: cobra.ExactArgs(1), @@ -584,8 +588,8 @@ func newPromotionEnvironmentPromoteCommand(opts Options) *cobra.Command { "reject is refused with 409 and nothing is pushed; --force pushes anyway\n" + "and rewrites remote history. This mutates the remote branch.\n" + "Interactive runs ask for confirmation and non-interactive runs require\n" + - "--yes. Requires gitConnection:push, plus variable:list when workflows\n" + - "reference variables.\n\n" + + "--yes. Requires promotions:promote (gitConnection:push on n8n 2.46),\n" + + "plus variable:list when workflows reference variables.\n\n" + "Text shows the commit, branch, counts, and any review the Git host\n" + "opened; JSON is the full result. Advisory warnings go to stderr in both\n" + "formats.\n\n" + @@ -660,8 +664,8 @@ func newPromotionEnvironmentProjectCommand(opts Options) *cobra.Command { "or 'remove' one.\n\n" + "Removing unlinks the project; its instance content is untouched.\n" + "Project IDs come from 'n8n project list'. Listing needs\n" + - "gitConnection:read; adding and removing need\n" + - "gitConnection:manageProjects.", + "promotions:read; adding and removing need promotions:manageProjects\n" + + "(gitConnection:read and gitConnection:manageProjects on n8n 2.46).", Example: " n8n promotion environment project list ENVIRONMENT_ID\n" + " n8n promotion environment project add ENVIRONMENT_ID PROJECT_ID\n" + " n8n promotion environment project remove ENVIRONMENT_ID PROJECT_ID --yes", @@ -683,7 +687,8 @@ func newPromotionEnvironmentProjectListCommand(opts Options) *cobra.Command { Short: "List projects linked to a promotion environment", Long: "List the team projects linked to one projects-scope promotion\n" + "environment. Find the environment ID with 'n8n promotion environment\n" + - "list --scope projects'. Requires gitConnection:read.", + "list --scope projects'. Requires promotions:read (gitConnection:read on\n" + + "n8n 2.46).", Example: " n8n promotion environment project list ENVIRONMENT_ID\n" + " n8n promotion environment project list ENVIRONMENT_ID --output json", Args: cobra.ExactArgs(1), @@ -733,6 +738,81 @@ func runPromotionEnvironmentProjectList(ctx context.Context, opts Options, id st return nil } +func newPromotionEnvironmentMissingProjectsCommand(opts Options) *cobra.Command { + var f promotionEnvironmentConnectFlags + cmd := &cobra.Command{ + Use: "missing-projects ", + Short: "List branch projects missing on this instance (n8n 2.47 and later)", + Long: "Read the package at the branch tip of a connected instance-scope apply\n" + + "environment and list its team projects whose IDs do not exist on this\n" + + "instance. Projects match by ID, not by name; an ID a personal project\n" + + "uses counts as existing. Nothing changes.\n\n" + + "Create each listed project with its ID, e.g. 'n8n project create NAME\n" + + "--id PROJECT_ID', then apply its content with the project apply flow.\n" + + "An empty list means no setup is needed. Find the environment ID with\n" + + "'n8n promotion environment list --scope instance --direction apply' and\n" + + "connect it first with 'n8n promotion environment connect'. The route\n" + + "exists from n8n 2.47. Requires promotions:read.", + Example: " n8n promotion environment missing-projects ENVIRONMENT_ID\n" + + " n8n promotion environment missing-projects ENVIRONMENT_ID --output json", + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + return runPromotionEnvironmentMissingProjects(cmd.Context(), opts, args[0], f) + }, + } + f.instance.register(cmd) + cmd.Flags().StringVar(&f.output, "output", outputText, "output format: text or json (JSON is the server result: environmentId, git, and data)") + return cmd +} + +func runPromotionEnvironmentMissingProjects(ctx context.Context, opts Options, id string, f promotionEnvironmentConnectFlags) error { + if err := validateOutput(f.output); err != nil { + return err + } + if err := validatePromotionEnvironmentArg(id); err != nil { + return err + } + client, resolution, err := opts.apiClient(f.instance) + if err != nil { + return err + } + result, err := client.GetPromotionEnvironmentMissingProjects(ctx, id) + if err != nil { + if n8n.IsNotFound(err) && promotionRouteMissing(err) { + return fmt.Errorf("%s answered 404 for the missing projects of promotion environment %q: either the ID does not exist (check it with 'n8n promotion environment list') or the instance predates n8n 2.47, which added this route; on older instances a blocked 'n8n promotion environment apply' lists the missing projects instead: %w", resolution.URL, id, err) + } + return promotionAPIError(err, resolution, "environment missing-projects", promotionEnvironmentSubject(id)) + } + if f.output == outputJSON { + return writeJSON(opts.Streams.Out, result) + } + tw := tabwriter.NewWriter(opts.Streams.Out, 0, 0, 2, ' ', 0) + fmt.Fprintf(tw, "Environment:\t%s\n", emptyDash(cmp.Or(result.EnvironmentID, id))) + if result.Git != nil { + fmt.Fprintf(tw, "Commit:\t%s\n", emptyDash(result.Git.CommitSHA)) + fmt.Fprintf(tw, "Branch:\t%s\n", emptyDash(result.Git.BranchName)) + } else { + fmt.Fprintln(tw, "Commit:\tnone (the branch has no package yet)") + } + fmt.Fprintf(tw, "Missing projects:\t%d\n", len(result.Data)) + fmt.Fprintf(tw, "Instance:\t%s\n", resolution.URL) + if len(result.Data) > 0 { + fmt.Fprintln(tw, "\nID\tNAME\tDESCRIPTION") + for _, project := range result.Data { + fmt.Fprintf(tw, "%s\t%s\t%s\n", emptyDash(project.ID), emptyDash(project.Name), emptyDash(singleLineText(project.Description))) + } + } + if err := tw.Flush(); err != nil { + return err + } + if len(result.Data) == 0 { + fmt.Fprintln(opts.Streams.Err, "No projects are missing; no setup is needed before applying.") + } else { + fmt.Fprintln(opts.Streams.Err, "Create each missing project with its ID, e.g. 'n8n project create NAME --id PROJECT_ID' (icon, description, and telemetry tags are in --output json), then apply it.") + } + return nil +} + func newPromotionEnvironmentProjectAddCommand(opts Options) *cobra.Command { var f promotionEnvironmentConnectFlags cmd := &cobra.Command{ @@ -742,7 +822,8 @@ func newPromotionEnvironmentProjectAddCommand(opts Options) *cobra.Command { "project-level sync in that direction uses this environment instead of\n" + "the instance environment. A project can have one environment for each\n" + "direction: adding a project that already has one for this direction\n" + - "answers 409. Requires gitConnection:manageProjects.", + "answers 409. Requires promotions:manageProjects\n" + + "(gitConnection:manageProjects on n8n 2.46).", Example: " n8n promotion environment project add ENVIRONMENT_ID PROJECT_ID\n" + " n8n promotion environment project add ENVIRONMENT_ID PROJECT_ID --output json", Args: cobra.ExactArgs(2), @@ -791,7 +872,8 @@ func newPromotionEnvironmentProjectRemoveCommand(opts Options) *cobra.Command { "environment. Re-link it later with 'n8n promotion environment project\n" + "add'.\n\n" + "Interactive runs ask for confirmation; non-interactive runs require\n" + - "--yes. Requires gitConnection:manageProjects.", + "--yes. Requires promotions:manageProjects (gitConnection:manageProjects\n" + + "on n8n 2.46).", Example: " n8n promotion environment project remove ENVIRONMENT_ID PROJECT_ID\n" + " n8n promotion environment project remove ENVIRONMENT_ID PROJECT_ID --yes --output json", Args: cobra.ExactArgs(2), diff --git a/internal/cli/promotion_environment_sync_test.go b/internal/cli/promotion_environment_sync_test.go index 3ffd51d..008a167 100644 --- a/internal/cli/promotion_environment_sync_test.go +++ b/internal/cli/promotion_environment_sync_test.go @@ -366,9 +366,9 @@ func TestPromotionEnvironmentSyncErrorsNameTheFix(t *testing.T) { t.Errorf("%v 403 = %+v, want %s", args, got, scope) } } - for action, want := range map[string]string{"environment apply": "gitConnection:pull", "environment apply-continue": "gitConnection:pull", "environment promote": "gitConnection:push"} { - if got := promotionScope(action); got != want { - t.Errorf("scope(%s) = %s, want %s", action, got, want) + for action, want := range map[string][2]string{"environment apply": {"promotions:apply", "gitConnection:pull"}, "environment apply-continue": {"promotions:apply", "gitConnection:pull"}, "environment promote": {"promotions:promote", "gitConnection:push"}} { + if got := [2]string{promotionScope(action), promotionLegacyScope(action)}; got != want { + t.Errorf("scope(%s) = %v, want %v", action, got, want) } } diff --git a/internal/cli/promotion_selection.go b/internal/cli/promotion_selection.go index 1239c16..5c37cda 100644 --- a/internal/cli/promotion_selection.go +++ b/internal/cli/promotion_selection.go @@ -22,7 +22,8 @@ func newPromotionDiscoveryCommand(opts Options, branches bool) *cobra.Command { } cmd := &cobra.Command{ Use: use, Short: short, - Long: "Discover GitLab repositories or branches using a saved provider with gitConnection:discover.\n" + + Long: "Discover GitLab repositories or branches using a saved provider with promotions:discover\n" + + "(gitConnection:discover before n8n 2.47).\n" + "Start with 'n8n promotion provider list', then repositories, then branches.\n" + "Pass the raw fullPath (for example org/repo) or GitLab project ID to branches;\n" + "the CLI escapes it. Use remoteUrl from repositories as an environment remote\n" + @@ -127,8 +128,9 @@ func newPromotionProjectChangesCommand(opts Options) *cobra.Command { "environment (n8n 2.46 and later) or connection (older) for the direction\n" + "takes precedence over the instance one. Prepare the checkout first: 'n8n\n" + "promotion environment connect' on 2.46, 'n8n promotion checkout clone'\n" + - "before. Apply requires gitConnection:pull; promote requires\n" + - "gitConnection:push. Text lists workflow IDs, statuses, and dependency\n" + + "before. Apply requires promotions:apply; promote requires\n" + + "promotions:promote (gitConnection:pull and gitConnection:push before\n" + + "n8n 2.47). Text lists workflow IDs, statuses, and dependency\n" + "counts; JSON includes changes, source (environmentId on 2.46, configId\n" + "before), and nullable commitSha. On 2.46 a deleted or new promote row can\n" + "be a workflow that moved between projects; promoting it is refused until\n" + @@ -198,6 +200,7 @@ type promotionSelectionFlags struct { workflowIDs []string source n8n.PromotionExpectedSource commit string + previewRevision string yes, destructive bool idempotency idempotencyFlag } @@ -237,7 +240,8 @@ func newPromotionSelectionCommand(opts Options, action, target string) *cobra.Co "branch, with the folders that hold it, which take the branch name; one\n" + "the branch and the instance hold in different projects is refused with\n" + "409 before any write. Unselected content stays unchanged. Duplicate or\n" + - "invalid IDs reject the whole request. Requires gitConnection:pull.\n" + "invalid IDs reject the whole request. Requires promotions:apply\n" + + "(gitConnection:pull before n8n 2.47).\n" switch { case target == promotionTargetConnection: long = "Continue a full instance-connection apply after resolving its preflight items.\n" + @@ -248,12 +252,12 @@ func newPromotionSelectionCommand(opts Options, action, target string) *cobra.Co "Requires gitConnection:pull and the same permissions as the initial apply.\n" case environment && isContinue: long = "Continue a full environment apply (n8n 2.46 and later) after resolving its\n" + - "preflight items. Start with 'n8n promotion environment apply ENVIRONMENT_ID\n" + + "check items. Start with 'n8n promotion environment apply ENVIRONMENT_ID\n" + "--output json'. The instance-scope apply environment must still be\n" + "connected. Every team project is synchronized: workflows, folders,\n" + "credentials, tables, variables, and tags can be created, updated, moved,\n" + - "renamed, or removed to match. Requires gitConnection:pull and the same\n" + - "permissions as the initial apply.\n\n" + "renamed, or removed to match. Requires promotions:apply (gitConnection:pull\n" + + "before n8n 2.47) and the same permissions as the initial apply.\n\n" case environment: long = "Check the full package at the branch tip of an instance-scope apply\n" + "environment (n8n 2.46 and later) and import it into the instance,\n" + @@ -267,7 +271,7 @@ func newPromotionSelectionCommand(opts Options, action, target string) *cobra.Co "folders take the branch name, and credential gaps become stubs.\n" + "Existing variable values are kept. A workflow or folder the branch and\n" + "the instance hold in different projects is refused with 409 before any\n" + - "write. Requires gitConnection:pull.\n\n" + "write. Requires promotions:apply (gitConnection:pull before n8n 2.47).\n\n" } if isPromote { long = "Start with 'n8n promotion project changes PROJECT_ID promote' to review IDs.\n" + @@ -279,7 +283,8 @@ func newPromotionSelectionCommand(opts Options, action, target string) *cobra.Co "leave the branch. On 2.46 a workflow that moved into or out of the\n" + "project since the branch was written is refused with 400; move it back\n" + "first. Unknown deletions reject the whole request. Requires\n" + - "gitConnection:push, plus variable:list when workflows use variables.\n" + + "promotions:promote (gitConnection:push before n8n 2.47), plus\n" + + "variable:list when workflows use variables.\n" + "Commit message is optional; the server supplies a default. Force pushing\n" + "is not supported. The result can name a review the Git host opened;\n" + "advisory warnings go to stderr.\n" @@ -314,10 +319,24 @@ func newPromotionSelectionCommand(opts Options, action, target string) *cobra.Co } else { long += "Expected source is optional; supply it to detect changes after review.\n" } - long += "Exit codes: 0 applied, 3 blocked, 4 source-changed, 1 other error. Only\n" + - "applied writes content. Resolve blocked bindings before apply-continue;\n" + - "review source-changed results again. JSON prints the full status result;\n" + - "text shows preflight details or counts and warnings. Hints go to stderr.\n" + if project { + long += "--expected-preview-revision (n8n 2.47 and later) pins the reviewed Apply\n" + + "preview; when this instance changed since, the server answers\n" + + "preview-changed and writes nothing. Older instances reject it.\n" + } + if target == promotionTargetConnection { + long += "Exit codes: 0 applied, 3 blocked, 4 source-changed, 1 other error. Only\n" + + "applied writes content. Resolve blocked bindings before apply-continue;\n" + + "review source-changed results again. JSON prints the full status result;\n" + + "text shows preflight details or counts and warnings. Hints go to stderr.\n" + } else { + long += "Exit codes: 0 applied, 3 blocked, 4 source-changed or preview-changed\n" + + "(n8n 2.47 and later), 1 other error. Only applied writes content.\n" + + "Resolve blocked items before apply-continue; review source-changed and\n" + + "preview-changed results again. JSON prints the full status result; text\n" + + "shows the blocking check (preflight before n8n 2.47) or counts and\n" + + "warnings. Hints go to stderr.\n" + } } if project { long += "\nPass repeated --workflow-id flags, or use a strict JSON request.\n" @@ -371,6 +390,10 @@ func newPromotionSelectionCommand(opts Options, action, target string) *cobra.Co cmd.Flags().StringVar(&f.source.BranchName, "expected-branch", "", "reviewed branch name (default: omitted; requires the expected ID and commit)") cmd.Flags().StringVar(&f.source.CommitSHA, "expected-commit", "", "reviewed lowercase full 40- or 64-digit hex commit SHA (default: omitted; requires the expected ID and branch)") documentFlags = append(documentFlags, "expected-branch", "expected-commit") + if project { + cmd.Flags().StringVar(&f.previewRevision, "expected-preview-revision", "", "revision of the reviewed Apply preview, 64 lowercase hex digits; a changed preview answers preview-changed and writes nothing (n8n 2.47 and later; default: omitted)") + documentFlags = append(documentFlags, "expected-preview-revision") + } } if isContinue { cmd.Flags().BoolVar(&f.destructive, "confirm-destructive-changes", false, "allow all destructive changes at continue time, including unreviewed column value loss and, for full apply, team-project deletion (default: false)") @@ -436,7 +459,7 @@ func newPromotionSelectionCommand(opts Options, action, target string) *cobra.Co } request = r case isContinue && project: - r := &n8n.ContinueApplyProjectSelectionRequest{WorkflowIDs: f.workflowIDs, ConfirmDestructiveChanges: destructive} + r := &n8n.ContinueApplyProjectSelectionRequest{WorkflowIDs: f.workflowIDs, ExpectedPreviewRevision: f.previewRevision, ConfirmDestructiveChanges: destructive} if source != nil { r.ExpectedSource = *source } @@ -456,7 +479,7 @@ func newPromotionSelectionCommand(opts Options, action, target string) *cobra.Co case environment: request = &n8n.ApplyPromotionEnvironmentRequest{ExpectedSource: source} default: - request = &n8n.ApplyProjectSelectionRequest{WorkflowIDs: f.workflowIDs, ExpectedSource: source} + request = &n8n.ApplyProjectSelectionRequest{WorkflowIDs: f.workflowIDs, ExpectedSource: source, ExpectedPreviewRevision: f.previewRevision} } if f.input != "" { if err := readPromotionDocument(opts, f.input, request); err != nil { diff --git a/internal/cli/promotion_selection_test.go b/internal/cli/promotion_selection_test.go index cb38d05..4208dd2 100644 --- a/internal/cli/promotion_selection_test.go +++ b/internal/cli/promotion_selection_test.go @@ -298,9 +298,18 @@ func TestPromotionSelectionInvalidArgumentsAndScopes(t *testing.T) { t.Errorf("args=%v result=%+v", args, got) } } - for action, want := range map[string]string{"project changes apply": "gitConnection:pull", "project changes promote": "gitConnection:push", "project apply": "gitConnection:pull", "project apply-continue": "gitConnection:pull", "apply-continue": "gitConnection:pull", "project promote": "gitConnection:push", "provider repositories": "gitConnection:discover", "provider branches": "gitConnection:discover"} { - if got := promotionScope(action); got != want { - t.Errorf("%s=%s want %s", action, got, want) + for action, want := range map[string][2]string{ + "project changes apply": {"promotions:apply", "gitConnection:pull"}, + "project changes promote": {"promotions:promote", "gitConnection:push"}, + "project apply": {"promotions:apply", "gitConnection:pull"}, + "project apply-continue": {"promotions:apply", "gitConnection:pull"}, + "apply-continue": {"gitConnection:pull", "gitConnection:pull"}, + "project promote": {"promotions:promote", "gitConnection:push"}, + "provider repositories": {"promotions:discover", "gitConnection:discover"}, + "provider branches": {"promotions:discover", "gitConnection:discover"}, + } { + if got := [2]string{promotionScope(action), promotionLegacyScope(action)}; got != want { + t.Errorf("%s=%v want %v", action, got, want) } } for _, tc := range []struct { diff --git a/internal/cli/rate_limit.go b/internal/cli/rate_limit.go new file mode 100644 index 0000000..afcb192 --- /dev/null +++ b/internal/cli/rate_limit.go @@ -0,0 +1,323 @@ +package cli + +import ( + "bytes" + "context" + "encoding/json" + "fmt" + "io" + "net/http" + "os" + "strconv" + "strings" + "text/tabwriter" + "unicode" + + "github.com/spf13/cobra" + + "github.com/SomeoneWithOptions/n8n-cli/internal/config" + "github.com/SomeoneWithOptions/n8n-cli/internal/n8n" +) + +const ( + rateLimitResource = "settingsratelimits" + maxRateLimitDocument = 1 << 20 + rateLimitEnabledFlag = "enabled" +) + +func newRateLimitCommand(opts Options) *cobra.Command { + cmd := &cobra.Command{ + Use: "rate-limit", + Short: "Manage Public API rate limits", + Long: "Read or replace the Public API rate-limit settings: whether limiting is on,\n" + + "and per-API-key read and write limits across all endpoints (global) and on\n" + + "one endpoint, each with its own window in seconds. A limit of 0 means no\n" + + "limit. Requests to these routes count against the limits too.\n\n" + + "Fields set by environment variables are listed in envManagedFields: they\n" + + "report their effective value and cannot be changed through the API.\n" + + "Requires securitySettings:manage and n8n 2.47 or later.", + Example: " n8n rate-limit get\n" + + " n8n rate-limit get --output json > rate-limits.json\n" + + " n8n rate-limit set --input rate-limits.json --global-write-limit 60", + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { return cmd.Help() }, + } + cmd.AddCommand( + newRateLimitGetCommand(opts), + newRateLimitSetCommand(opts), + ) + return cmd +} + +type rateLimitGetFlags struct { + instance instanceFlags + output string +} + +func newRateLimitGetCommand(opts Options) *cobra.Command { + var f rateLimitGetFlags + cmd := &cobra.Command{ + Use: "get", + Short: "Get Public API rate-limit settings", + Long: "Get the effective Public API rate-limit settings and the fields environment\n" + + "variables manage. --output json is the starting point for 'set --input': it\n" + + "round-trips, and set drops the read-only envManagedFields before sending.\n\n" + + "Requires securitySettings:manage and n8n 2.47 or later.", + Example: " n8n rate-limit get\n" + + " n8n rate-limit get --output json\n" + + " n8n rate-limit get --output json > rate-limits.json", + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + return runRateLimitGet(cmd.Context(), opts, f) + }, + } + f.instance.register(cmd) + cmd.Flags().StringVar(&f.output, "output", outputText, "output format: text or json (JSON is the complete settings document with envManagedFields)") + return cmd +} + +func runRateLimitGet(ctx context.Context, opts Options, f rateLimitGetFlags) error { + if err := validateOutput(f.output); err != nil { + return err + } + client, resolution, err := opts.apiClient(f.instance) + if err != nil { + return err + } + settings, err := client.GetRateLimitSettings(ctx) + if err != nil { + return rateLimitAPIError(err, resolution, "read") + } + return writeRateLimitSettings(opts, resolution, "Rate-limit settings", settings, f.output) +} + +type rateLimitSetFlags struct { + instance instanceFlags + input string + enabled bool + ints map[string]*int + yes bool + output string +} + +// rateLimitFlagName is the kebab-case flag for a JSON field, e.g. +// globalReadWindowSeconds becomes global-read-window-seconds. +func rateLimitFlagName(field string) string { + var b strings.Builder + for _, r := range field { + if unicode.IsUpper(r) { + b.WriteByte('-') + r = unicode.ToLower(r) + } + b.WriteRune(r) + } + return b.String() +} + +func newRateLimitSetCommand(opts Options) *cobra.Command { + f := rateLimitSetFlags{ints: map[string]*int{}} + cmd := &cobra.Command{ + Use: "set", + Short: "Fully replace Public API rate-limit settings", + Long: "Fully replace the Public API rate-limit settings. This is a PUT, not a patch:\n" + + "enabled and all eight limit and window fields are required. Take them from\n" + + "--input (start from 'n8n rate-limit get --output json'), from flags, or both;\n" + + "a flag overrides the --input value. Limits are request counts per API key,\n" + + "at least 0 (0 for no limit); windows are seconds, at least 1. When limiting\n" + + "is enabled, at least one limit must be above 0.\n\n" + + "envManagedFields in --input is read-only: it is dropped before sending and\n" + + "reported on stderr. Fields set by environment variables can be repeated with\n" + + "their current value but not changed; a different value answers 409 and\n" + + "nothing changes.\n\n" + + "New limits apply at once to every API key, including the one this CLI uses,\n" + + "so interactive runs ask for confirmation and non-interactive runs require\n" + + "--yes. --input - also requires --yes because stdin cannot hold both JSON and\n" + + "a confirmation answer. Requires securitySettings:manage and n8n 2.47 or later.", + Example: " n8n rate-limit get --output json > rate-limits.json\n" + + " n8n rate-limit set --input rate-limits.json --global-write-limit 60\n" + + " n8n rate-limit set --input - --yes < rate-limits.json\n" + + " n8n rate-limit set --enabled=false --global-read-limit 0 --global-read-window-seconds 60 \\\n" + + " --global-write-limit 0 --global-write-window-seconds 60 --endpoint-read-limit 0 \\\n" + + " --endpoint-read-window-seconds 60 --endpoint-write-limit 0 --endpoint-write-window-seconds 60 --yes", + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + changed := map[string]bool{rateLimitEnabledFlag: cmd.Flags().Changed(rateLimitEnabledFlag)} + for _, field := range n8n.RateLimitIntFields { + changed[field.Name] = cmd.Flags().Changed(rateLimitFlagName(field.Name)) + } + return runRateLimitSet(cmd.Context(), opts, f, changed) + }, + } + f.instance.register(cmd) + cmd.Flags().StringVar(&f.input, "input", "", "full rate-limit settings JSON file path, or - for stdin, e.g. from 'n8n rate-limit get --output json' (default: none; flags supply every field; maximum 1 MiB)") + cmd.Flags().BoolVar(&f.enabled, rateLimitEnabledFlag, false, "turn Public API rate limiting on or off; true or false, overrides enabled in --input (default: the --input value)") + for _, field := range n8n.RateLimitIntFields { + value := new(int) + f.ints[field.Name] = value + usage := "requests allowed per API key in the window, 0 for no limit" + if field.Window { + usage = "window in seconds, at least 1" + } + cmd.Flags().IntVar(value, rateLimitFlagName(field.Name), 0, fmt.Sprintf("%s; overrides %s in --input (default: the --input value)", usage, field.Name)) + } + cmd.Flags().BoolVar(&f.yes, "yes", false, "confirm replacing the limits, which apply at once to every API key, without prompting (required when stdin is not interactive)") + cmd.Flags().StringVar(&f.output, "output", outputText, "output format: text or json (JSON is the effective settings returned after replacement)") + return cmd +} + +// rateLimitInput is the --input document: the writable fields plus the +// read-only envManagedFields a GET returns, accepted so the GET output +// round-trips and then dropped. +type rateLimitInput struct { + n8n.UpdateRateLimitSettingsRequest + EnvManagedFields json.RawMessage `json:"envManagedFields"` +} + +func runRateLimitSet(ctx context.Context, opts Options, f rateLimitSetFlags, changed map[string]bool) error { + if err := validateOutput(f.output); err != nil { + return err + } + if f.input == "-" && !f.yes { + return fmt.Errorf("--input - consumes stdin and cannot answer the replacement confirmation: pass --yes after reviewing the settings") + } + var input rateLimitInput + if f.input != "" { + if err := readRateLimitDocument(opts, f.input, &input); err != nil { + return err + } + if input.EnvManagedFields != nil { + fmt.Fprintln(opts.Streams.Err, "Dropped read-only field envManagedFields.") + } + } + request := input.UpdateRateLimitSettingsRequest + if changed[rateLimitEnabledFlag] { + request.Enabled = &f.enabled + } + for _, field := range n8n.RateLimitIntFields { + if changed[field.Name] { + *request.Int(field.Name) = f.ints[field.Name] + } + } + if err := rateLimitMissingField(request, f.input); err != nil { + return err + } + if err := request.Validate(); err != nil { + return err + } + client, resolution, err := opts.apiClient(f.instance) + if err != nil { + return err + } + question := fmt.Sprintf("Fully replace the Public API rate-limit settings on %s? The new limits apply at once to every API key, including the one this CLI uses.", resolution.URL) + if err := opts.confirmer(f.yes).Confirm(question); err != nil { + return err + } + settings, err := client.UpdateRateLimitSettings(ctx, request) + if err != nil { + return rateLimitAPIError(err, resolution, "update") + } + return writeRateLimitSettings(opts, resolution, "Updated rate-limit settings", settings, f.output) +} + +// rateLimitMissingField names the first required field neither --input nor a +// flag supplied, with the flag that fixes it. +func rateLimitMissingField(request n8n.UpdateRateLimitSettingsRequest, input string) error { + missing := "" + if request.Enabled == nil { + missing = rateLimitEnabledFlag + } else { + for _, field := range n8n.RateLimitIntFields { + if *request.Int(field.Name) == nil { + missing = field.Name + break + } + } + } + if missing == "" { + return nil + } + source := "no --input was given" + if input != "" { + source = "--input omits it" + } + return fmt.Errorf("%s is required and %s: pass --%s, or start from 'n8n rate-limit get --output json' and pass it with --input", missing, source, rateLimitFlagName(missing)) +} + +func readRateLimitDocument(opts Options, path string, dst *rateLimitInput) error { + reader := opts.Streams.In + if path != "-" { + file, err := os.Open(path) + if err != nil { + return fmt.Errorf("open rate-limit settings input %q: %w", path, err) + } + defer file.Close() + reader = file + } + raw, err := io.ReadAll(io.LimitReader(reader, maxRateLimitDocument+1)) + if err != nil { + return fmt.Errorf("read rate-limit settings JSON: %w", err) + } + if len(raw) > maxRateLimitDocument { + return fmt.Errorf("rate-limit settings JSON exceeds %d bytes", maxRateLimitDocument) + } + decoder := json.NewDecoder(bytes.NewReader(raw)) + decoder.DisallowUnknownFields() + if err := decoder.Decode(dst); err != nil { + return fmt.Errorf("decode rate-limit settings JSON: %w", err) + } + var extra any + if err := decoder.Decode(&extra); err != io.EOF { + if err == nil { + return fmt.Errorf("decode rate-limit settings JSON: multiple documents are not allowed") + } + return fmt.Errorf("decode rate-limit settings JSON: %w", err) + } + return nil +} + +func writeRateLimitSettings(opts Options, resolution config.Resolution, heading string, settings *n8n.RateLimitSettings, output string) error { + if output == outputJSON { + return writeJSON(opts.Streams.Out, settings) + } + tw := tabwriter.NewWriter(opts.Streams.Out, 0, 0, 2, ' ', 0) + fmt.Fprintf(tw, "%s:\t%s\n", heading, resolution.URL) + fmt.Fprintf(tw, "Enabled:\t%s\n", yesNo(settings.Enabled)) + managed := "none" + if len(settings.EnvManagedFields) > 0 { + managed = strings.Join(settings.EnvManagedFields, ", ") + } + fmt.Fprintf(tw, "Env-managed fields:\t%s\n", managed) + fmt.Fprintln(tw, "\nSCOPE\tACCESS\tLIMIT\tWINDOW") + rows := []struct { + scope, access string + limit, window int + }{ + {"global", "read", settings.GlobalReadLimit, settings.GlobalReadWindowSeconds}, + {"global", "write", settings.GlobalWriteLimit, settings.GlobalWriteWindowSeconds}, + {"endpoint", "read", settings.EndpointReadLimit, settings.EndpointReadWindowSeconds}, + {"endpoint", "write", settings.EndpointWriteLimit, settings.EndpointWriteWindowSeconds}, + } + for _, row := range rows { + limit := "none" + if row.limit > 0 { + limit = strconv.Itoa(row.limit) + } + fmt.Fprintf(tw, "%s\t%s\t%s\t%ds\n", row.scope, row.access, limit, row.window) + } + return tw.Flush() +} + +func rateLimitAPIError(err error, resolution config.Resolution, action string) error { + switch { + case n8n.IsStatus(err, http.StatusBadRequest) && action == "update": + return fmt.Errorf("%s rejected the full rate-limit replacement (400): send enabled and all eight limit and window fields, limits at least 0, windows at least 1, and at least one limit above 0 when enabled: %w", resolution.URL, err) + case n8n.IsConflict(err) && action == "update": + return fmt.Errorf("%s refused the rate-limit update (409): a field set by environment variables has a different value, so nothing changed; repeat the current values of the fields 'n8n rate-limit get' lists as env-managed, or change the environment configuration and restart n8n: %w", resolution.URL, err) + case n8n.IsForbidden(err): + return forbiddenScopeError(err, resolution, "rate-limit settings "+action, allOf("securitySettings:manage"), "", rateLimitResource) + case n8n.IsNotFound(err): + return fmt.Errorf("%s does not serve Public API rate-limit settings (404): they need n8n 2.47 or later; run %s to see what this instance offers: %w", resolution.URL, discoverHint(rateLimitResource), err) + default: + return apiError(err, resolution, rateLimitResource) + } +} diff --git a/internal/cli/rate_limit_test.go b/internal/cli/rate_limit_test.go new file mode 100644 index 0000000..cf1b51f --- /dev/null +++ b/internal/cli/rate_limit_test.go @@ -0,0 +1,218 @@ +package cli + +import ( + "encoding/json" + "net/http" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/SomeoneWithOptions/n8n-cli/internal/n8n" +) + +const cliRateLimitSettings = `{ + "enabled":true, + "globalReadLimit":600, + "globalReadWindowSeconds":60, + "globalWriteLimit":120, + "globalWriteWindowSeconds":60, + "endpointReadLimit":0, + "endpointReadWindowSeconds":60, + "endpointWriteLimit":30, + "endpointWriteWindowSeconds":10, + "envManagedFields":["globalReadLimit"] +}` + +const cliRateLimitInput = `{"enabled":true,"globalReadLimit":600,"globalReadWindowSeconds":60,"globalWriteLimit":120,"globalWriteWindowSeconds":60,"endpointReadLimit":0,"endpointReadWindowSeconds":60,"endpointWriteLimit":30,"endpointWriteWindowSeconds":10}` + +func rateLimitFixture(t *testing.T) *fixture { + t.Helper() + f := newFixture(t) + f.login() + f.body = cliRateLimitSettings + return f +} + +func writeRateLimitInput(t *testing.T, body string) string { + t.Helper() + path := filepath.Join(t.TempDir(), "rate-limits.json") + if err := os.WriteFile(path, []byte(body), 0o600); err != nil { + t.Fatalf("WriteFile: %v", err) + } + return path +} + +func TestRateLimitGetText(t *testing.T) { + f := rateLimitFixture(t) + got := f.run("rate-limit", "get") + if got.code != ExitSuccess { + t.Fatalf("exit = %d, stderr: %s", got.code, got.stderr) + } + for _, want := range []string{ + "Rate-limit settings:", f.server.URL, "Enabled:", "yes", "Env-managed fields:", "globalReadLimit", + "SCOPE", "global", "read", "600", "60s", "endpoint", "write", "30", "10s", "none", + } { + if !strings.Contains(got.stdout, want) { + t.Errorf("stdout missing %q:\n%s", want, got.stdout) + } + } + req := f.lastRequest() + if req.Method != http.MethodGet || req.URL.EscapedPath() != n8n.BasePath+n8n.RateLimitSettingsPath || f.lastBody() != "" { + t.Errorf("request = %s %s body %q", req.Method, req.URL.EscapedPath(), f.lastBody()) + } +} + +func TestRateLimitGetJSONRoundTripsIntoSet(t *testing.T) { + f := rateLimitFixture(t) + got := f.run("rate-limit", "get", "--output", "json") + if got.code != ExitSuccess { + t.Fatalf("exit = %d, stderr: %s", got.code, got.stderr) + } + var settings n8n.RateLimitSettings + if err := json.Unmarshal([]byte(got.stdout), &settings); err != nil { + t.Fatalf("stdout is not settings JSON: %v\n%s", err, got.stdout) + } + f.stdin = got.stdout + set := f.run("rate-limit", "set", "--input", "-", "--yes", "--endpoint-write-limit", "45") + if set.code != ExitSuccess { + t.Fatalf("set exit = %d, stderr: %s", set.code, set.stderr) + } + if !strings.Contains(set.stderr, "Dropped read-only field envManagedFields.") { + t.Errorf("stderr does not report the dropped field: %s", set.stderr) + } + if !strings.Contains(set.stdout, "Updated rate-limit settings:") { + t.Errorf("stdout = %s", set.stdout) + } + req := f.lastRequest() + if req.Method != http.MethodPut || req.URL.EscapedPath() != n8n.BasePath+n8n.RateLimitSettingsPath { + t.Errorf("request = %s %s", req.Method, req.URL.EscapedPath()) + } + var sent map[string]any + if err := json.Unmarshal([]byte(f.lastBody()), &sent); err != nil { + t.Fatalf("body is not JSON: %v", err) + } + if _, ok := sent["envManagedFields"]; ok { + t.Error("read-only envManagedFields was sent") + } + if len(sent) != 9 || sent["endpointWriteLimit"] != float64(45) || sent["globalReadLimit"] != float64(600) { + t.Errorf("body = %s", f.lastBody()) + } +} + +func TestRateLimitSetFromFlagsOnly(t *testing.T) { + f := rateLimitFixture(t) + got := f.run("rate-limit", "set", "--yes", "--output", "json", "--enabled=false", + "--global-read-limit", "0", "--global-read-window-seconds", "60", + "--global-write-limit", "0", "--global-write-window-seconds", "60", + "--endpoint-read-limit", "0", "--endpoint-read-window-seconds", "60", + "--endpoint-write-limit", "0", "--endpoint-write-window-seconds", "60") + if got.code != ExitSuccess { + t.Fatalf("exit = %d, stderr: %s", got.code, got.stderr) + } + var sent map[string]any + if err := json.Unmarshal([]byte(f.lastBody()), &sent); err != nil { + t.Fatalf("body is not JSON: %v", err) + } + if sent["enabled"] != false || len(sent) != 9 { + t.Errorf("body = %s", f.lastBody()) + } + if got.stderr != "" { + t.Errorf("stderr = %q, want empty", got.stderr) + } +} + +func TestRateLimitSetRequiresConfirmation(t *testing.T) { + f := rateLimitFixture(t) + path := writeRateLimitInput(t, cliRateLimitInput) + before := f.requestCount() + + f.stdin = "n\n" + got := f.run("rate-limit", "set", "--input", path) + if got.code != ExitError || !strings.Contains(got.stderr, "aborted") { + t.Fatalf("declined result = %+v", got) + } + if !strings.Contains(got.stderr, "including the one this CLI uses") { + t.Errorf("confirmation lacks the warning: %s", got.stderr) + } + if f.requestCount() != before { + t.Error("declined replacement reached instance") + } + + f.stdin = "yes\n" + got = f.run("rate-limit", "set", "--input", path) + if got.code != ExitSuccess { + t.Fatalf("confirmed exit = %d, stderr: %s", got.code, got.stderr) + } + if f.lastRequest().Method != http.MethodPut { + t.Errorf("method = %s, want PUT", f.lastRequest().Method) + } +} + +func TestRateLimitSetValidationBeforeTransport(t *testing.T) { + tests := []struct { + name string + input string + args []string + want string + }{ + {name: "nothing given", args: []string{"rate-limit", "set", "--yes"}, want: "enabled is required and no --input was given: pass --enabled"}, + {name: "stdin without yes", input: cliRateLimitInput, args: []string{"rate-limit", "set", "--input", "-"}, want: "consumes stdin"}, + {name: "unknown output", input: cliRateLimitInput, args: []string{"rate-limit", "set", "--input", "-", "--yes", "--output", "yaml"}, want: "unknown output format"}, + {name: "malformed", input: `{`, args: []string{"rate-limit", "set", "--input", "-", "--yes"}, want: "decode rate-limit settings JSON"}, + {name: "unknown field", input: `{"enabled":true,"surprise":1}`, args: []string{"rate-limit", "set", "--input", "-", "--yes"}, want: "unknown field"}, + {name: "trailing document", input: cliRateLimitInput + ` {}`, args: []string{"rate-limit", "set", "--input", "-", "--yes"}, want: "multiple documents"}, + {name: "input omits field", input: `{"enabled":true,"globalReadLimit":1}`, args: []string{"rate-limit", "set", "--input", "-", "--yes"}, want: "globalReadWindowSeconds is required and --input omits it: pass --global-read-window-seconds"}, + {name: "negative limit flag", input: cliRateLimitInput, args: []string{"rate-limit", "set", "--input", "-", "--yes", "--global-write-limit", "-1"}, want: "globalWriteLimit must be at least 0"}, + {name: "zero window flag", input: cliRateLimitInput, args: []string{"rate-limit", "set", "--input", "-", "--yes", "--endpoint-read-window-seconds", "0"}, want: "endpointReadWindowSeconds must be at least 1"}, + {name: "enabled without limits", input: `{"enabled":true,"globalReadLimit":0,"globalReadWindowSeconds":60,"globalWriteLimit":0,"globalWriteWindowSeconds":60,"endpointReadLimit":0,"endpointReadWindowSeconds":60,"endpointWriteLimit":0,"endpointWriteWindowSeconds":60}`, args: []string{"rate-limit", "set", "--input", "-", "--yes"}, want: "every limit is 0"}, + {name: "oversized", input: strings.Repeat("x", maxRateLimitDocument+1), args: []string{"rate-limit", "set", "--input", "-", "--yes"}, want: "exceeds"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + f := rateLimitFixture(t) + f.stdin = tt.input + before := f.requestCount() + got := f.run(tt.args...) + if got.code != ExitError || !strings.Contains(got.stderr, tt.want) { + t.Errorf("result = %+v, want error containing %q", got, tt.want) + } + if f.requestCount() != before { + t.Error("invalid rate-limit request reached instance") + } + }) + } +} + +func TestRateLimitAPIErrorsStateTheFix(t *testing.T) { + setArgs := []string{"rate-limit", "set", "--input", "-", "--yes"} + tests := []struct { + name string + status int + args []string + want []string + }{ + {name: "get forbidden", status: http.StatusForbidden, args: []string{"rate-limit", "get"}, want: []string{"securitySettings:manage", "discover --resource settingsratelimits"}}, + {name: "set forbidden", status: http.StatusForbidden, args: setArgs, want: []string{"securitySettings:manage"}}, + {name: "env managed conflict", status: http.StatusConflict, args: setArgs, want: []string{"409", "environment variables", "nothing changed", "rate-limit get"}}, + {name: "invalid replacement", status: http.StatusBadRequest, args: setArgs, want: []string{"full rate-limit replacement", "at least one limit above 0"}}, + {name: "older instance", status: http.StatusNotFound, args: []string{"rate-limit", "get"}, want: []string{"n8n 2.47 or later", "discover --resource settingsratelimits"}}, + {name: "unauthorized", status: http.StatusUnauthorized, args: []string{"rate-limit", "get"}, want: []string{"rejected the credential", "auth login"}}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + f := rateLimitFixture(t) + f.status = tt.status + f.stdin = cliRateLimitInput + got := f.run(tt.args...) + if got.code != ExitError { + t.Fatalf("exit = %d, stderr: %s", got.code, got.stderr) + } + for _, want := range tt.want { + if !strings.Contains(got.stderr, want) { + t.Errorf("stderr missing %q: %s", want, got.stderr) + } + } + }) + } +} diff --git a/internal/coverage/coverage_test.go b/internal/coverage/coverage_test.go index 7b6aad9..56885c7 100644 --- a/internal/coverage/coverage_test.go +++ b/internal/coverage/coverage_test.go @@ -327,7 +327,7 @@ func TestAvailabilityMatchesSpecs(t *testing.T) { // // A phase is never excused because one server does not serve its resource: // every phase owns operations from the union of the documents. -const deliveredThrough = 36 +const deliveredThrough = 38 // TestPhaseCounts is how a phase exit gate reads the manifest: every operation // a delivered phase owns must be implemented, and no later phase may have diff --git a/internal/coverage/manifest.json b/internal/coverage/manifest.json index 30e0a45..2971348 100644 --- a/internal/coverage/manifest.json +++ b/internal/coverage/manifest.json @@ -1339,7 +1339,7 @@ "method": "POST", "path": "/n8n-packages/import", "tag": "N8nPackage", - "scope": "workflow:import", + "scope": "workflow:import,agent:import", "availability": "both", "phase": 27, "command": "n8n package import", @@ -1691,7 +1691,7 @@ "method": "GET", "path": "/promotions/providers", "tag": "Promotions", - "scope": "gitConnection:list", + "scope": "promotions:list", "availability": "both", "phase": 29, "command": "n8n promotion provider list", @@ -1702,7 +1702,7 @@ "method": "POST", "path": "/promotions/providers", "tag": "Promotions", - "scope": "gitConnection:create", + "scope": "promotions:create", "availability": "both", "phase": 29, "command": "n8n promotion provider create", @@ -1713,7 +1713,7 @@ "method": "DELETE", "path": "/promotions/providers/{promotionProviderId}", "tag": "Promotions", - "scope": "gitConnection:delete", + "scope": "promotions:delete", "availability": "both", "phase": 29, "command": "n8n promotion provider delete", @@ -1724,7 +1724,7 @@ "method": "GET", "path": "/promotions/providers/{promotionProviderId}", "tag": "Promotions", - "scope": "gitConnection:read", + "scope": "promotions:read", "availability": "both", "phase": 29, "command": "n8n promotion provider get", @@ -1735,7 +1735,7 @@ "method": "PUT", "path": "/promotions/providers/{promotionProviderId}", "tag": "Promotions", - "scope": "gitConnection:update", + "scope": "promotions:update", "availability": "both", "phase": 29, "command": "n8n promotion provider update", @@ -1757,7 +1757,7 @@ "method": "GET", "path": "/promotions/projects/{projectId}/changes/{direction}", "tag": "Promotions", - "scope": "gitConnection:push,gitConnection:pull", + "scope": "promotions:promote,promotions:apply", "availability": "both", "phase": 31, "command": "n8n promotion project changes", @@ -1779,7 +1779,7 @@ "method": "POST", "path": "/promotions/projects/{projectId}/apply", "tag": "Promotions", - "scope": "gitConnection:pull", + "scope": "promotions:apply", "availability": "both", "phase": 31, "command": "n8n promotion project apply", @@ -1790,7 +1790,7 @@ "method": "POST", "path": "/promotions/projects/{projectId}/apply/continue", "tag": "Promotions", - "scope": "gitConnection:pull", + "scope": "promotions:apply", "availability": "both", "phase": 31, "command": "n8n promotion project apply-continue", @@ -1801,7 +1801,7 @@ "method": "POST", "path": "/promotions/projects/{projectId}/promote", "tag": "Promotions", - "scope": "gitConnection:push", + "scope": "promotions:promote", "availability": "both", "phase": 31, "command": "n8n promotion project promote", @@ -1812,7 +1812,7 @@ "method": "GET", "path": "/promotions/providers/{promotionProviderId}/repositories", "tag": "Promotions", - "scope": "gitConnection:discover", + "scope": "promotions:discover", "availability": "upstream-only", "phase": 31, "command": "n8n promotion provider repositories", @@ -1823,7 +1823,7 @@ "method": "GET", "path": "/promotions/providers/{promotionProviderId}/repositories/{repositoryId}/branches", "tag": "Promotions", - "scope": "gitConnection:discover", + "scope": "promotions:discover", "availability": "upstream-only", "phase": 31, "command": "n8n promotion provider branches", @@ -2065,7 +2065,7 @@ "method": "GET", "path": "/promotions/environments", "tag": "Promotions", - "scope": "gitConnection:list", + "scope": "promotions:list", "availability": "upstream-only", "phase": 35, "command": "n8n promotion environment list", @@ -2076,7 +2076,7 @@ "method": "POST", "path": "/promotions/environments", "tag": "Promotions", - "scope": "gitConnection:create", + "scope": "promotions:create", "availability": "upstream-only", "phase": 35, "command": "n8n promotion environment create", @@ -2087,7 +2087,7 @@ "method": "GET", "path": "/promotions/environments/{promotionEnvironmentId}", "tag": "Promotions", - "scope": "gitConnection:read", + "scope": "promotions:read", "availability": "upstream-only", "phase": 35, "command": "n8n promotion environment get", @@ -2098,7 +2098,7 @@ "method": "PUT", "path": "/promotions/environments/{promotionEnvironmentId}", "tag": "Promotions", - "scope": "gitConnection:update", + "scope": "promotions:update", "availability": "upstream-only", "phase": 35, "command": "n8n promotion environment update", @@ -2109,7 +2109,7 @@ "method": "DELETE", "path": "/promotions/environments/{promotionEnvironmentId}", "tag": "Promotions", - "scope": "gitConnection:delete", + "scope": "promotions:delete", "availability": "upstream-only", "phase": 35, "command": "n8n promotion environment delete", @@ -2120,7 +2120,7 @@ "method": "POST", "path": "/promotions/environments/{promotionEnvironmentId}/connect", "tag": "Promotions", - "scope": "gitConnection:clone", + "scope": "promotions:connect", "availability": "upstream-only", "phase": 35, "command": "n8n promotion environment connect", @@ -2131,7 +2131,7 @@ "method": "POST", "path": "/promotions/environments/{promotionEnvironmentId}/disconnect", "tag": "Promotions", - "scope": "gitConnection:clone", + "scope": "promotions:connect", "availability": "upstream-only", "phase": 35, "command": "n8n promotion environment disconnect", @@ -2142,7 +2142,7 @@ "method": "GET", "path": "/promotions/environments/{promotionEnvironmentId}/projects", "tag": "Promotions", - "scope": "gitConnection:read", + "scope": "promotions:read", "availability": "upstream-only", "phase": 35, "command": "n8n promotion environment project list", @@ -2153,7 +2153,7 @@ "method": "POST", "path": "/promotions/environments/{promotionEnvironmentId}/projects/{projectId}", "tag": "Promotions", - "scope": "gitConnection:manageProjects", + "scope": "promotions:manageProjects", "availability": "upstream-only", "phase": 35, "command": "n8n promotion environment project add", @@ -2164,7 +2164,7 @@ "method": "DELETE", "path": "/promotions/environments/{promotionEnvironmentId}/projects/{projectId}", "tag": "Promotions", - "scope": "gitConnection:manageProjects", + "scope": "promotions:manageProjects", "availability": "upstream-only", "phase": 35, "command": "n8n promotion environment project remove", @@ -2175,7 +2175,7 @@ "method": "POST", "path": "/promotions/environments/{promotionEnvironmentId}/apply", "tag": "Promotions", - "scope": "gitConnection:pull", + "scope": "promotions:apply", "availability": "upstream-only", "phase": 36, "command": "n8n promotion environment apply", @@ -2186,7 +2186,7 @@ "method": "POST", "path": "/promotions/environments/{promotionEnvironmentId}/apply/continue", "tag": "Promotions", - "scope": "gitConnection:pull", + "scope": "promotions:apply", "availability": "upstream-only", "phase": 36, "command": "n8n promotion environment apply-continue", @@ -2197,11 +2197,44 @@ "method": "POST", "path": "/promotions/environments/{promotionEnvironmentId}/promote", "tag": "Promotions", - "scope": "gitConnection:push", + "scope": "promotions:promote", "availability": "upstream-only", "phase": 36, "command": "n8n promotion environment promote", "status": "implemented" + }, + { + "operationId": "getPromotionEnvironmentMissingProjects", + "method": "GET", + "path": "/promotions/environments/{promotionEnvironmentId}/missing-projects", + "tag": "Promotions", + "scope": "promotions:read", + "availability": "upstream-only", + "phase": 37, + "command": "n8n promotion environment missing-projects", + "status": "implemented" + }, + { + "operationId": "getRateLimitSettings", + "method": "GET", + "path": "/settings/rate-limits", + "tag": "SettingsRateLimits", + "scope": "securitySettings:manage", + "availability": "upstream-only", + "phase": 38, + "command": "n8n rate-limit get", + "status": "implemented" + }, + { + "operationId": "updateRateLimitSettings", + "method": "PUT", + "path": "/settings/rate-limits", + "tag": "SettingsRateLimits", + "scope": "securitySettings:manage", + "availability": "upstream-only", + "phase": 38, + "command": "n8n rate-limit set", + "status": "implemented" } ] } diff --git a/internal/n8n/errors.go b/internal/n8n/errors.go index 0261001..428ba1f 100644 --- a/internal/n8n/errors.go +++ b/internal/n8n/errors.go @@ -7,8 +7,10 @@ import ( "fmt" "net/http" "regexp" + "slices" "strconv" "strings" + "time" ) // maxErrorBody caps how much of a non-2xx body is read. A misrouted request can @@ -40,6 +42,38 @@ type APIError struct { // ReviewRequestID names the open workflow review that blocked a // publication (409). ReviewRequestID string + + // Fields names the request fields a validation failure (400) points at: + // the first element of the issue path, then any unrecognized keys. n8n + // answers a rejected body with its first schema issue, e.g. + // {"code":"unrecognized_keys","keys":["idPolicy"],"path":[],...}. + Fields []string + + // RateLimit is set on a 429 from the headers the server sent with it. + RateLimit *RateLimit +} + +// RateLimit is what a 429 says about the rate-limit window. A field the +// server did not send stays at its zero value and its Has flag false. +type RateLimit struct { + // RetryAfter is how long to wait before retrying (Retry-After). + RetryAfter time.Duration + HasRetryAfter bool + // Limit and Remaining are X-RateLimit-Limit and X-RateLimit-Remaining. + Limit int + HasLimit bool + Remaining int + HasRemaining bool + // Reset is when the window resets (X-RateLimit-Reset, Unix seconds). + Reset time.Time +} + +// RetryAfterOf returns the wait a 429 asked for and whether it named one. +func RetryAfterOf(err error) (time.Duration, bool) { + if apiErr, ok := errors.AsType[*APIError](err); ok && apiErr.RateLimit != nil && apiErr.RateLimit.HasRetryAfter { + return apiErr.RateLimit.RetryAfter, true + } + return 0, false } func (e *APIError) Error() string { @@ -62,11 +96,21 @@ func (e *APIError) Error() string { b.WriteString(": ") b.WriteString(singleLine(e.Body)) } + if len(e.Fields) > 0 { + fmt.Fprintf(&b, " (field %s)", strings.Join(quoteAll(e.Fields), ", ")) + } if e.Hint != "" { b.WriteString(" (") b.WriteString(e.Hint) b.WriteString(")") } + if e.RateLimit != nil { + if text := e.RateLimit.describe(); text != "" { + b.WriteString(" (") + b.WriteString(text) + b.WriteString(")") + } + } if e.RequestID != "" { b.WriteString(" (request id ") b.WriteString(e.RequestID) @@ -75,6 +119,35 @@ func (e *APIError) Error() string { return b.String() } +// describe renders the rate-limit headers as one clause, e.g. "retry after +// 30s; limit 100, 0 remaining; window resets at 2026-11-10T10:00:00Z". +func (r *RateLimit) describe() string { + var parts []string + if r.HasRetryAfter { + parts = append(parts, "retry after "+r.RetryAfter.String()) + } + switch { + case r.HasLimit && r.HasRemaining: + parts = append(parts, fmt.Sprintf("limit %d, %d remaining", r.Limit, r.Remaining)) + case r.HasLimit: + parts = append(parts, fmt.Sprintf("limit %d", r.Limit)) + case r.HasRemaining: + parts = append(parts, fmt.Sprintf("%d remaining", r.Remaining)) + } + if !r.Reset.IsZero() { + parts = append(parts, "window resets at "+r.Reset.UTC().Format(time.RFC3339)) + } + return strings.Join(parts, "; ") +} + +func quoteAll(values []string) []string { + quoted := make([]string, len(values)) + for i, v := range values { + quoted[i] = strconv.Quote(v) + } + return quoted +} + func (e *APIError) statusText() string { if e.Status != "" { return e.Status @@ -145,6 +218,11 @@ type errorBody struct { Reason json.RawMessage `json:"reason"` VersionID json.RawMessage `json:"versionId"` WorkflowReviewRequestID json.RawMessage `json:"workflowReviewRequestId"` + + // Path and Keys come from a schema issue, the shape n8n answers a + // rejected request body with. + Path json.RawMessage `json:"path"` + Keys json.RawMessage `json:"keys"` } // newAPIError builds an error from a response body that has already been read @@ -158,6 +236,9 @@ func newAPIError(resp *http.Response, method, path string, body []byte, truncate RequestID: requestID(resp.Header), Truncated: truncated, } + if resp.StatusCode == http.StatusTooManyRequests { + apiErr.RateLimit = parseRateLimit(resp.Header, time.Now()) + } var decoded errorBody if err := json.Unmarshal(body, &decoded); err != nil { @@ -171,6 +252,9 @@ func newAPIError(resp *http.Response, method, path string, body []byte, truncate apiErr.Reason = firstText(decoded.Reason) apiErr.VersionID = firstText(decoded.VersionID) apiErr.ReviewRequestID = firstText(decoded.WorkflowReviewRequestID) + if resp.StatusCode == http.StatusBadRequest { + apiErr.Fields = issueFields(decoded.Path, decoded.Keys) + } if apiErr.Message == "" && apiErr.Code == "" { // Valid JSON in a shape we do not know: keep it rather than drop it. apiErr.Body = truncateText(strings.TrimSpace(string(body)), 512) @@ -228,6 +312,56 @@ func flattenText(raw json.RawMessage) string { return "" } +// issueFields names the request fields a schema issue points at: the first +// path element when it is a field name, then the unrecognized keys. Anything +// that is not a list of strings is ignored. +func issueFields(path, keys json.RawMessage) []string { + var fields []string + var elements []json.RawMessage + if len(path) > 0 && json.Unmarshal(path, &elements) == nil && len(elements) > 0 { + var first string + if json.Unmarshal(elements[0], &first) == nil && first != "" { + fields = append(fields, first) + } + } + var names []string + if len(keys) > 0 && json.Unmarshal(keys, &names) == nil { + for _, name := range names { + if name != "" && !slices.Contains(fields, name) { + fields = append(fields, name) + } + } + } + return fields +} + +// parseRateLimit reads the 429 headers. Retry-After is seconds or an HTTP +// date; malformed values are dropped rather than guessed at. It returns nil +// when no header was usable. +func parseRateLimit(h http.Header, now time.Time) *RateLimit { + var r RateLimit + if v := strings.TrimSpace(h.Get("Retry-After")); v != "" { + if seconds, err := strconv.Atoi(v); err == nil && seconds >= 0 { + r.RetryAfter, r.HasRetryAfter = time.Duration(seconds)*time.Second, true + } else if at, err := http.ParseTime(v); err == nil { + r.RetryAfter, r.HasRetryAfter = max(at.Sub(now).Round(time.Second), 0), true + } + } + if v, err := strconv.Atoi(strings.TrimSpace(h.Get("X-RateLimit-Limit"))); err == nil && v >= 0 { + r.Limit, r.HasLimit = v, true + } + if v, err := strconv.Atoi(strings.TrimSpace(h.Get("X-RateLimit-Remaining"))); err == nil && v >= 0 { + r.Remaining, r.HasRemaining = v, true + } + if v, err := strconv.ParseInt(strings.TrimSpace(h.Get("X-RateLimit-Reset")), 10, 64); err == nil && v > 0 { + r.Reset = time.Unix(v, 0).UTC() + } + if !r.HasRetryAfter && !r.HasLimit && !r.HasRemaining && r.Reset.IsZero() { + return nil + } + return &r +} + // requestID reads the correlation identifiers n8n and its proxies emit. func requestID(h http.Header) string { for _, name := range []string{"X-Request-Id", "X-Correlation-Id", "X-Amzn-Trace-Id"} { diff --git a/internal/n8n/idempotency_test.go b/internal/n8n/idempotency_test.go index cb391cd..95d91e1 100644 --- a/internal/n8n/idempotency_test.go +++ b/internal/n8n/idempotency_test.go @@ -180,7 +180,7 @@ func TestIdempotencyKeyValidatedBeforeTransport(t *testing.T) { }, "package import": func() error { _, err := client.ImportPackage(context.Background(), ImportPackageRequest{ - WorkflowConflictPolicy: ImportWorkflowConflictFail, WorkflowIDPolicy: ImportWorkflowIDSource, + ConflictPolicy: ImportConflictFail, IDPolicy: ImportIDSource, }, strings.NewReader(packageArchiveBytes), "workflows.n8np", IdempotencyKey("clé")) return err }, @@ -228,8 +228,8 @@ func TestIdempotencyRefusals(t *testing.T) { } func TestImportPackageIdempotencyKey(t *testing.T) { - request := ImportPackageRequest{WorkflowConflictPolicy: ImportWorkflowConflictFail, WorkflowIDPolicy: ImportWorkflowIDSource} - selection := ImportPackageSelectionRequest{ProjectID: "p1", WorkflowIDs: []string{"wf-1"}, WorkflowIDPolicy: ImportWorkflowIDSource} + request := ImportPackageRequest{ConflictPolicy: ImportConflictFail, IDPolicy: ImportIDSource} + selection := ImportPackageSelectionRequest{ProjectID: "p1", WorkflowIDs: []string{"wf-1"}, IDPolicy: ImportIDSource} calls := map[string]func(*Client, ...CallOption) error{ "import": func(c *Client, opts ...CallOption) error { _, err := c.ImportPackage(context.Background(), request, strings.NewReader(packageArchiveBytes), "workflows.n8np", opts...) @@ -291,7 +291,7 @@ func TestImportPackageIdempotencyRefusalIsNotImportBlocked(t *testing.T) { t.Run(fmt.Sprint(status), func(t *testing.T) { server := newCommunityPackageServer(t, packageJSONHandler(status, body)) _, err := server.client(t).ImportPackage(context.Background(), ImportPackageRequest{ - WorkflowConflictPolicy: ImportWorkflowConflictFail, WorkflowIDPolicy: ImportWorkflowIDSource, + ConflictPolicy: ImportConflictFail, IDPolicy: ImportIDSource, }, strings.NewReader(packageArchiveBytes), "workflows.n8np", IdempotencyKey("import-1")) if _, blocked := AsImportBlocked(err); blocked { t.Errorf("err = %v, want an API error, not an import block", err) diff --git a/internal/n8n/n8n_package.go b/internal/n8n/n8n_package.go index 15a1a75..7542735 100644 --- a/internal/n8n/n8n_package.go +++ b/internal/n8n/n8n_package.go @@ -289,9 +289,9 @@ func exportFilename(header string) string { } // Import conflict and mode values. Every optional mode takes its default when -// omitted; the CLI sends a field only when its flag is set, except -// WorkflowIDPolicy, which is always sent so the ID behavior is stated rather -// than inherited from a server default (source). +// omitted; the CLI sends a field only when its flag is set, except IDPolicy, +// which is always sent so the ID behavior is stated rather than inherited from +// a server default (source). const ( ImportCredentialMatchIDOnly = "id-only" ImportCredentialMatchNameAndType = "name-and-type" @@ -305,12 +305,16 @@ const ( ImportCredentialConflictOverwrite = "overwrite" ImportCredentialConflictFail = "fail" - ImportWorkflowConflictNewVersion = "new-version" - ImportWorkflowConflictFail = "fail" - ImportWorkflowConflictSkip = "skip" + // Conflict policies cover Agents and workflows from n8n 2.47; older + // instances apply them to workflows only. + ImportConflictNewVersion = "new-version" + ImportConflictFail = "fail" + ImportConflictSkip = "skip" - ImportWorkflowIDNew = "new" - ImportWorkflowIDSource = "source" + // ImportIDNew mints fresh IDs. Only instances before n8n 2.47 accept it; + // 2.47 and later accept only ImportIDSource. + ImportIDNew = "new" + ImportIDSource = "source" ImportMissingNodeFail = "fail" ImportMissingNodeImportAnyway = "import-anyway" @@ -366,8 +370,8 @@ var ( importCredentialMatchModes = []string{ImportCredentialMatchIDOnly, ImportCredentialMatchNameAndType, ImportCredentialMatchTypeOnly} importCredentialMissingModes = []string{ImportCredentialMissingMustPreexist, ImportCredentialMissingCreateStub, ImportCredentialMissingCreateWithValues} importCredentialConflicts = []string{ImportCredentialConflictKeep, ImportCredentialConflictOverwrite, ImportCredentialConflictFail} - importWorkflowConflicts = []string{ImportWorkflowConflictNewVersion, ImportWorkflowConflictFail, ImportWorkflowConflictSkip} - importWorkflowIDPolicies = []string{ImportWorkflowIDNew, ImportWorkflowIDSource} + importConflictPolicies = []string{ImportConflictNewVersion, ImportConflictFail, ImportConflictSkip} + importIDPolicies = []string{ImportIDNew, ImportIDSource} importMissingNodeModes = []string{ImportMissingNodeFail, ImportMissingNodeImportAnyway} importPublishPolicies = []string{ImportPublishPreserve, ImportPublishMatch, ImportPublishAll, ImportPublishNone} importProjectConflicts = []string{ImportProjectMerge, ImportProjectFail, ImportProjectOverwrite} @@ -385,35 +389,41 @@ var ( // ImportPackageRequest is the routing and conflict policy for one package // import. Empty optional fields are omitted so the server default applies, -// except WorkflowIDPolicy, which is always sent so the ID behavior is explicit +// except IDPolicy, which is always sent so the ID behavior is explicit // (the server default is source). Bindings, when set, must be a JSON object; // only credentials bindings are supported today. +// +// ConflictPolicy, IDPolicy, and PublishingPolicy travel under their n8n 2.47 +// names, conflictPolicy, idPolicy, and publishingPolicy, which cover Agents +// and workflows. Older instances name them workflowConflictPolicy, +// workflowIdPolicy, and workflowPublishingPolicy; [Client.ImportPackage] +// resends under those names when the instance asks for them. type ImportPackageRequest struct { - ProjectID string `json:"-"` - FolderID string `json:"-"` - CredentialMatchingMode string `json:"-"` - CredentialMissingMode string `json:"-"` - CredentialConflict string `json:"-"` // credentialConflictPolicy; overwrite and fail need credential:update - Bindings string `json:"-"` - WorkflowConflictPolicy string `json:"-"` - WorkflowIDPolicy string `json:"-"` - MissingNodeTypeMode string `json:"-"` - WorkflowPublishingPolicy string `json:"-"` - ProjectConflictPolicy string `json:"-"` - FolderConflictPolicy string `json:"-"` - OverwriteDeletionPolicy string `json:"-"` - DataTableMatchingMode string `json:"-"` - DataTableMissingMode string `json:"-"` - DataTableSchemaConflict string `json:"-"` - VariableMissingMode string `json:"-"` - VariableConflictPolicy string `json:"-"` - VariableParentPolicy string `json:"-"` - TagMissingMode string `json:"-"` - TagConflictPolicy string `json:"-"` + ProjectID string `json:"-"` + FolderID string `json:"-"` + CredentialMatchingMode string `json:"-"` + CredentialMissingMode string `json:"-"` + CredentialConflict string `json:"-"` // credentialConflictPolicy; overwrite and fail need credential:update + Bindings string `json:"-"` + ConflictPolicy string `json:"-"` + IDPolicy string `json:"-"` + MissingNodeTypeMode string `json:"-"` + PublishingPolicy string `json:"-"` + ProjectConflictPolicy string `json:"-"` + FolderConflictPolicy string `json:"-"` + OverwriteDeletionPolicy string `json:"-"` + DataTableMatchingMode string `json:"-"` + DataTableMissingMode string `json:"-"` + DataTableSchemaConflict string `json:"-"` + VariableMissingMode string `json:"-"` + VariableConflictPolicy string `json:"-"` + VariableParentPolicy string `json:"-"` + TagMissingMode string `json:"-"` + TagConflictPolicy string `json:"-"` } // Validate rejects an import policy the API would reject before transport. -// WorkflowConflictPolicy is required; WorkflowIDPolicy must be explicit. +// ConflictPolicy is required; IDPolicy must be explicit. func (r ImportPackageRequest) Validate() error { if strings.TrimSpace(r.ProjectID) != r.ProjectID { return fmt.Errorf("project ID must not start or end with whitespace") @@ -421,11 +431,11 @@ func (r ImportPackageRequest) Validate() error { if strings.TrimSpace(r.FolderID) != r.FolderID { return fmt.Errorf("folder ID must not start or end with whitespace") } - if !slices.Contains(importWorkflowConflicts, r.WorkflowConflictPolicy) { - return fmt.Errorf("unknown workflow-conflict policy %q: use %s", r.WorkflowConflictPolicy, strings.Join(importWorkflowConflicts, ", ")) + if !slices.Contains(importConflictPolicies, r.ConflictPolicy) { + return fmt.Errorf("unknown conflict policy %q: use %s", r.ConflictPolicy, strings.Join(importConflictPolicies, ", ")) } - if !slices.Contains(importWorkflowIDPolicies, r.WorkflowIDPolicy) { - return fmt.Errorf("unknown workflow-id policy %q: use %s", r.WorkflowIDPolicy, strings.Join(importWorkflowIDPolicies, ", ")) + if !slices.Contains(importIDPolicies, r.IDPolicy) { + return fmt.Errorf("unknown ID policy %q: use %s (new only before n8n 2.47)", r.IDPolicy, strings.Join(importIDPolicies, ", ")) } checks := []struct { value string @@ -436,7 +446,7 @@ func (r ImportPackageRequest) Validate() error { {r.CredentialMissingMode, importCredentialMissingModes, "credential-missing mode"}, {r.CredentialConflict, importCredentialConflicts, "credential-conflict policy"}, {r.MissingNodeTypeMode, importMissingNodeModes, "missing-node-type mode"}, - {r.WorkflowPublishingPolicy, importPublishPolicies, "workflow-publishing policy"}, + {r.PublishingPolicy, importPublishPolicies, "publishing policy"}, {r.ProjectConflictPolicy, importProjectConflicts, "project-conflict policy"}, {r.FolderConflictPolicy, importFolderConflicts, "folder-conflict policy"}, {r.OverwriteDeletionPolicy, importDeletionPolicies, "overwrite-deletion policy"}, @@ -463,13 +473,13 @@ func (r ImportPackageRequest) Validate() error { return nil } -// fields renders the policy as multipart form fields. Empty optional fields -// stay omitted so the server default applies; the workflow ID policy is -// always present. +// fields renders the policy as multipart form fields under the n8n 2.47 +// names. Empty optional fields stay omitted so the server default applies; +// the ID policy is always present. func (r ImportPackageRequest) fields() map[string]string { fields := map[string]string{ - "workflowConflictPolicy": r.WorkflowConflictPolicy, - "workflowIdPolicy": r.WorkflowIDPolicy, + "conflictPolicy": r.ConflictPolicy, + "idPolicy": r.IDPolicy, } set := func(name, value string) { if value != "" { @@ -483,7 +493,7 @@ func (r ImportPackageRequest) fields() map[string]string { set("credentialConflictPolicy", r.CredentialConflict) set("bindings", r.Bindings) set("missingNodeTypeMode", r.MissingNodeTypeMode) - set("workflowPublishingPolicy", r.WorkflowPublishingPolicy) + set("publishingPolicy", r.PublishingPolicy) set("projectConflictPolicy", r.ProjectConflictPolicy) set("folderConflictPolicy", r.FolderConflictPolicy) set("overwriteDeletionPolicy", r.OverwriteDeletionPolicy) @@ -507,13 +517,13 @@ func (r ImportPackageRequest) fields() map[string]string { // delete-only request. DeletedWorkflowIDs are destination IDs in the same // project, removed per OverwriteDeletionPolicy (server default archive). // Empty optional policies are omitted so the server default applies, except -// WorkflowIDPolicy, which is always sent like [ImportPackageRequest]. +// IDPolicy, which is always sent like [ImportPackageRequest]. type ImportPackageSelectionRequest struct { ProjectID string WorkflowIDs []string DeletedWorkflowIDs []string - WorkflowConflictPolicy string - WorkflowIDPolicy string + ConflictPolicy string + IDPolicy string OverwriteDeletionPolicy string } @@ -554,11 +564,11 @@ func (r ImportPackageSelectionRequest) Validate() error { } deleted[id] = true } - if r.WorkflowConflictPolicy != "" && !slices.Contains(importWorkflowConflicts, r.WorkflowConflictPolicy) { - return fmt.Errorf("unknown workflow-conflict policy %q: use %s", r.WorkflowConflictPolicy, strings.Join(importWorkflowConflicts, ", ")) + if r.ConflictPolicy != "" && !slices.Contains(importConflictPolicies, r.ConflictPolicy) { + return fmt.Errorf("unknown conflict policy %q: use %s", r.ConflictPolicy, strings.Join(importConflictPolicies, ", ")) } - if !slices.Contains(importWorkflowIDPolicies, r.WorkflowIDPolicy) { - return fmt.Errorf("unknown workflow-id policy %q: use %s", r.WorkflowIDPolicy, strings.Join(importWorkflowIDPolicies, ", ")) + if !slices.Contains(importIDPolicies, r.IDPolicy) { + return fmt.Errorf("unknown ID policy %q: use %s (new only before n8n 2.47)", r.IDPolicy, strings.Join(importIDPolicies, ", ")) } if r.OverwriteDeletionPolicy != "" { if !slices.Contains(importDeletionPolicies, r.OverwriteDeletionPolicy) { @@ -592,7 +602,7 @@ func (r ImportPackageSelectionRequest) fields() (map[string]string, error) { fields := map[string]string{ "selectedProjectId": r.ProjectID, "selectedWorkflowIds": string(selected), - "workflowIdPolicy": r.WorkflowIDPolicy, + "idPolicy": r.IDPolicy, } if len(r.DeletedWorkflowIDs) > 0 { deleted, err := json.Marshal(r.DeletedWorkflowIDs) @@ -601,8 +611,8 @@ func (r ImportPackageSelectionRequest) fields() (map[string]string, error) { } fields["deletedWorkflowIds"] = string(deleted) } - if r.WorkflowConflictPolicy != "" { - fields["workflowConflictPolicy"] = r.WorkflowConflictPolicy + if r.ConflictPolicy != "" { + fields["conflictPolicy"] = r.ConflictPolicy } if r.OverwriteDeletionPolicy != "" { fields["overwriteDeletionPolicy"] = r.OverwriteDeletionPolicy @@ -610,6 +620,69 @@ func (r ImportPackageSelectionRequest) fields() (map[string]string, error) { return fields, nil } +// legacyImportFields maps the n8n 2.47 import field names to the names +// instances before 2.47 require. Each generation's schema is strict and +// rejects the other's names. +var legacyImportFields = map[string]string{ + "conflictPolicy": "workflowConflictPolicy", + "idPolicy": "workflowIdPolicy", + "publishingPolicy": "workflowPublishingPolicy", +} + +// withLegacyImportFields returns fields with the 2.47 names renamed to the +// pre-2.47 ones; other fields are copied unchanged. +func withLegacyImportFields(fields map[string]string) map[string]string { + legacy := make(map[string]string, len(fields)) + for name, value := range fields { + if old, ok := legacyImportFields[name]; ok { + name = old + } + legacy[name] = value + } + return legacy +} + +// predatesImportFieldRename reports whether err is the 400 an instance +// before n8n 2.47 answers to the 2.47 field names: it names one of its own +// workflow-prefixed fields as missing or invalid, or rejects a 2.47 name as +// an unrecognized key. A 2.47 instance refusing a value (idPolicy=new) names +// idPolicy without rejecting the key, so it does not match. +func predatesImportFieldRename(err error) bool { + apiErr, ok := errors.AsType[*APIError](err) + if !ok || apiErr.StatusCode != http.StatusBadRequest { + return false + } + unrecognized := apiErr.Code == "unrecognized_keys" || strings.Contains(apiErr.Message, "Unrecognized key") + // The first request never sends a workflow-prefixed name, so a 400 whose + // text names one comes from an instance that still requires it, whatever + // validator produced the message. + for _, old := range legacyImportFields { + if strings.Contains(apiErr.Message, old) || strings.Contains(apiErr.Body, old) { + return true + } + } + for _, field := range apiErr.Fields { + for current, old := range legacyImportFields { + if field == old || (unrecognized && field == current) { + return true + } + } + } + if unrecognized && len(apiErr.Fields) == 0 { + for current := range legacyImportFields { + if strings.Contains(apiErr.Message, "'"+current+"'") { + return true + } + } + } + return false +} + +// ErrImportArchiveNotRewindable means the instance predates n8n 2.47 and +// needs the import resent under the older field names, but the archive came +// from a reader that cannot be read twice, such as a pipe. +var ErrImportArchiveNotRewindable = errors.New("the instance predates n8n 2.47 and needs the import resent with workflowConflictPolicy, workflowIdPolicy, and workflowPublishingPolicy, but the archive reader cannot be rewound") + func nonNilStrings(values []string) []string { if values == nil { return []string{} @@ -624,8 +697,13 @@ func nonNilStrings(values []string) []string { // Raw keeps the response verbatim so fields this type does not name yet, // nested ones included, survive --output json. It is a read model: MarshalJSON // re-emits Raw when present, so edits to the typed fields are not reflected. +// +// Agents, Counts, and Bindings.Agents arrive from n8n 2.47 and stay empty on +// older instances. type ImportPackageResult struct { Package ImportedPackage `json:"package"` + Agents []ImportedAgent `json:"agents"` + Counts *ImportCounts `json:"counts,omitempty"` Workflows []ImportedWorkflow `json:"workflows"` RemovedWorkflows []RemovedWorkflow `json:"removedWorkflows"` RemovedFolders []RemovedFolder `json:"removedFolders"` @@ -660,11 +738,55 @@ func (r ImportPackageResult) MarshalJSON() ([]byte, error) { return json.Marshal(plain(r)) } -// ImportedPackage identifies the package the result came from. +// ImportedPackage identifies the package the result came from. ExportedAt is +// sent only before n8n 2.47. type ImportedPackage struct { SourceN8nVersion string `json:"sourceN8nVersion"` SourceID string `json:"sourceId"` - ExportedAt string `json:"exportedAt"` + ExportedAt string `json:"exportedAt,omitempty"` +} + +// ImportedAgent is one package Agent and what happened to it (n8n 2.47). +// Definition import and publication have separate outcomes: a publication +// failure keeps the imported definition. +type ImportedAgent struct { + SourceAgentID string `json:"sourceAgentId"` + LocalID string `json:"localId"` + Name string `json:"name"` + ProjectID string `json:"projectId"` + ActiveVersionID *string `json:"activeVersionId"` + Status string `json:"status"` + Publishing ImportPublishing `json:"publishing"` + Channels []ImportedAgentChannel `json:"channels"` +} + +// Agent channel statuses. setup-required channels need a visit to SetupURL +// before the Agent can use them. +const ( + ImportChannelReused = "reused" + ImportChannelSetupRequired = "setup-required" +) + +// ImportedAgentChannel is one integration channel of an imported Agent: +// reused as configured, or needing setup (Reason new-channel or +// destination-draft). +type ImportedAgentChannel struct { + Type string `json:"type"` + Status string `json:"status"` + Reason string `json:"reason,omitempty"` + SetupURL string `json:"setupUrl,omitempty"` +} + +// ImportCounts holds the per-entity totals of an import (n8n 2.47). +type ImportCounts struct { + Agents ImportEntityCounts `json:"agents"` +} + +// ImportEntityCounts counts entities by outcome. +type ImportEntityCounts struct { + Created int `json:"created"` + Updated int `json:"updated"` + Skipped int `json:"skipped"` } // ImportedWorkflow is one package workflow and what happened to it. @@ -680,8 +802,21 @@ type ImportedWorkflow struct { Status string `json:"status"` } +// Publishing states and reasons shared by workflows and Agents. A blocked or +// skipped publication names its reason; channel-setup-required (n8n 2.47) +// means an Agent channel needs setup first. +const ( + ImportPublishingPublished = "published" + ImportPublishingUnpublished = "unpublished" + ImportPublishingUnchanged = "unchanged" + ImportPublishingBlocked = "blocked" + ImportPublishingFailed = "failed" + + ImportPublishReasonChannelSetupRequired = "channel-setup-required" +) + // ImportPublishing is the outcome of applying the publishing policy to one -// workflow. +// workflow or Agent. type ImportPublishing struct { State string `json:"state"` Error string `json:"error,omitempty"` @@ -728,7 +863,10 @@ type ImportedProject struct { // ImportBindings maps source IDs from the package to target IDs on the // instance, one map per entity type. +// +// Agents is set from n8n 2.47. type ImportBindings struct { + Agents map[string]string `json:"agents,omitempty"` Workflows map[string]string `json:"workflows"` Credentials map[string]string `json:"credentials"` } @@ -783,6 +921,8 @@ const ( ImportIssueAgentPolicyViolation = "agent-policy-violation" ImportIssueWorkflowFolderConflict = "workflow-folder-conflict" ImportIssueCredentialPolicyViolation = "credential-policy-violation" + ImportIssuePolicyCheckFailed = "policy-check-failed" + ImportIssueDataTableUnresolved = "data-table-unresolved" ) // ImportBlockingIssue is one reason a 409 or 422 rejected an import. The @@ -814,9 +954,18 @@ type ImportBlockingIssue struct { TargetID string `json:"targetId,omitempty"` CredentialType string `json:"credentialType,omitempty"` Violations []ImportIssueViolation `json:"violations,omitempty"` + Point string `json:"point,omitempty"` + Column *ImportIssueColumn `json:"column,omitempty"` Raw json.RawMessage `json:"-"` } +// ImportIssueColumn names the data-table column a column-id-conflict +// (data-table-unresolved, n8n 2.47) is about. +type ImportIssueColumn struct { + ID string `json:"id"` + Name string `json:"name"` +} + // ImportIssueViolation is one policy check that refused an agent, workflow, or // credential in a *-policy-violation issue. type ImportIssueViolation struct { @@ -861,9 +1010,10 @@ func (issue ImportBlockingIssue) MarshalJSON() ([]byte, error) { } // Describe renders the issue as one human-readable line starting with its -// type. Agent issues, workflow-folder-conflict, and -// credential-policy-violation get a sentence; every other type lists its -// scalar fields from Raw as key=value pairs, so unknown types still read. +// type. Agent issues, workflow-folder-conflict, credential-policy-violation, +// and policy-check-failed get a sentence; data-table-unresolved adds its +// column; every other type lists its scalar fields from Raw as key=value +// pairs, so unknown types and new fields such as reason or kind still read. func (issue ImportBlockingIssue) Describe() string { typ := emptyImportIssueType(issue.Type) switch issue.Type { @@ -892,6 +1042,14 @@ func (issue ImportBlockingIssue) Describe() string { line += fmt.Sprintf(", update of target %q", issue.TargetID) } return line + ") refused: " + describeViolations(issue.Violations) + case ImportIssuePolicyCheckFailed: + return fmt.Sprintf("%s: the %s policy check could not run, so nothing was written", typ, dashIfEmpty(issue.Point)) + case ImportIssueDataTableUnresolved: + line := typ + describeScalarFields(issue.Raw) + if issue.Column != nil { + line += fmt.Sprintf(" (column %s, id %s)", quoteOrDash(issue.Column.Name), quoteOrDash(issue.Column.ID)) + } + return line } return typ + describeScalarFields(issue.Raw) } @@ -1075,11 +1233,17 @@ func IsImportUnprocessable(err error) bool { // opts accepts [IdempotencyKey]. With a key the multipart boundary is derived // from it, so a retry with the same key, archive and filename sends the same // bytes, which the server requires to replay the first result. +// +// The policy travels under the n8n 2.47 field names. An instance before 2.47 +// rejects them with a 400 before writing anything; the import is then sent +// once more under the older names, which needs packageData to be an +// [io.Seeker] (a file). Otherwise the error wraps +// [ErrImportArchiveNotRewindable]. func (c *Client) ImportPackage(ctx context.Context, request ImportPackageRequest, packageData io.Reader, filename string, opts ...CallOption) (*ImportPackageResult, error) { if err := request.Validate(); err != nil { return nil, err } - return c.postPackageImport(ctx, N8nPackageImportPath, request.fields(), packageData, filename, opts) + return c.postPackageImportCompat(ctx, N8nPackageImportPath, request.fields(), packageData, filename, opts) } // ImportPackageSelection cherry-picks workflows from one source project of a @@ -1087,7 +1251,8 @@ func (c *Client) ImportPackage(ctx context.Context, request ImportPackageRequest // missing. It never removes a workflow the selection omits; it deletes only // request.DeletedWorkflowIDs. The archive streams like [Client.ImportPackage] // and the result has the same shape. The caller confirms first. opts accepts -// [IdempotencyKey], with the same boundary rule as [Client.ImportPackage]. +// [IdempotencyKey], with the same boundary rule as [Client.ImportPackage], and +// older instances get the same field-name fallback. func (c *Client) ImportPackageSelection(ctx context.Context, request ImportPackageSelectionRequest, packageData io.Reader, filename string, opts ...CallOption) (*ImportPackageResult, error) { if err := request.Validate(); err != nil { return nil, err @@ -1096,7 +1261,44 @@ func (c *Client) ImportPackageSelection(ctx context.Context, request ImportPacka if err != nil { return nil, err } - return c.postPackageImport(ctx, N8nPackageImportSelectionPath, fields, packageData, filename, opts) + return c.postPackageImportCompat(ctx, N8nPackageImportSelectionPath, fields, packageData, filename, opts) +} + +// postPackageImportCompat sends the import under the n8n 2.47 field names +// and, when the instance turns out to predate them, rewinds the archive and +// sends it once more under the older names. The 400 comes from body +// validation, before any write, and a failed request releases its +// idempotency key, so resending with the same key is safe. +func (c *Client) postPackageImportCompat(ctx context.Context, path string, fields map[string]string, packageData io.Reader, filename string, opts []CallOption) (*ImportPackageResult, error) { + seeker, start, rewindable := rewindPoint(packageData) + result, err := c.postPackageImport(ctx, path, fields, packageData, filename, opts) + if err == nil || !predatesImportFieldRename(err) { + return result, err + } + if !rewindable { + return nil, fmt.Errorf("n8n: POST %s: %w: %w", path, ErrImportArchiveNotRewindable, err) + } + if _, seekErr := seeker.Seek(start, io.SeekStart); seekErr != nil { + return nil, fmt.Errorf("n8n: POST %s: %w: rewind: %w: %w", path, ErrImportArchiveNotRewindable, seekErr, err) + } + if ctx != nil { + c.logger.DebugContext(ctx, "n8n import resent with pre-2.47 field names", "path", path, "first", err) + } + return c.postPackageImport(ctx, path, withLegacyImportFields(fields), packageData, filename, opts) +} + +// rewindPoint records where a seekable reader stands so it can be read again. +// A pipe implements io.Seeker but fails to seek, so it is not rewindable. +func rewindPoint(r io.Reader) (io.Seeker, int64, bool) { + seeker, ok := r.(io.Seeker) + if !ok { + return nil, 0, false + } + offset, err := seeker.Seek(0, io.SeekCurrent) + if err != nil { + return nil, 0, false + } + return seeker, offset, true } // postPackageImport streams fields and the archive to an import endpoint and @@ -1135,10 +1337,17 @@ func (c *Client) postPackageImport(ctx context.Context, path string, fields map[ if call.IdempotencyKey != "" { boundary = idempotentBoundary(call.IdempotencyKey) } - body, contentType, err := multipartImportBody(fields, packageData, filename, boundary) + body, contentType, done, err := multipartImportBody(fields, packageData, filename, boundary) if err != nil { return nil, err } + // The writer goroutine reads packageData until the server stops reading. + // Closing the pipe stops it, and waiting for it means the archive is no + // longer read once this returns, so a caller may rewind it. + defer func() { + _ = body.Close() + <-done + }() req, err := http.NewRequestWithContext(ctx, http.MethodPost, importEndpoint.String(), body) if err != nil { return nil, fmt.Errorf("n8n: build request: %w", err) @@ -1210,22 +1419,25 @@ func (c *Client) postPackageImport(ctx context.Context, path string, fields map[ // multipartImportBody streams the policy fields and the archive through a // pipe: the writer side runs in a goroutine, so the HTTP transport reads // while the archive streams without an intermediate buffer. An empty boundary -// keeps the random one multipart picks. -func multipartImportBody(fields map[string]string, packageData io.Reader, filename, boundary string) (io.Reader, string, error) { +// keeps the random one multipart picks. done closes once the writer has +// stopped reading packageData. +func multipartImportBody(fields map[string]string, packageData io.Reader, filename, boundary string) (io.ReadCloser, string, <-chan struct{}, error) { reader, writer := io.Pipe() multipartWriter := multipart.NewWriter(writer) if boundary != "" { if err := multipartWriter.SetBoundary(boundary); err != nil { _ = writer.Close() - return nil, "", fmt.Errorf("n8n: multipart boundary: %w", err) + return nil, "", nil, fmt.Errorf("n8n: multipart boundary: %w", err) } } contentType := multipartWriter.FormDataContentType() + done := make(chan struct{}) go func() { + defer close(done) err := writeMultipartImport(multipartWriter, fields, packageData, filename) _ = writer.CloseWithError(err) }() - return reader, contentType, nil + return reader, contentType, done, nil } func writeMultipartImport(multipartWriter *multipart.Writer, fields map[string]string, packageData io.Reader, filename string) error { diff --git a/internal/n8n/n8n_package_247_test.go b/internal/n8n/n8n_package_247_test.go new file mode 100644 index 0000000..472651d --- /dev/null +++ b/internal/n8n/n8n_package_247_test.go @@ -0,0 +1,290 @@ +package n8n + +import ( + "bytes" + "context" + "errors" + "io" + "net/http" + "strings" + "testing" + "time" +) + +// legacyImportServer answers like an n8n 2.46 instance: the 2.47 field names +// fail body validation with the first schema issue, the older names succeed. +func legacyImportServer(t *testing.T, rejection string) *communityPackageServer { + t.Helper() + var server *communityPackageServer + server = newCommunityPackageServer(t, func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Content-Type", contentTypeJSON) + // The recording wrapper consumed the body before this handler runs. + if strings.Contains(server.bodies[len(server.bodies)-1], `name="idPolicy"`) { + w.WriteHeader(http.StatusBadRequest) + _, _ = w.Write([]byte(rejection)) + return + } + _, _ = w.Write([]byte(packageImportResultJSON)) + }) + return server +} + +func TestImportPackageFallsBackToLegacyFieldNames(t *testing.T) { + const missingRequired = `{"code":"invalid_type","expected":"'new-version' | 'fail' | 'skip'","received":"undefined","path":["workflowConflictPolicy"],"message":"Required"}` + server := legacyImportServer(t, missingRequired) + + // The archive starts mid-reader: the retry must rewind to where it began, + // not to the start of the file. + archive := bytes.NewReader([]byte("prefix" + packageArchiveBytes)) + if _, err := archive.Seek(int64(len("prefix")), io.SeekStart); err != nil { + t.Fatal(err) + } + _, err := server.client(t).ImportPackage(context.Background(), ImportPackageRequest{ + ConflictPolicy: ImportConflictSkip, + IDPolicy: ImportIDSource, + PublishingPolicy: ImportPublishAll, + }, archive, "p.n8np", IdempotencyKey("retry-key")) + if err != nil { + t.Fatalf("ImportPackage: %v", err) + } + if len(server.requests) != 2 { + t.Fatalf("requests = %d, want the 2.47 attempt and one legacy retry", len(server.requests)) + } + first, _, _ := parseMultipartImport(t, server.requests[0], []byte(server.bodies[0])) + if first["conflictPolicy"] != ImportConflictSkip || first["idPolicy"] != ImportIDSource || first["publishingPolicy"] != ImportPublishAll { + t.Errorf("first fields = %v, want the 2.47 names", first) + } + second, fileBytes, _ := parseMultipartImport(t, server.requests[1], []byte(server.bodies[1])) + for name, want := range map[string]string{ + "workflowConflictPolicy": ImportConflictSkip, + "workflowIdPolicy": ImportIDSource, + "workflowPublishingPolicy": ImportPublishAll, + } { + if second[name] != want { + t.Errorf("retry %s = %q, want %q", name, second[name], want) + } + } + for _, name := range []string{"conflictPolicy", "idPolicy", "publishingPolicy"} { + if _, ok := second[name]; ok { + t.Errorf("retry still sends %s; the 2.46 schema rejects it", name) + } + } + if fileBytes != packageArchiveBytes { + t.Errorf("retry archive = %q, want the full archive again", fileBytes) + } + for i, req := range server.requests { + if got := req.Header.Get(IdempotencyKeyHeader); got != "retry-key" { + t.Errorf("request %d %s = %q, want the same key", i, IdempotencyKeyHeader, got) + } + } +} + +func TestImportPackageSelectionFallsBackOnUnrecognizedKeys(t *testing.T) { + const unrecognized = `{"code":"unrecognized_keys","keys":["conflictPolicy","idPolicy"],"path":[],"message":"Unrecognized key(s) in object: 'conflictPolicy', 'idPolicy'"}` + server := legacyImportServer(t, unrecognized) + + _, err := server.client(t).ImportPackageSelection(context.Background(), ImportPackageSelectionRequest{ + ProjectID: "p1", + WorkflowIDs: []string{"wf-1"}, + ConflictPolicy: ImportConflictFail, + IDPolicy: ImportIDSource, + }, strings.NewReader(packageArchiveBytes), "p.n8np") + if err != nil { + t.Fatalf("ImportPackageSelection: %v", err) + } + if len(server.requests) != 2 { + t.Fatalf("requests = %d, want 2", len(server.requests)) + } + second, _, _ := parseMultipartImport(t, server.requests[1], []byte(server.bodies[1])) + if second["workflowConflictPolicy"] != ImportConflictFail || second["workflowIdPolicy"] != ImportIDSource || second["selectedProjectId"] != "p1" { + t.Errorf("retry fields = %v, want legacy names and the selection", second) + } +} + +func TestImportPackageFallsBackOnLegacyFieldInMessage(t *testing.T) { + // A validator that answers with prose instead of a zod issue still names + // the field the older schema requires. + const prose = `{"message":"request/body must have required property 'workflowConflictPolicy'"}` + server := legacyImportServer(t, prose) + + _, err := server.client(t).ImportPackage(context.Background(), ImportPackageRequest{ + ConflictPolicy: ImportConflictSkip, + IDPolicy: ImportIDSource, + }, strings.NewReader(packageArchiveBytes), "p.n8np") + if err != nil { + t.Fatalf("ImportPackage: %v", err) + } + if len(server.requests) != 2 { + t.Fatalf("requests = %d, want the 2.47 attempt and one legacy retry", len(server.requests)) + } +} + +func TestImportPackageLegacyFallbackNeedsRewindableArchive(t *testing.T) { + const missingRequired = `{"code":"invalid_type","path":["workflowConflictPolicy"],"message":"Required"}` + server := legacyImportServer(t, missingRequired) + + // io.MultiReader hides Seek, like a pipe that cannot be read twice. + archive := io.MultiReader(strings.NewReader(packageArchiveBytes)) + _, err := server.client(t).ImportPackage(context.Background(), ImportPackageRequest{ + ConflictPolicy: ImportConflictSkip, + IDPolicy: ImportIDSource, + }, archive, "p.n8np") + if !errors.Is(err, ErrImportArchiveNotRewindable) { + t.Fatalf("error = %v, want ErrImportArchiveNotRewindable", err) + } + if !IsStatus(err, http.StatusBadRequest) { + t.Errorf("error = %v, want the 400 kept in the chain", err) + } + if len(server.requests) != 1 { + t.Errorf("requests = %d, want no retry", len(server.requests)) + } +} + +func TestImportPackageDoesNotFallBackOnOtherBadRequests(t *testing.T) { + for name, body := range map[string]string{ + "2.47 refuses idPolicy new": `{"code":"invalid_enum_value","options":["source"],"path":["idPolicy"],"message":"Invalid enum value. Expected 'source', received 'new'"}`, + "bad bindings": `{"code":"custom","path":["bindings"],"message":"bindings must be a JSON object"}`, + "plain message": `{"message":"package is malformed"}`, + } { + t.Run(name, func(t *testing.T) { + server := newCommunityPackageServer(t, packageJSONHandler(http.StatusBadRequest, body)) + _, err := server.client(t).ImportPackage(context.Background(), ImportPackageRequest{ + ConflictPolicy: ImportConflictSkip, + IDPolicy: ImportIDNew, + }, strings.NewReader(packageArchiveBytes), "p.n8np") + if !IsStatus(err, http.StatusBadRequest) || errors.Is(err, ErrImportArchiveNotRewindable) { + t.Fatalf("error = %v, want the plain 400", err) + } + if len(server.requests) != 1 { + t.Errorf("requests = %d, want 1", len(server.requests)) + } + }) + } +} + +func TestImportPackageResultDecodesAgents(t *testing.T) { + body := `{ + "package":{"sourceN8nVersion":"2.47.3","sourceId":"pkg-4"}, + "agents":[{"sourceAgentId":"ag-1","localId":"ag-1","name":"Helper","projectId":"p1","activeVersionId":null,"status":"created", + "publishing":{"state":"blocked","blockedReason":"channel-setup-required"}, + "channels":[{"type":"slack","status":"setup-required","reason":"new-channel","setupUrl":"https://n8n.example/agents/ag-1/channels"},{"type":"chat","status":"reused"}]}], + "counts":{"agents":{"created":1,"updated":0,"skipped":0}}, + "workflows":[],"removedWorkflows":[],"removedFolders":[],"folders":[],"projects":[], + "bindings":{"agents":{"ag-1":"ag-1"},"workflows":{},"credentials":{}}, + "credentials":{"matched":[],"stubbed":[],"seeded":[],"incomplete":[]}, + "dataTables":{"matched":0,"created":0,"updated":0}, + "variables":{"matched":[],"missing":[],"created":[],"stubbed":[],"updated":[]}, + "tags":{"matched":[],"created":[],"renamed":[],"reconciled":[],"skipped":[]} +}` + server := newCommunityPackageServer(t, packageJSONHandler(http.StatusOK, body)) + result, err := server.client(t).ImportPackage(context.Background(), ImportPackageRequest{ + ConflictPolicy: ImportConflictSkip, IDPolicy: ImportIDSource, + }, strings.NewReader(packageArchiveBytes), "p.n8np") + if err != nil { + t.Fatalf("ImportPackage: %v", err) + } + if len(result.Agents) != 1 { + t.Fatalf("agents = %d, want 1", len(result.Agents)) + } + agent := result.Agents[0] + if agent.Status != "created" || agent.ActiveVersionID != nil || agent.Publishing.BlockedReason != ImportPublishReasonChannelSetupRequired { + t.Errorf("agent = %+v, want created, no active version, blocked on channel setup", agent) + } + if len(agent.Channels) != 2 || agent.Channels[0].Status != ImportChannelSetupRequired || agent.Channels[0].SetupURL == "" { + t.Errorf("channels = %+v, want a setup-required channel with its URL", agent.Channels) + } + if result.Counts == nil || result.Counts.Agents.Created != 1 { + t.Errorf("counts = %+v, want one created agent", result.Counts) + } + if result.Bindings.Agents["ag-1"] != "ag-1" { + t.Errorf("bindings.agents = %v, want ag-1", result.Bindings.Agents) + } + if result.Package.ExportedAt != "" { + t.Errorf("exportedAt = %q, want empty on 2.47", result.Package.ExportedAt) + } +} + +func TestImportBlockingIssueDescribe247(t *testing.T) { + for _, tc := range []struct { + name, raw string + want []string + }{ + {"policy-check-failed", `{"type":"policy-check-failed","point":"credentialSave"}`, + []string{"policy-check-failed: the credentialSave policy check could not run"}}, + {"data-table column-id-conflict", `{"type":"data-table-unresolved","kind":"column-id-conflict","sourceId":"dt-1","name":"Orders","column":{"id":"col-9","name":"total"}}`, + []string{`data-table-unresolved: kind="column-id-conflict" name="Orders" sourceId="dt-1"`, `(column "total", id "col-9")`}}, + {"credential-unresolved reason", `{"type":"credential-unresolved","sourceId":"c-1","reason":"access-required"}`, + []string{`reason="access-required"`}}, + {"project-conflict kind", `{"type":"project-conflict","kind":"create-forbidden","sourceProjectId":"p1"}`, + []string{`kind="create-forbidden"`}}, + } { + t.Run(tc.name, func(t *testing.T) { + var issue ImportBlockingIssue + if err := issue.UnmarshalJSON([]byte(tc.raw)); err != nil { + t.Fatal(err) + } + got := issue.Describe() + for _, want := range tc.want { + if !strings.Contains(got, want) { + t.Errorf("Describe() = %q, want %q", got, want) + } + } + }) + } +} + +func TestAPIErrorBadRequestFields(t *testing.T) { + err := decodeError(t, http.StatusBadRequest, nil, + `{"code":"unrecognized_keys","keys":["conflictPolicy","idPolicy"],"path":[],"message":"Unrecognized key(s) in object: 'conflictPolicy', 'idPolicy'"}`) + if len(err.Fields) != 2 || err.Fields[0] != "conflictPolicy" || err.Fields[1] != "idPolicy" { + t.Errorf("Fields = %v, want the unrecognized keys", err.Fields) + } + if !strings.Contains(err.Error(), `(field "conflictPolicy", "idPolicy")`) { + t.Errorf("Error() = %q, want the fields named", err.Error()) + } + err = decodeError(t, http.StatusBadRequest, nil, `{"code":"invalid_type","path":["workflowConflictPolicy",0],"message":"Required"}`) + if len(err.Fields) != 1 || err.Fields[0] != "workflowConflictPolicy" { + t.Errorf("Fields = %v, want the path head", err.Fields) + } + if got := decodeError(t, http.StatusNotFound, nil, `{"message":"x","path":["a"]}`).Fields; got != nil { + t.Errorf("404 Fields = %v, want none", got) + } +} + +func TestAPIErrorRateLimit(t *testing.T) { + header := http.Header{} + header.Set("Retry-After", "30") + header.Set("X-RateLimit-Limit", "100") + header.Set("X-RateLimit-Remaining", "0") + header.Set("X-RateLimit-Reset", "1793000000") + err := decodeError(t, http.StatusTooManyRequests, header, `{"message":"Too many requests"}`) + if !IsRateLimited(err) || err.RateLimit == nil { + t.Fatalf("error = %#v, want a rate limit", err) + } + if d, ok := RetryAfterOf(err); !ok || d != 30*time.Second { + t.Errorf("RetryAfterOf = %v, %v, want 30s", d, ok) + } + want := "retry after 30s; limit 100, 0 remaining; window resets at " + time.Unix(1793000000, 0).UTC().Format(time.RFC3339) + if !strings.Contains(err.Error(), want) { + t.Errorf("Error() = %q, want %q", err.Error(), want) + } + + date := http.Header{} + date.Set("Retry-After", time.Now().Add(90*time.Second).UTC().Format(http.TimeFormat)) + if d, ok := RetryAfterOf(decodeError(t, http.StatusTooManyRequests, date, "")); !ok || d < 80*time.Second || d > 91*time.Second { + t.Errorf("HTTP-date Retry-After = %v, %v, want about 90s", d, ok) + } + + junk := http.Header{} + junk.Set("Retry-After", "soon") + junk.Set("X-RateLimit-Limit", "-3") + if got := decodeError(t, http.StatusTooManyRequests, junk, "").RateLimit; got != nil { + t.Errorf("RateLimit = %+v, want nil for malformed headers", got) + } + if _, ok := RetryAfterOf(errors.New("plain")); ok { + t.Error("RetryAfterOf(plain error) = ok, want false") + } + if got := decodeError(t, http.StatusServiceUnavailable, header, "").RateLimit; got != nil { + t.Errorf("503 RateLimit = %+v, want headers read only on 429", got) + } +} diff --git a/internal/n8n/n8n_package_test.go b/internal/n8n/n8n_package_test.go index c86c4e5..9f2d7af 100644 --- a/internal/n8n/n8n_package_test.go +++ b/internal/n8n/n8n_package_test.go @@ -311,10 +311,10 @@ func TestImportPackageStreamsMultipart(t *testing.T) { archive := strings.NewReader(packageArchiveBytes) result, err := server.client(t).ImportPackage(context.Background(), ImportPackageRequest{ - WorkflowConflictPolicy: ImportWorkflowConflictFail, - WorkflowIDPolicy: ImportWorkflowIDSource, - ProjectID: "p1", - TagConflictPolicy: ImportTagConflictRename, + ConflictPolicy: ImportConflictFail, + IDPolicy: ImportIDSource, + ProjectID: "p1", + TagConflictPolicy: ImportTagConflictRename, }, archive, "workflows.n8np") if err != nil { t.Fatalf("ImportPackage: %v", err) @@ -327,11 +327,11 @@ func TestImportPackageStreamsMultipart(t *testing.T) { t.Errorf("%s = %q, want API key", HeaderAPIKey, got) } fields, fileBytes, filename := parseMultipartImport(t, req, []byte(raw)) - if fields["workflowConflictPolicy"] != ImportWorkflowConflictFail { - t.Errorf("workflowConflictPolicy = %q, want fail", fields["workflowConflictPolicy"]) + if fields["conflictPolicy"] != ImportConflictFail { + t.Errorf("conflictPolicy = %q, want fail", fields["conflictPolicy"]) } - if fields["workflowIdPolicy"] != ImportWorkflowIDSource { - t.Errorf("workflowIdPolicy = %q, want source", fields["workflowIdPolicy"]) + if fields["idPolicy"] != ImportIDSource { + t.Errorf("idPolicy = %q, want source", fields["idPolicy"]) } if fields["projectId"] != "p1" || fields["tagConflictPolicy"] != ImportTagConflictRename { t.Errorf("fields = %v, want project and tag policies", fields) @@ -376,8 +376,8 @@ func TestImportPackageAcceptsNewModes(t *testing.T) { {ImportCredentialMissingCreateStub, ImportDataTableSchemaOverwriteNonDestructive}, } { _, err := client.ImportPackage(context.Background(), ImportPackageRequest{ - WorkflowConflictPolicy: ImportWorkflowConflictSkip, - WorkflowIDPolicy: ImportWorkflowIDSource, + ConflictPolicy: ImportConflictSkip, + IDPolicy: ImportIDSource, CredentialMissingMode: tc.credential, DataTableSchemaConflict: tc.schema, }, strings.NewReader(packageArchiveBytes), "p.n8np") @@ -401,13 +401,13 @@ func TestImportPackageResultKeepsNewFields(t *testing.T) { "dataTables":{"matched":1,"created":0,"updated":2}, "variables":{"matched":[],"missing":[],"created":[],"stubbed":[],"updated":[]}, "tags":{"matched":[],"created":[],"renamed":[],"reconciled":[],"skipped":[]}, - "agents":{"created":["ag-1"]} + "futureSection":{"created":["ag-1"]} }` server := newCommunityPackageServer(t, packageJSONHandler(http.StatusOK, body)) result, err := server.client(t).ImportPackage(context.Background(), ImportPackageRequest{ - WorkflowConflictPolicy: ImportWorkflowConflictSkip, - WorkflowIDPolicy: ImportWorkflowIDSource, + ConflictPolicy: ImportConflictSkip, + IDPolicy: ImportIDSource, }, strings.NewReader(packageArchiveBytes), "p.n8np") if err != nil { t.Fatalf("ImportPackage: %v", err) @@ -457,8 +457,8 @@ func TestImportPackageDefaultsFilename(t *testing.T) { server := newCommunityPackageServer(t, packageJSONHandler(http.StatusOK, packageImportResultJSON)) _, err := server.client(t).ImportPackage(context.Background(), ImportPackageRequest{ - WorkflowConflictPolicy: ImportWorkflowConflictSkip, - WorkflowIDPolicy: ImportWorkflowIDSource, + ConflictPolicy: ImportConflictSkip, + IDPolicy: ImportIDSource, }, strings.NewReader(packageArchiveBytes), "") if err != nil { t.Fatalf("ImportPackage: %v", err) @@ -477,15 +477,15 @@ func TestImportPackageValidation(t *testing.T) { cases := []ImportPackageRequest{ {}, - {WorkflowConflictPolicy: "sometimes", WorkflowIDPolicy: ImportWorkflowIDSource}, - {WorkflowConflictPolicy: ImportWorkflowConflictFail}, - {WorkflowConflictPolicy: ImportWorkflowConflictFail, WorkflowIDPolicy: "sometimes"}, - {WorkflowConflictPolicy: ImportWorkflowConflictFail, WorkflowIDPolicy: ImportWorkflowIDSource, CredentialMatchingMode: "sometimes"}, - {WorkflowConflictPolicy: ImportWorkflowConflictFail, WorkflowIDPolicy: ImportWorkflowIDSource, Bindings: "[1,2]"}, - {WorkflowConflictPolicy: ImportWorkflowConflictFail, WorkflowIDPolicy: ImportWorkflowIDSource, Bindings: "not-json"}, - {WorkflowConflictPolicy: ImportWorkflowConflictFail, WorkflowIDPolicy: ImportWorkflowIDSource, ProjectID: " padded "}, - {WorkflowConflictPolicy: ImportWorkflowConflictFail, WorkflowIDPolicy: ImportWorkflowIDSource, OverwriteDeletionPolicy: "sometimes"}, - {WorkflowConflictPolicy: ImportWorkflowConflictFail, WorkflowIDPolicy: ImportWorkflowIDSource, VariableParentPolicy: "sometimes"}, + {ConflictPolicy: "sometimes", IDPolicy: ImportIDSource}, + {ConflictPolicy: ImportConflictFail}, + {ConflictPolicy: ImportConflictFail, IDPolicy: "sometimes"}, + {ConflictPolicy: ImportConflictFail, IDPolicy: ImportIDSource, CredentialMatchingMode: "sometimes"}, + {ConflictPolicy: ImportConflictFail, IDPolicy: ImportIDSource, Bindings: "[1,2]"}, + {ConflictPolicy: ImportConflictFail, IDPolicy: ImportIDSource, Bindings: "not-json"}, + {ConflictPolicy: ImportConflictFail, IDPolicy: ImportIDSource, ProjectID: " padded "}, + {ConflictPolicy: ImportConflictFail, IDPolicy: ImportIDSource, OverwriteDeletionPolicy: "sometimes"}, + {ConflictPolicy: ImportConflictFail, IDPolicy: ImportIDSource, VariableParentPolicy: "sometimes"}, } for i, request := range cases { if _, err := client.ImportPackage(context.Background(), request, archive(), "p.n8np"); err == nil { @@ -493,8 +493,8 @@ func TestImportPackageValidation(t *testing.T) { } } if _, err := client.ImportPackage(context.Background(), ImportPackageRequest{ - WorkflowConflictPolicy: ImportWorkflowConflictFail, - WorkflowIDPolicy: ImportWorkflowIDSource, + ConflictPolicy: ImportConflictFail, + IDPolicy: ImportIDSource, }, nil, "p.n8np"); err == nil { t.Error("nil archive: want an error") } @@ -508,8 +508,8 @@ func TestImportPackageBlockedPreservesIssues(t *testing.T) { server := newCommunityPackageServer(t, packageJSONHandler(http.StatusConflict, body)) _, err := server.client(t).ImportPackage(context.Background(), ImportPackageRequest{ - WorkflowConflictPolicy: ImportWorkflowConflictFail, - WorkflowIDPolicy: ImportWorkflowIDSource, + ConflictPolicy: ImportConflictFail, + IDPolicy: ImportIDSource, }, strings.NewReader(packageArchiveBytes), "p.n8np") if err == nil || !IsImportConflict(err) || IsImportUnprocessable(err) { t.Fatalf("error = %v, want a 409 blocked error", err) @@ -537,8 +537,8 @@ func TestImportPackageUnprocessable(t *testing.T) { server := newCommunityPackageServer(t, packageJSONHandler(http.StatusUnprocessableEntity, body)) _, err := server.client(t).ImportPackage(context.Background(), ImportPackageRequest{ - WorkflowConflictPolicy: ImportWorkflowConflictSkip, - WorkflowIDPolicy: ImportWorkflowIDNew, + ConflictPolicy: ImportConflictSkip, + IDPolicy: ImportIDNew, }, strings.NewReader(packageArchiveBytes), "p.n8np") if err == nil || !IsImportUnprocessable(err) || IsImportConflict(err) { t.Fatalf("error = %v, want a 422 blocked error", err) @@ -560,8 +560,8 @@ func TestImportPackageOtherErrors(t *testing.T) { t.Run(tc.name, func(t *testing.T) { server := newCommunityPackageServer(t, packageJSONHandler(tc.status, tc.body)) _, err := server.client(t).ImportPackage(context.Background(), ImportPackageRequest{ - WorkflowConflictPolicy: ImportWorkflowConflictSkip, - WorkflowIDPolicy: ImportWorkflowIDSource, + ConflictPolicy: ImportConflictSkip, + IDPolicy: ImportIDSource, }, strings.NewReader(packageArchiveBytes), "p.n8np") if err == nil || !tc.check(err) { t.Fatalf("error = %v, want the %d behavior", err, tc.status) @@ -580,8 +580,8 @@ func TestImportPackageSelectionStreamsMultipart(t *testing.T) { ProjectID: "src-project", WorkflowIDs: []string{"wf-1", "wf-2"}, DeletedWorkflowIDs: []string{"wf-3"}, - WorkflowConflictPolicy: ImportWorkflowConflictSkip, - WorkflowIDPolicy: ImportWorkflowIDNew, + ConflictPolicy: ImportConflictSkip, + IDPolicy: ImportIDNew, OverwriteDeletionPolicy: ImportDeletionHardDelete, }, strings.NewReader(packageArchiveBytes), "project.n8np") if err != nil { @@ -599,8 +599,8 @@ func TestImportPackageSelectionStreamsMultipart(t *testing.T) { "selectedProjectId": "src-project", "selectedWorkflowIds": `["wf-1","wf-2"]`, "deletedWorkflowIds": `["wf-3"]`, - "workflowConflictPolicy": ImportWorkflowConflictSkip, - "workflowIdPolicy": ImportWorkflowIDNew, + "conflictPolicy": ImportConflictSkip, + "idPolicy": ImportIDNew, "overwriteDeletionPolicy": ImportDeletionHardDelete, } if diff := cmp.Diff(want, fields); diff != "" { @@ -620,7 +620,7 @@ func TestImportPackageSelectionOmitsUnsetFields(t *testing.T) { _, err := server.client(t).ImportPackageSelection(context.Background(), ImportPackageSelectionRequest{ ProjectID: "src-project", DeletedWorkflowIDs: []string{"wf-3"}, - WorkflowIDPolicy: ImportWorkflowIDSource, + IDPolicy: ImportIDSource, }, strings.NewReader(packageArchiveBytes), "") if err != nil { t.Fatalf("ImportPackageSelection: %v", err) @@ -631,7 +631,7 @@ func TestImportPackageSelectionOmitsUnsetFields(t *testing.T) { "selectedProjectId": "src-project", "selectedWorkflowIds": `[]`, "deletedWorkflowIds": `["wf-3"]`, - "workflowIdPolicy": ImportWorkflowIDSource, + "idPolicy": ImportIDSource, } if diff := cmp.Diff(want, fields); diff != "" { t.Errorf("delete-only fields mismatch (-want +got):\n%s", diff) @@ -641,16 +641,16 @@ func TestImportPackageSelectionOmitsUnsetFields(t *testing.T) { } _, err = server.client(t).ImportPackageSelection(context.Background(), ImportPackageSelectionRequest{ - ProjectID: "src-project", - WorkflowIDs: []string{"wf-1"}, - WorkflowIDPolicy: ImportWorkflowIDSource, + ProjectID: "src-project", + WorkflowIDs: []string{"wf-1"}, + IDPolicy: ImportIDSource, }, strings.NewReader(packageArchiveBytes), "p.n8np") if err != nil { t.Fatalf("ImportPackageSelection: %v", err) } req, raw = server.last(t) fields, _, _ = parseMultipartImport(t, req, []byte(raw)) - for _, name := range []string{"deletedWorkflowIds", "workflowConflictPolicy", "overwriteDeletionPolicy"} { + for _, name := range []string{"deletedWorkflowIds", "conflictPolicy", "overwriteDeletionPolicy"} { if _, present := fields[name]; present { t.Errorf("%s = present, want omitted when unset", name) } @@ -663,9 +663,9 @@ func TestImportPackageSelectionValidation(t *testing.T) { base := func(mutate func(*ImportPackageSelectionRequest)) ImportPackageSelectionRequest { request := ImportPackageSelectionRequest{ - ProjectID: "p", - WorkflowIDs: []string{"a"}, - WorkflowIDPolicy: ImportWorkflowIDSource, + ProjectID: "p", + WorkflowIDs: []string{"a"}, + IDPolicy: ImportIDSource, } mutate(&request) return request @@ -680,9 +680,9 @@ func TestImportPackageSelectionValidation(t *testing.T) { "duplicate deleted": base(func(r *ImportPackageSelectionRequest) { r.DeletedWorkflowIDs = []string{"b", "b"} }), "selected and deleted": base(func(r *ImportPackageSelectionRequest) { r.DeletedWorkflowIDs = []string{"a"} }), "empty deleted id": base(func(r *ImportPackageSelectionRequest) { r.DeletedWorkflowIDs = []string{" "} }), - "bad conflict policy": base(func(r *ImportPackageSelectionRequest) { r.WorkflowConflictPolicy = "sometimes" }), - "missing id policy": base(func(r *ImportPackageSelectionRequest) { r.WorkflowIDPolicy = "" }), - "bad id policy": base(func(r *ImportPackageSelectionRequest) { r.WorkflowIDPolicy = "sometimes" }), + "bad conflict policy": base(func(r *ImportPackageSelectionRequest) { r.ConflictPolicy = "sometimes" }), + "missing id policy": base(func(r *ImportPackageSelectionRequest) { r.IDPolicy = "" }), + "bad id policy": base(func(r *ImportPackageSelectionRequest) { r.IDPolicy = "sometimes" }), "bad deletion policy": base(func(r *ImportPackageSelectionRequest) { r.DeletedWorkflowIDs = []string{"b"} r.OverwriteDeletionPolicy = "sometimes" @@ -716,7 +716,7 @@ func TestImportPackageSelectionBlocked(t *testing.T) { ProjectID: "p", WorkflowIDs: []string{"a"}, DeletedWorkflowIDs: []string{"b"}, - WorkflowIDPolicy: ImportWorkflowIDNew, + IDPolicy: ImportIDNew, }, strings.NewReader(packageArchiveBytes), "p.n8np") if err == nil || !tc.check(err) { t.Fatalf("%d: error = %v, want a blocked error", tc.status, err) @@ -745,9 +745,9 @@ func TestImportPackageSelectionOtherErrors(t *testing.T) { t.Run(tc.name, func(t *testing.T) { server := newCommunityPackageServer(t, packageJSONHandler(tc.status, tc.body)) _, err := server.client(t).ImportPackageSelection(context.Background(), ImportPackageSelectionRequest{ - ProjectID: "p", - WorkflowIDs: []string{"a"}, - WorkflowIDPolicy: ImportWorkflowIDSource, + ProjectID: "p", + WorkflowIDs: []string{"a"}, + IDPolicy: ImportIDSource, }, strings.NewReader(packageArchiveBytes), "p.n8np") if err == nil || !tc.check(err) { t.Fatalf("error = %v, want the %d behavior", err, tc.status) @@ -764,9 +764,9 @@ func TestImportPackageSelectionCancellation(t *testing.T) { ctx, cancel := context.WithCancel(context.Background()) cancel() _, err := server.client(t).ImportPackageSelection(ctx, ImportPackageSelectionRequest{ - ProjectID: "p", - WorkflowIDs: []string{"a"}, - WorkflowIDPolicy: ImportWorkflowIDSource, + ProjectID: "p", + WorkflowIDs: []string{"a"}, + IDPolicy: ImportIDSource, }, strings.NewReader(packageArchiveBytes), "p.n8np") if !errors.Is(err, context.Canceled) { t.Errorf("error = %v, want context.Canceled", err) @@ -779,9 +779,9 @@ func TestImportPackageCredentialConflictPolicy(t *testing.T) { for _, policy := range []string{ImportCredentialConflictKeep, ImportCredentialConflictOverwrite, ImportCredentialConflictFail} { _, err := client.ImportPackage(context.Background(), ImportPackageRequest{ - WorkflowConflictPolicy: ImportWorkflowConflictSkip, - WorkflowIDPolicy: ImportWorkflowIDSource, - CredentialConflict: policy, + ConflictPolicy: ImportConflictSkip, + IDPolicy: ImportIDSource, + CredentialConflict: policy, }, strings.NewReader(packageArchiveBytes), "p.n8np") if err != nil { t.Fatalf("ImportPackage(%s): %v", policy, err) @@ -794,8 +794,8 @@ func TestImportPackageCredentialConflictPolicy(t *testing.T) { } _, err := client.ImportPackage(context.Background(), ImportPackageRequest{ - WorkflowConflictPolicy: ImportWorkflowConflictSkip, - WorkflowIDPolicy: ImportWorkflowIDSource, + ConflictPolicy: ImportConflictSkip, + IDPolicy: ImportIDSource, }, strings.NewReader(packageArchiveBytes), "p.n8np") if err != nil { t.Fatalf("ImportPackage(unset): %v", err) @@ -808,9 +808,9 @@ func TestImportPackageCredentialConflictPolicy(t *testing.T) { before := len(server.requests) _, err = client.ImportPackage(context.Background(), ImportPackageRequest{ - WorkflowConflictPolicy: ImportWorkflowConflictSkip, - WorkflowIDPolicy: ImportWorkflowIDSource, - CredentialConflict: "replace", + ConflictPolicy: ImportConflictSkip, + IDPolicy: ImportIDSource, + CredentialConflict: "replace", }, strings.NewReader(packageArchiveBytes), "p.n8np") if err == nil || !strings.Contains(err.Error(), "credential-conflict policy") || !strings.Contains(err.Error(), "keep-existing, overwrite, fail") { t.Errorf("error = %v, want the unknown policy named with the allowed values", err) @@ -841,9 +841,9 @@ func TestImportPackageResultCredentialsUpdated(t *testing.T) { t.Run(tc.name, func(t *testing.T) { server := newCommunityPackageServer(t, packageJSONHandler(http.StatusOK, tc.body)) result, err := server.client(t).ImportPackageSelection(context.Background(), ImportPackageSelectionRequest{ - ProjectID: "p", - WorkflowIDs: []string{"a"}, - WorkflowIDPolicy: ImportWorkflowIDSource, + ProjectID: "p", + WorkflowIDs: []string{"a"}, + IDPolicy: ImportIDSource, }, strings.NewReader(packageArchiveBytes), "p.n8np") if err != nil { t.Fatalf("ImportPackageSelection: %v", err) @@ -965,9 +965,9 @@ func TestImportPackageBlockedDecodesNewIssues(t *testing.T) { } { server := newCommunityPackageServer(t, packageJSONHandler(tc.status, body)) _, err := server.client(t).ImportPackage(context.Background(), ImportPackageRequest{ - WorkflowConflictPolicy: ImportWorkflowConflictFail, - WorkflowIDPolicy: ImportWorkflowIDSource, - CredentialConflict: ImportCredentialConflictOverwrite, + ConflictPolicy: ImportConflictFail, + IDPolicy: ImportIDSource, + CredentialConflict: ImportCredentialConflictOverwrite, }, strings.NewReader(packageArchiveBytes), "p.n8np") if !tc.check(err) { t.Fatalf("%d: error = %v, want a blocked error", tc.status, err) diff --git a/internal/n8n/promotion.go b/internal/n8n/promotion.go index 9112b27..cdd52df 100644 --- a/internal/n8n/promotion.go +++ b/internal/n8n/promotion.go @@ -719,28 +719,36 @@ type PromotionApplyCounts struct { } // Apply outcomes. The apply response is a union on status: only applied -// wrote anything. An unknown status is kept as sent so a newer server never -// fails the decode. +// wrote anything. preview-changed (n8n 2.47 and later) answers a project +// apply whose expectedPreviewRevision no longer matches, and an environment +// apply whose preview changed during the run. An unknown status is kept as +// sent so a newer server never fails the decode. const ( - PromotionApplyStatusApplied = "applied" - PromotionApplyStatusBlocked = "blocked" - PromotionApplyStatusSourceChanged = "source-changed" + PromotionApplyStatusApplied = "applied" + PromotionApplyStatusBlocked = "blocked" + PromotionApplyStatusSourceChanged = "source-changed" + PromotionApplyStatusPreviewChanged = "preview-changed" ) -// Preflight conflict codes that need explicit confirmation at continue time. +// Check conflict codes that need explicit confirmation at continue time. const ( PromotionConflictProjectDeletion = "project-deletion" PromotionConflictDestructiveChange = "destructive-change" ) -// PromotionRef names one project or workflow in a preflight item. +// PromotionConflictMoved (n8n 2.47 and later) is a workflow or folder the +// branch and the instance hold in different projects. Apply cannot move it +// between projects. +const PromotionConflictMoved = "moved" + +// PromotionRef names one project or workflow in a check item. type PromotionRef struct { ID string `json:"id"` Name string `json:"name"` } // PromotionConsumer is one project and the workflows in it that reference a -// preflight item. +// check item. type PromotionConsumer struct { Project PromotionRef `json:"project"` Workflows []PromotionRef `json:"workflows"` @@ -764,32 +772,40 @@ type PromotionDataTableChange struct { Destructive bool `json:"destructive"` } -// PromotionApplyIssue is one preflight item or warning: a missing binding, -// an access requirement, a conflict, or a warning. Kind (credential, variable, -// project, data-table) and Code discriminate; the remaining fields are the -// union of the documented variants, and only those a variant carries are set. -// The full document is preserved verbatim so new variants survive without a -// client change. +// PromotionApplyIssue is one check item or warning: a missing binding, an +// access requirement, a conflict, or a warning. Kind (credential, variable, +// project, data-table, and from n8n 2.47 workflow, folder, and tag) and Code +// discriminate; the remaining fields are the union of the documented +// variants, and only those a variant carries are set. The full document is +// preserved verbatim so new variants survive without a client change. +// +// Reason explains a 2.47 workflow, data-table, tag, or project conflict. +// ProjectExists and InstanceProject belong to the 2.47 moved conflict: the +// workflow or folder is in Project on the branch and in InstanceProject here; +// ProjectExists reports whether the branch project exists on the instance. type PromotionApplyIssue struct { - Kind string `json:"kind"` - Code string `json:"code,omitempty"` - ID string `json:"id,omitempty"` - Name string `json:"name,omitempty"` - SourceID *string `json:"sourceId,omitempty"` - CredentialType string `json:"credentialType,omitempty"` - ExpectedTypes []string `json:"expectedTypes,omitempty"` - TargetType string `json:"targetType,omitempty"` - UsageScope string `json:"usageScope,omitempty"` - VariableType string `json:"variableType,omitempty"` - Scope *PromotionVariableScope `json:"scope,omitempty"` - Project *PromotionRef `json:"project,omitempty"` - OwnerProject *PromotionRef `json:"ownerProject,omitempty"` - FilePath string `json:"filePath,omitempty"` - ReferenceFiles []string `json:"referenceFiles,omitempty"` - Workflows []PromotionRef `json:"workflows,omitempty"` - Consumers []PromotionConsumer `json:"consumers,omitempty"` - Changes []PromotionDataTableChange `json:"changes,omitempty"` - Raw json.RawMessage `json:"-"` + Kind string `json:"kind"` + Code string `json:"code,omitempty"` + ID string `json:"id,omitempty"` + Name string `json:"name,omitempty"` + Reason string `json:"reason,omitempty"` + ProjectExists *bool `json:"projectExists,omitempty"` + InstanceProject *PromotionRef `json:"instanceProject,omitempty"` + SourceID *string `json:"sourceId,omitempty"` + CredentialType string `json:"credentialType,omitempty"` + ExpectedTypes []string `json:"expectedTypes,omitempty"` + TargetType string `json:"targetType,omitempty"` + UsageScope string `json:"usageScope,omitempty"` + VariableType string `json:"variableType,omitempty"` + Scope *PromotionVariableScope `json:"scope,omitempty"` + Project *PromotionRef `json:"project,omitempty"` + OwnerProject *PromotionRef `json:"ownerProject,omitempty"` + FilePath string `json:"filePath,omitempty"` + ReferenceFiles []string `json:"referenceFiles,omitempty"` + Workflows []PromotionRef `json:"workflows,omitempty"` + Consumers []PromotionConsumer `json:"consumers,omitempty"` + Changes []PromotionDataTableChange `json:"changes,omitempty"` + Raw json.RawMessage `json:"-"` } // UnmarshalJSON decodes the typed view and keeps the verbatim document. @@ -823,7 +839,8 @@ type PromotionMissingProject struct { CustomTelemetryTags json.RawMessage `json:"customTelemetryTags,omitempty"` } -// PromotionApplyPreflight lists why a blocked apply wrote nothing. +// PromotionApplyPreflight lists why a blocked apply wrote nothing. n8n 2.47 +// sends it as check, older instances as preflight; the shape is the same. type PromotionApplyPreflight struct { MissingProjects []PromotionMissingProject `json:"missingProjects"` MissingBindings []PromotionApplyIssue `json:"missingBindings"` @@ -832,7 +849,7 @@ type PromotionApplyPreflight struct { Warnings []PromotionApplyIssue `json:"warnings"` } -// Empty reports whether the preflight lists nothing at all. +// Empty reports whether the check lists nothing at all. func (p PromotionApplyPreflight) Empty() bool { return len(p.MissingProjects) == 0 && len(p.MissingBindings) == 0 && len(p.AccessRequirements) == 0 && len(p.Conflicts) == 0 && len(p.Warnings) == 0 @@ -907,8 +924,9 @@ func (s PromotionExpectedSource) ValidateConfig() error { // ApplyPromotionResult is the apply acknowledgement. Inspect Status before // reading anything else: applied carries Counts and Warnings; blocked carries -// Preflight and wrote nothing; source-changed carries neither and wrote -// nothing. ConfigID (before n8n 2.46) or EnvironmentID (2.46 and later) and +// Check (n8n 2.47 and later) or Preflight (older) and wrote nothing, see +// [ApplyPromotionResult.Blockers]; source-changed and preview-changed carry +// neither and wrote nothing. ConfigID (before n8n 2.46) or EnvironmentID (2.46 and later) and // Git identify the source for a later continue; older instances also report // ConnectionID. // @@ -923,6 +941,7 @@ type ApplyPromotionResult struct { Git PromotionGit `json:"git"` Counts *PromotionApplyCounts `json:"counts,omitempty"` Warnings []PromotionApplyIssue `json:"warnings,omitempty"` + Check *PromotionApplyPreflight `json:"check,omitempty"` Preflight *PromotionApplyPreflight `json:"preflight,omitempty"` Extra map[string]json.RawMessage `json:"-"` raw json.RawMessage @@ -931,7 +950,7 @@ type ApplyPromotionResult struct { // applyPromotionResultFields are the field names [ApplyPromotionResult] // decodes itself. Anything else lands in Extra. var applyPromotionResultFields = []string{ - "connectionId", "configId", "environmentId", "status", "git", "counts", "warnings", "preflight", + "connectionId", "configId", "environmentId", "status", "git", "counts", "warnings", "check", "preflight", } // UnmarshalJSON decodes by shape, keeps unknown fields in Extra, and keeps the @@ -997,6 +1016,15 @@ func (r ApplyPromotionResult) Applied() bool { return r.Status == PromotionApplyStatusApplied || (r.Status == "" && r.Counts != nil) } +// Blockers returns why a blocked apply wrote nothing: check from n8n 2.47, +// preflight from older instances, or nil when the response carries neither. +func (r ApplyPromotionResult) Blockers() *PromotionApplyPreflight { + if r.Check != nil { + return r.Check + } + return r.Preflight +} + // ExpectedSource returns the source a continue must name: the environment or // config and the branch and commit this result was checked against. The // identifier is the one the instance returned; environmentId wins when a diff --git a/internal/n8n/promotion_check_test.go b/internal/n8n/promotion_check_test.go new file mode 100644 index 0000000..89d89e4 --- /dev/null +++ b/internal/n8n/promotion_check_test.go @@ -0,0 +1,204 @@ +package n8n + +import ( + "context" + "encoding/json" + "net/http" + "reflect" + "strings" + "testing" +) + +// n8n 2.47 apply shapes: blocked carries check instead of preflight, with +// workflow, data-table, tag, project, and moved conflicts; preview-changed +// joins the status union; project apply bodies take expectedPreviewRevision; +// and environments list their missing projects. + +const previewRevision = "abcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcd" + +const checkBlockedResultBody = `{ + "environmentId":"` + testEnvironmentID + `", + "git":{"commitSha":"` + selectionSHA + `","branchName":"main"}, + "status":"blocked", + "check":{ + "missingProjects":[{"id":"p-9","name":"Ops"}], + "missingBindings":[], + "accessRequirements":[], + "conflicts":[ + {"kind":"workflow","code":"lineage-conflict","reason":"history diverged","consumers":[{"project":{"id":"p1","name":"Sales"},"workflows":[{"id":"w1","name":"Lead"}]}]}, + {"kind":"tag","code":"tag-conflict","id":"t1","name":"prod","reason":"renamed here","consumers":[{"project":{"id":"p1","name":"Sales"},"workflows":[{"id":"w1","name":"Lead"}]}]}, + {"kind":"project","code":"project-not-on-branch","project":{"id":"p2","name":"Ops"},"reason":"absent"}, + {"kind":"folder","code":"moved","id":"f1","name":"Inbox","project":{"id":"p1","name":"Sales"},"projectExists":false,"instanceProject":{"id":"p3","name":"Support"}} + ], + "warnings":[] + } +}` + +func TestApplyPromotionResultDecodesCheck(t *testing.T) { + var result ApplyPromotionResult + if err := json.Unmarshal([]byte(checkBlockedResultBody), &result); err != nil { + t.Fatal(err) + } + if result.Status != PromotionApplyStatusBlocked || result.Applied() || result.Preflight != nil || result.Extra != nil { + t.Fatalf("result = %+v, want blocked with check only", result) + } + check := result.Blockers() + if check == nil || check != result.Check || len(check.MissingProjects) != 1 || len(check.Conflicts) != 4 { + t.Fatalf("blockers = %+v, want the check", check) + } + workflow, tag, project, moved := check.Conflicts[0], check.Conflicts[1], check.Conflicts[2], check.Conflicts[3] + if workflow.Reason != "history diverged" || len(workflow.Consumers) != 1 { + t.Errorf("workflow conflict = %+v", workflow) + } + if tag.ID != "t1" || tag.Reason != "renamed here" { + t.Errorf("tag conflict = %+v", tag) + } + if project.Project == nil || project.Project.ID != "p2" || project.Reason != "absent" { + t.Errorf("project conflict = %+v", project) + } + if moved.Code != PromotionConflictMoved || moved.ProjectExists == nil || *moved.ProjectExists || + moved.InstanceProject == nil || moved.InstanceProject.ID != "p3" || moved.Project.ID != "p1" { + t.Errorf("moved conflict = %+v", moved) + } + encoded, err := json.Marshal(result) + if err != nil { + t.Fatal(err) + } + var got, want any + if err := json.Unmarshal(encoded, &got); err != nil { + t.Fatal(err) + } + if err := json.Unmarshal([]byte(checkBlockedResultBody), &want); err != nil { + t.Fatal(err) + } + if !reflect.DeepEqual(got, want) { + t.Errorf("response not preserved: %s", encoded) + } + + // Older instances still send preflight; Blockers falls back to it. + var older ApplyPromotionResult + if err := json.Unmarshal([]byte(envBlockedResultBody), &older); err != nil { + t.Fatal(err) + } + if older.Check != nil || older.Blockers() == nil || older.Blockers() != older.Preflight { + t.Errorf("older blockers = %+v, want preflight", older.Blockers()) + } + var none ApplyPromotionResult + if none.Blockers() != nil { + t.Error("zero result has blockers") + } +} + +func TestApplyPromotionResultPreviewChanged(t *testing.T) { + body := `{"environmentId":"` + testEnvironmentID + `","git":{"commitSha":"` + selectionSHA + `","branchName":"main"},"status":"preview-changed"}` + var result ApplyPromotionResult + if err := json.Unmarshal([]byte(body), &result); err != nil { + t.Fatal(err) + } + if result.Status != PromotionApplyStatusPreviewChanged || result.Applied() || result.Blockers() != nil { + t.Errorf("result = %+v, want preview-changed that wrote nothing", result) + } +} + +func TestProjectSelectionExpectedPreviewRevision(t *testing.T) { + source := PromotionExpectedSource{EnvironmentID: testEnvironmentID, BranchName: "main", CommitSHA: selectionSHA} + cases := []struct { + name, path, body string + call func(context.Context, *Client) (any, error) + }{ + {"apply omits an empty revision", "/promotions/projects/p1/apply", `{"workflowIds":["w1"]}`, func(ctx context.Context, c *Client) (any, error) { + return c.ApplyProjectSelection(ctx, "p1", ApplyProjectSelectionRequest{WorkflowIDs: []string{"w1"}}) + }}, + {"apply sends the revision", "/promotions/projects/p1/apply", `{"workflowIds":["w1"],"expectedPreviewRevision":"` + previewRevision + `"}`, func(ctx context.Context, c *Client) (any, error) { + return c.ApplyProjectSelection(ctx, "p1", ApplyProjectSelectionRequest{WorkflowIDs: []string{"w1"}, ExpectedPreviewRevision: previewRevision}) + }}, + {"continue sends the revision", "/promotions/projects/p1/apply/continue", `{"workflowIds":["w1"],"expectedSource":` + envSourceJSON + `,"expectedPreviewRevision":"` + previewRevision + `"}`, func(ctx context.Context, c *Client) (any, error) { + return c.ContinueApplyProjectSelection(ctx, "p1", ContinueApplyProjectSelectionRequest{WorkflowIDs: []string{"w1"}, ExpectedSource: source, ExpectedPreviewRevision: previewRevision}) + }}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + server := newCommunityPackageServer(t, packageJSONHandler(http.StatusOK, envAppliedResultBody)) + if _, err := tc.call(context.Background(), server.client(t)); err != nil { + t.Fatal(err) + } + req, body := server.last(t) + if req.URL.EscapedPath() != BasePath+tc.path || body != tc.body { + t.Errorf("request = %s %s, want %s %s", req.URL.EscapedPath(), body, BasePath+tc.path, tc.body) + } + }) + } + + server := newCommunityPackageServer(t, packageJSONHandler(http.StatusOK, envAppliedResultBody)) + client := server.client(t) + for _, bad := range []string{"abc", strings.ToUpper(previewRevision), previewRevision + "0"} { + _, err := client.ApplyProjectSelection(context.Background(), "p1", ApplyProjectSelectionRequest{WorkflowIDs: []string{"w1"}, ExpectedPreviewRevision: bad}) + if err == nil || !strings.Contains(err.Error(), "64 lowercase hex") { + t.Errorf("apply revision %q: error = %v", bad, err) + } + _, err = client.ContinueApplyProjectSelection(context.Background(), "p1", ContinueApplyProjectSelectionRequest{WorkflowIDs: []string{"w1"}, ExpectedSource: source, ExpectedPreviewRevision: bad}) + if err == nil || !strings.Contains(err.Error(), "64 lowercase hex") { + t.Errorf("continue revision %q: error = %v", bad, err) + } + } + if len(server.requests) != 0 { + t.Errorf("%d request(s) sent for invalid revisions", len(server.requests)) + } +} + +const missingProjectsBody = `{ + "environmentId":"` + testEnvironmentID + `", + "git":{"commitSha":"` + selectionSHA + `","branchName":"main"}, + "data":[{"id":"p-9","name":"Ops","icon":{"type":"emoji","value":"📣"},"description":"Operations","customTelemetryTags":[{"key":"team","value":"ops"}],"future":true}] +}` + +func TestGetPromotionEnvironmentMissingProjects(t *testing.T) { + server := newCommunityPackageServer(t, packageJSONHandler(http.StatusOK, missingProjectsBody)) + result, err := server.client(t).GetPromotionEnvironmentMissingProjects(context.Background(), testEnvironmentID) + if err != nil { + t.Fatal(err) + } + req, _ := server.last(t) + if want := BasePath + PromotionEnvironmentsPath + "/" + testEnvironmentID + "/missing-projects"; req.Method != http.MethodGet || req.URL.EscapedPath() != want { + t.Errorf("request = %s %s, want GET %s", req.Method, req.URL.EscapedPath(), want) + } + if result.EnvironmentID != testEnvironmentID || result.Git == nil || result.Git.CommitSHA != selectionSHA || + len(result.Data) != 1 || result.Data[0].ID != "p-9" || result.Data[0].Description != "Operations" { + t.Errorf("result = %+v", result) + } + encoded, err := json.Marshal(result) + if err != nil { + t.Fatal(err) + } + var got, want any + if err := json.Unmarshal(encoded, &got); err != nil { + t.Fatal(err) + } + if err := json.Unmarshal([]byte(missingProjectsBody), &want); err != nil { + t.Fatal(err) + } + if !reflect.DeepEqual(got, want) { + t.Errorf("response not preserved: %s", encoded) + } + + empty := newCommunityPackageServer(t, packageJSONHandler(http.StatusOK, `{"environmentId":"`+testEnvironmentID+`","git":null,"data":[]}`)) + result, err = empty.client(t).GetPromotionEnvironmentMissingProjects(context.Background(), testEnvironmentID) + if err != nil || result.Git != nil || len(result.Data) != 0 { + t.Errorf("empty result = %+v, %v", result, err) + } + + for _, status := range []int{400, 403, 404, 503} { + s := newCommunityPackageServer(t, packageJSONHandler(status, `{"message":"failure"}`)) + if _, err := s.client(t).GetPromotionEnvironmentMissingProjects(context.Background(), testEnvironmentID); !IsStatus(err, status) { + t.Errorf("status %d: error = %v", status, err) + } + } + + invalid := newCommunityPackageServer(t, packageJSONHandler(http.StatusOK, missingProjectsBody)) + if _, err := invalid.client(t).GetPromotionEnvironmentMissingProjects(context.Background(), " "); err == nil { + t.Error("blank environment ID accepted") + } + if len(invalid.requests) != 0 { + t.Error("invalid ID reached the instance") + } +} diff --git a/internal/n8n/promotion_environment.go b/internal/n8n/promotion_environment.go index dad0ed6..65c379f 100644 --- a/internal/n8n/promotion_environment.go +++ b/internal/n8n/promotion_environment.go @@ -2,6 +2,7 @@ package n8n import ( "context" + "encoding/json" "fmt" "net/http" "net/url" @@ -375,6 +376,56 @@ func (c *Client) ListPromotionEnvironmentProjects(ctx context.Context, id string return &projects, nil } +// PromotionEnvironmentMissingProjects lists the team projects of the package +// at an apply environment's branch tip whose IDs do not exist on this +// instance (n8n 2.47 and later). Git is nil when the branch has no package +// yet; empty Data means no project needs to be created. +// +// The response is kept verbatim: MarshalJSON re-emits it, so --output json +// keeps fields this type does not name. +type PromotionEnvironmentMissingProjects struct { + EnvironmentID string `json:"environmentId"` + Git *PromotionGit `json:"git"` + Data []PromotionMissingProject `json:"data"` + raw json.RawMessage +} + +// UnmarshalJSON decodes the named fields and keeps the verbatim document. +func (r *PromotionEnvironmentMissingProjects) UnmarshalJSON(data []byte) error { + type plain PromotionEnvironmentMissingProjects + var decoded plain + if err := json.Unmarshal(data, &decoded); err != nil { + return err + } + *r = PromotionEnvironmentMissingProjects(decoded) + r.raw = append(json.RawMessage(nil), data...) + return nil +} + +// MarshalJSON re-emits the verbatim document when present. +func (r PromotionEnvironmentMissingProjects) MarshalJSON() ([]byte, error) { + if len(r.raw) > 0 { + return r.raw, nil + } + type plain PromotionEnvironmentMissingProjects + return json.Marshal(plain(r)) +} + +// GetPromotionEnvironmentMissingProjects reads the package at the branch tip +// of a connected instance-scope apply environment and returns its team +// projects missing on this instance, matched by ID. Create each with the +// returned ID before applying it. The route exists from n8n 2.47. +func (c *Client) GetPromotionEnvironmentMissingProjects(ctx context.Context, id string) (*PromotionEnvironmentMissingProjects, error) { + if err := ValidatePromotionEnvironmentID(id); err != nil { + return nil, err + } + var result PromotionEnvironmentMissingProjects + if _, err := c.Do(ctx, Request{Path: PathJoin("promotions", "environments", id, "missing-projects")}, &result); err != nil { + return nil, err + } + return &result, nil +} + // AddProjectToPromotionEnvironment links one team project to a projects-scope // environment. A project can have one environment per direction; a second // link for the same direction answers 409. diff --git a/internal/n8n/promotion_selection.go b/internal/n8n/promotion_selection.go index 8637fde..4b9dad1 100644 --- a/internal/n8n/promotion_selection.go +++ b/internal/n8n/promotion_selection.go @@ -6,6 +6,7 @@ import ( "fmt" "net/http" "net/url" + "regexp" "strings" "unicode/utf8" ) @@ -200,26 +201,37 @@ type ContinueApplyPromotionRequest struct { func (r ContinueApplyPromotionRequest) Validate() error { return r.ExpectedSource.ValidateConfig() } // ApplyProjectSelectionRequest applies only selected workflow changes. +// +// ExpectedPreviewRevision (n8n 2.47 and later) pins the reviewed Apply +// preview: when the rebuilt preview differs, the server answers status +// preview-changed and writes nothing. Older instances reject the field, so it +// is sent only when set. type ApplyProjectSelectionRequest struct { - WorkflowIDs []string `json:"workflowIds"` - ExpectedSource *PromotionExpectedSource `json:"expectedSource,omitempty"` + WorkflowIDs []string `json:"workflowIds"` + ExpectedSource *PromotionExpectedSource `json:"expectedSource,omitempty"` + ExpectedPreviewRevision string `json:"expectedPreviewRevision,omitempty"` } -// Validate rejects invalid selections and incomplete expected sources. +// Validate rejects invalid selections, incomplete expected sources, and +// malformed preview revisions. func (r ApplyProjectSelectionRequest) Validate() error { if err := validatePromotionWorkflowIDs(r.WorkflowIDs); err != nil { return err } if r.ExpectedSource != nil { - return r.ExpectedSource.Validate() + if err := r.ExpectedSource.Validate(); err != nil { + return err + } } - return nil + return ValidatePromotionPreviewRevision(r.ExpectedPreviewRevision) } // ContinueApplyProjectSelectionRequest must repeat the full reviewed selection. +// ExpectedPreviewRevision works as in [ApplyProjectSelectionRequest]. type ContinueApplyProjectSelectionRequest struct { WorkflowIDs []string `json:"workflowIds"` ExpectedSource PromotionExpectedSource `json:"expectedSource"` + ExpectedPreviewRevision string `json:"expectedPreviewRevision,omitempty"` ConfirmDestructiveChanges *bool `json:"confirmDestructiveChanges,omitempty"` } @@ -228,7 +240,22 @@ func (r ContinueApplyProjectSelectionRequest) Validate() error { if err := validatePromotionWorkflowIDs(r.WorkflowIDs); err != nil { return err } - return r.ExpectedSource.Validate() + if err := r.ExpectedSource.Validate(); err != nil { + return err + } + return ValidatePromotionPreviewRevision(r.ExpectedPreviewRevision) +} + +var promotionPreviewRevision = regexp.MustCompile(`^[0-9a-f]{64}$`) + +// ValidatePromotionPreviewRevision accepts an empty revision (not sent) or the +// 64 lowercase hex digits n8n 2.47 and later return as an Apply preview +// revision. +func ValidatePromotionPreviewRevision(revision string) error { + if revision == "" || promotionPreviewRevision.MatchString(revision) { + return nil + } + return fmt.Errorf("expected preview revision %q must be 64 lowercase hex digits: copy the revision of the reviewed Apply preview", revision) } // PromoteProjectSelectionRequest pushes selected workflows without force support. diff --git a/internal/n8n/rate_limit.go b/internal/n8n/rate_limit.go new file mode 100644 index 0000000..5a93271 --- /dev/null +++ b/internal/n8n/rate_limit.go @@ -0,0 +1,143 @@ +package n8n + +import ( + "context" + "fmt" + "net/http" +) + +// RateLimitSettingsPath is the Public API rate-limit settings endpoint (n8n +// 2.47 and later). +const RateLimitSettingsPath = "/settings/rate-limits" + +// RateLimitSettings is the effective Public API rate-limit configuration. A +// limit of 0 means no limit; windows are in seconds. EnvManagedFields lists +// the fields environment variables control: the API reports their effective +// values and refuses to change them. +type RateLimitSettings struct { + Enabled bool `json:"enabled"` + GlobalReadLimit int `json:"globalReadLimit"` + GlobalReadWindowSeconds int `json:"globalReadWindowSeconds"` + GlobalWriteLimit int `json:"globalWriteLimit"` + GlobalWriteWindowSeconds int `json:"globalWriteWindowSeconds"` + EndpointReadLimit int `json:"endpointReadLimit"` + EndpointReadWindowSeconds int `json:"endpointReadWindowSeconds"` + EndpointWriteLimit int `json:"endpointWriteLimit"` + EndpointWriteWindowSeconds int `json:"endpointWriteWindowSeconds"` + EnvManagedFields []string `json:"envManagedFields"` +} + +// UpdateRateLimitSettingsRequest is a full replacement document: every field +// is required. Pointers distinguish an omitted field from false or 0. +// envManagedFields is read-only and has no field here, so it is never sent. +type UpdateRateLimitSettingsRequest struct { + Enabled *bool `json:"enabled"` + GlobalReadLimit *int `json:"globalReadLimit"` + GlobalReadWindowSeconds *int `json:"globalReadWindowSeconds"` + GlobalWriteLimit *int `json:"globalWriteLimit"` + GlobalWriteWindowSeconds *int `json:"globalWriteWindowSeconds"` + EndpointReadLimit *int `json:"endpointReadLimit"` + EndpointReadWindowSeconds *int `json:"endpointReadWindowSeconds"` + EndpointWriteLimit *int `json:"endpointWriteLimit"` + EndpointWriteWindowSeconds *int `json:"endpointWriteWindowSeconds"` +} + +// RateLimitField is one writable rate-limit field: its JSON name and, for the +// integer fields, whether it is a window (seconds, at least 1) rather than a +// limit (at least 0, 0 for no limit). +type RateLimitField struct { + Name string + Window bool +} + +// RateLimitIntFields lists the eight integer fields in document order. +var RateLimitIntFields = []RateLimitField{ + {Name: "globalReadLimit"}, + {Name: "globalReadWindowSeconds", Window: true}, + {Name: "globalWriteLimit"}, + {Name: "globalWriteWindowSeconds", Window: true}, + {Name: "endpointReadLimit"}, + {Name: "endpointReadWindowSeconds", Window: true}, + {Name: "endpointWriteLimit"}, + {Name: "endpointWriteWindowSeconds", Window: true}, +} + +// Int returns a pointer to the integer field named name, or nil when name is +// not one of [RateLimitIntFields]. +func (r *UpdateRateLimitSettingsRequest) Int(name string) **int { + switch name { + case "globalReadLimit": + return &r.GlobalReadLimit + case "globalReadWindowSeconds": + return &r.GlobalReadWindowSeconds + case "globalWriteLimit": + return &r.GlobalWriteLimit + case "globalWriteWindowSeconds": + return &r.GlobalWriteWindowSeconds + case "endpointReadLimit": + return &r.EndpointReadLimit + case "endpointReadWindowSeconds": + return &r.EndpointReadWindowSeconds + case "endpointWriteLimit": + return &r.EndpointWriteLimit + case "endpointWriteWindowSeconds": + return &r.EndpointWriteWindowSeconds + } + return nil +} + +// Validate enforces the replacement rules before transport: all nine fields +// present, limits at least 0, windows at least 1 second, and at least one +// limit above 0 when rate limiting is enabled. +func (r UpdateRateLimitSettingsRequest) Validate() error { + if r.Enabled == nil { + return fmt.Errorf("enabled is required and must be true or false") + } + anyLimit := false + for _, field := range RateLimitIntFields { + value := *r.Int(field.Name) + switch { + case value == nil && field.Window: + return fmt.Errorf("%s is required: a window in seconds, at least 1", field.Name) + case value == nil: + return fmt.Errorf("%s is required: a request count, at least 0 (0 for no limit)", field.Name) + case field.Window && *value < 1: + return fmt.Errorf("%s must be at least 1 second, got %d", field.Name, *value) + case !field.Window && *value < 0: + return fmt.Errorf("%s must be at least 0 (0 for no limit), got %d", field.Name, *value) + case !field.Window && *value > 0: + anyLimit = true + } + } + if *r.Enabled && !anyLimit { + return fmt.Errorf("rate limiting is enabled but every limit is 0: set at least one of globalReadLimit, globalWriteLimit, endpointReadLimit, or endpointWriteLimit above 0, or set enabled to false") + } + return nil +} + +// GetRateLimitSettings returns the effective Public API rate-limit settings +// and the fields environment variables manage. +func (c *Client) GetRateLimitSettings(ctx context.Context) (*RateLimitSettings, error) { + var settings RateLimitSettings + if _, err := c.Do(ctx, Request{Path: RateLimitSettingsPath}, &settings); err != nil { + return nil, err + } + return &settings, nil +} + +// UpdateRateLimitSettings fully replaces the Public API rate-limit settings. +// The new limits apply to every API key, this one included. +func (c *Client) UpdateRateLimitSettings(ctx context.Context, request UpdateRateLimitSettingsRequest) (*RateLimitSettings, error) { + if err := request.Validate(); err != nil { + return nil, err + } + var settings RateLimitSettings + if _, err := c.Do(ctx, Request{ + Method: http.MethodPut, + Path: RateLimitSettingsPath, + Body: request, + }, &settings); err != nil { + return nil, err + } + return &settings, nil +} diff --git a/internal/n8n/rate_limit_test.go b/internal/n8n/rate_limit_test.go new file mode 100644 index 0000000..015e70f --- /dev/null +++ b/internal/n8n/rate_limit_test.go @@ -0,0 +1,140 @@ +package n8n + +import ( + "context" + "encoding/json" + "net/http" + "strings" + "testing" +) + +const rateLimitResponse = `{ + "enabled":true, + "globalReadLimit":600, + "globalReadWindowSeconds":60, + "globalWriteLimit":120, + "globalWriteWindowSeconds":60, + "endpointReadLimit":0, + "endpointReadWindowSeconds":60, + "endpointWriteLimit":30, + "endpointWriteWindowSeconds":10, + "envManagedFields":["globalReadLimit"] +}` + +func validRateLimitRequest() UpdateRateLimitSettingsRequest { + ints := []int{600, 60, 120, 60, 0, 60, 30, 10} + request := UpdateRateLimitSettingsRequest{Enabled: Bool(true)} + for i, field := range RateLimitIntFields { + value := ints[i] + *request.Int(field.Name) = &value + } + return request +} + +func TestGetRateLimitSettings(t *testing.T) { + server := newCommunityPackageServer(t, packageJSONHandler(http.StatusOK, rateLimitResponse)) + settings, err := server.client(t).GetRateLimitSettings(context.Background()) + if err != nil { + t.Fatalf("GetRateLimitSettings: %v", err) + } + req, body := server.last(t) + if req.Method != http.MethodGet || req.URL.EscapedPath() != BasePath+RateLimitSettingsPath || req.URL.RawQuery != "" || body != "" { + t.Errorf("request = %s %s?%s body %q", req.Method, req.URL.EscapedPath(), req.URL.RawQuery, body) + } + if got := req.Header.Get(HeaderAPIKey); got != "community-secret" { + t.Errorf("%s = %q, want API key", HeaderAPIKey, got) + } + if !settings.Enabled || settings.GlobalReadLimit != 600 || settings.GlobalWriteLimit != 120 || + settings.EndpointReadLimit != 0 || settings.EndpointWriteLimit != 30 || settings.EndpointWriteWindowSeconds != 10 || + len(settings.EnvManagedFields) != 1 || settings.EnvManagedFields[0] != "globalReadLimit" { + t.Errorf("settings = %+v", settings) + } +} + +func TestUpdateRateLimitSettingsSendsAllWritableFieldsOnly(t *testing.T) { + server := newCommunityPackageServer(t, packageJSONHandler(http.StatusOK, rateLimitResponse)) + settings, err := server.client(t).UpdateRateLimitSettings(context.Background(), validRateLimitRequest()) + if err != nil { + t.Fatalf("UpdateRateLimitSettings: %v", err) + } + req, body := server.last(t) + if req.Method != http.MethodPut || req.URL.EscapedPath() != BasePath+RateLimitSettingsPath { + t.Errorf("request = %s %s", req.Method, req.URL.EscapedPath()) + } + var sent map[string]any + if err := json.Unmarshal([]byte(body), &sent); err != nil { + t.Fatalf("body is not JSON: %v\n%s", err, body) + } + if len(sent) != 9 { + t.Errorf("sent %d fields, want the 9 writable ones: %s", len(sent), body) + } + if _, ok := sent["envManagedFields"]; ok { + t.Error("read-only envManagedFields was sent") + } + if sent["enabled"] != true || sent["endpointReadLimit"] != float64(0) || sent["endpointWriteWindowSeconds"] != float64(10) { + t.Errorf("body = %s", body) + } + if settings.GlobalReadWindowSeconds != 60 { + t.Errorf("settings = %+v", settings) + } +} + +func TestUpdateRateLimitSettingsValidationBeforeTransport(t *testing.T) { + tests := []struct { + name string + mutate func(*UpdateRateLimitSettingsRequest) + want string + }{ + {"missing enabled", func(r *UpdateRateLimitSettingsRequest) { r.Enabled = nil }, "enabled is required"}, + {"missing limit", func(r *UpdateRateLimitSettingsRequest) { r.GlobalWriteLimit = nil }, "globalWriteLimit is required"}, + {"missing window", func(r *UpdateRateLimitSettingsRequest) { r.EndpointReadWindowSeconds = nil }, "endpointReadWindowSeconds is required"}, + {"negative limit", func(r *UpdateRateLimitSettingsRequest) { v := -1; r.EndpointWriteLimit = &v }, "endpointWriteLimit must be at least 0"}, + {"zero window", func(r *UpdateRateLimitSettingsRequest) { v := 0; r.GlobalReadWindowSeconds = &v }, "globalReadWindowSeconds must be at least 1"}, + {"enabled without limits", func(r *UpdateRateLimitSettingsRequest) { + for _, field := range RateLimitIntFields { + if !field.Window { + zero := 0 + *r.Int(field.Name) = &zero + } + } + }, "every limit is 0"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + server := newCommunityPackageServer(t, packageJSONHandler(http.StatusOK, rateLimitResponse)) + request := validRateLimitRequest() + tt.mutate(&request) + _, err := server.client(t).UpdateRateLimitSettings(context.Background(), request) + if err == nil || !strings.Contains(err.Error(), tt.want) { + t.Fatalf("error = %v, want %q", err, tt.want) + } + if len(server.requests) != 0 { + t.Errorf("%d invalid requests reached instance", len(server.requests)) + } + }) + } +} + +func TestUpdateRateLimitSettingsDisabledAllowsZeroLimits(t *testing.T) { + request := validRateLimitRequest() + request.Enabled = Bool(false) + for _, field := range RateLimitIntFields { + if !field.Window { + zero := 0 + *request.Int(field.Name) = &zero + } + } + if err := request.Validate(); err != nil { + t.Errorf("Validate: %v", err) + } +} + +func TestRateLimitSettingsErrorsPreserveAPIError(t *testing.T) { + for _, status := range []int{http.StatusForbidden, http.StatusConflict, http.StatusTooManyRequests} { + server := newCommunityPackageServer(t, packageJSONHandler(status, `{"message":"limits denied"}`)) + _, err := server.client(t).UpdateRateLimitSettings(context.Background(), validRateLimitRequest()) + if err == nil || StatusCodeOf(err) != status || !strings.Contains(err.Error(), "limits denied") { + t.Errorf("status %d: error = %v", status, err) + } + } +} diff --git a/test/integration/n8n_package_test.go b/test/integration/n8n_package_test.go index 35c3d1c..05d66e7 100644 --- a/test/integration/n8n_package_test.go +++ b/test/integration/n8n_package_test.go @@ -109,8 +109,8 @@ func TestN8nPackageImportValidation(t *testing.T) { client := instance.Client(t) _, err := client.ImportPackage(context.Background(), n8n.ImportPackageRequest{ - WorkflowConflictPolicy: n8n.ImportWorkflowConflictSkip, - WorkflowIDPolicy: n8n.ImportWorkflowIDSource, + ConflictPolicy: n8n.ImportConflictSkip, + IDPolicy: n8n.ImportIDSource, }, strings.NewReader("not-a-gzip-package"), "invalid.n8np") if n8n.IsForbidden(err) || n8n.IsNotFound(err) { t.Skip("integration instance has no licensed Packages feature") @@ -131,9 +131,9 @@ func TestN8nPackageImportSelectionValidation(t *testing.T) { client := instance.Client(t) _, err := client.ImportPackageSelection(context.Background(), n8n.ImportPackageSelectionRequest{ - ProjectID: integration.ResourcePrefix + "missing-project", - WorkflowIDs: []string{integration.ResourcePrefix + "missing-workflow"}, - WorkflowIDPolicy: n8n.ImportWorkflowIDSource, + ProjectID: integration.ResourcePrefix + "missing-project", + WorkflowIDs: []string{integration.ResourcePrefix + "missing-workflow"}, + IDPolicy: n8n.ImportIDSource, }, strings.NewReader("not-a-gzip-package"), "invalid.n8np") if n8n.IsForbidden(err) || n8n.IsNotFound(err) || n8n.IsStatus(err, http.StatusServiceUnavailable) { t.Skip("integration instance does not serve package import-selection") @@ -218,8 +218,8 @@ func TestN8nPackageImportSelectionRoundTrip(t *testing.T) { ProjectID: projectID, WorkflowIDs: []string{kept}, DeletedWorkflowIDs: []string{removed}, - WorkflowConflictPolicy: n8n.ImportWorkflowConflictNewVersion, - WorkflowIDPolicy: n8n.ImportWorkflowIDSource, + ConflictPolicy: n8n.ImportConflictNewVersion, + IDPolicy: n8n.ImportIDSource, OverwriteDeletionPolicy: n8n.ImportDeletionArchive, }, bytes.NewReader(archive.Bytes()), "project.n8np") if n8n.IsForbidden(err) || n8n.IsNotFound(err) || n8n.IsStatus(err, http.StatusServiceUnavailable) { @@ -243,7 +243,7 @@ func TestN8nPackageImportSelectionRoundTrip(t *testing.T) { interactive := false var stdout, stderr strings.Builder code := cli.Run(ctx, []string{"package", "import-selection", "--file", path, "--project-id", projectID, - "--workflow-id", kept, "--workflow-conflict-policy", "skip", "--yes", "--output", "json"}, cli.Options{ + "--workflow-id", kept, "--conflict-policy", "skip", "--yes", "--output", "json"}, cli.Options{ Streams: cli.Streams{In: strings.NewReader(""), Out: &stdout, Err: &stderr}, Version: version.Get(), ConfigDir: t.TempDir(), diff --git a/test/integration/promotion_test.go b/test/integration/promotion_test.go index 68c946b..680d3bd 100644 --- a/test/integration/promotion_test.go +++ b/test/integration/promotion_test.go @@ -15,15 +15,17 @@ import ( ) // skipUnlessPromotions skips when the instance does not serve this group. The -// target instance serves GitConnections instead; both share the -// gitConnection:* scope namespace, so the served paths decide, not the scopes. +// target instance serves GitConnections instead; instances before n8n 2.47 +// share the gitConnection:* scope namespace with it (2.47 renamed the +// Promotions scopes to promotions:*), so the served paths decide, not the +// scopes. func skipUnlessPromotions(t *testing.T, err error) { t.Helper() switch { case n8n.IsNotFound(err), n8n.IsStatus(err, http.StatusServiceUnavailable): t.Skip("instance does not serve promotions: a GitConnections-generation instance answers here instead") case n8n.IsForbidden(err): - t.Skip("integration credential lacks gitConnection:list") + t.Skip("integration credential lacks promotions:list (gitConnection:list before n8n 2.47)") } }