InfiniDysk namespace migration API¶
Endpoint paths below are backend-native. Add /api when using the dashboard gateway, for example http://localhost:3005/api/process/capabilities.
Namespace migration request order
Review preflight findings before applying a namespace change. Cleanup is a later, separately reviewed operation after the migrated installation has been validated.
flowchart TD
Status["Read migration status"] --> Preflight["Request full-namespace preflight"]
Preflight --> Review["Review blockers, affected paths and recovery data"]
Review --> Apply["Apply the reviewed migration"]
Apply --> Poll["Poll the retained job status"]
Poll --> Validate["Validate services, paths and playback"]
Validate --> Cleanup["Separately preview and approve recovery-data cleanup"]
InfiniDysk migration¶
GET /process/infinidysk-migration/status¶
Returns whether a legacy NzbDAV deployment needs review, whether the notice is due or snoozed, the legacy paths and DUMB-generated attached-service names that were found, and the modes supported by this backend.
The response also exposes cleanup_available, cleanup_finalized,
cleanup_finalized_at, and rollback_artifacts_available. Clients must hide
both the notice and manual migration entry once cleanup_finalized is true.
POST /process/infinidysk-migration/remind-later¶
Persists the reminder on the DUMB instance. days must be between 1 and 90.
POST /process/infinidysk-migration/preflight¶
Runs the non-mutating full-namespace preflight and returns a short-lived token,
expiry, blockers/warnings, pending_conditions, filesystem moves, active-read count, and counts of
planned Arr (including tag-label), Prowlarr application/tag, and media-library
updates. The response never includes application API keys or download-client
secrets. The full private inventory is stored separately from the small public
job record with mode 0600, preventing job polling/progress writes from parsing
or rewriting the complete catalog.
arr_discovery lists every enabled Arr instance with included and human-readable
reasons. Inclusion uses either configured InfiniDysk core_service metadata or
live legacy root/item/import-list/collection/download-client/category/tag
references, so a Prowlarr-managed Arr is not omitted merely because its DUMB
linkage metadata is blank. Per-Arr public counts include root_changes,
item_changes, client_changes, import_list_changes, collection_changes,
and tag_changes.
media_servers marks external_api_only=true when no DUMB media server is enabled
and DUMB successfully infers Plex from dumb.plex_address plus dumb.plex_token.
The public entry includes the Plex display name/version and affected-library count,
but not the token or machine identifier.
ready remains false when activity cannot be inspected, an application API is
unreachable, a destination conflicts, a move crosses filesystems, or a legacy
path lies outside DUMB-managed roots. Current Arr queues, verified media
activity, and InfiniDysk reads are returned in pending_conditions; they are
handled by the apply job's automatic quiescence stage. Preflight also reads
InfiniDysk's effective repair.enable value. An enabled setting managed by an
environment variable is a blocker because DUMB cannot temporarily override it
through InfiniDysk's authenticated configuration API. Migration Arr requests
use a 120-second timeout for large catalogs. Generated attached-service paths such as
/radarr/nzbdav and /log/rclone_w_nzbdav.log are discovered and planned
automatically. Prowlarr legacy/canonical tag-label or application-name
collisions are structural blockers; the response identifies them so an
operator can reconcile the duplicate and rerun preflight before any path moves.
GET /process/infinidysk-migration/job-status¶
Returns the latest persisted complete-namespace job, or a specific job when a
32-character hexadecimal job_id query parameter is supplied. The public job
record includes status, stage, message, progress, up to 100 recent
stage events, and the terminal result or safe error text. Arr stages also expose
a detail object with the current process, phase, completed/total reference
counts, and all-Arr completed/total counts. Active statuses are
queued, running, and rolling_back.
When no migration job exists, the response is {"job": null}. An empty object
is not a job and must not be used to infer that migration controls are needed.
A rolled-back terminal result includes a sanitized result.recovery object with
the cutover cause, component-scoped rollback_errors, retained backup/config
paths, and manual_restore_required. This is recovery guidance, not an instruction
to restore the entire bundle blindly; verify the legacy paths and application
state and repair only the failed rollback surface. Current rollback manifests
also restore captured file ownership and permissions; this includes SQLite WAL
and shared-memory sidecars that must remain writable by the managed service UID.
Rollback also reapplies and verifies every captured symlink target after the
legacy roots return, removes Arr root paths that exist only in the failed
migration direction, and treats any remaining stale root as a rollback error.
failed_rolled_back means the automatic namespace rollback completed and the
legacy topology should be verified before a new preflight. A
rollback_attention_required result freezes ordinary config/service lifecycle
changes and requires review of the named failed rollback surfaces; do not force
a provider/path toggle or restore the complete bundle. An interrupted job
known to have stopped before filesystem mutation may cold-start the legacy
topology for a fresh preflight. Unknown or post-mutation interruptions remain
frozen for recovery review.
While a current quiescing job is waiting on verified media activity and the
backend advertises capability infinidysk_migration_playback_override, the
record also exposes playback_override_available, playback_stop_requested,
and the process-name-only active_media_servers list. These transient fields
belong to the active backend worker; a backend restart interrupts the entire
migration rather than resuming the override.
The dashboard polls this route after the migration dialog is closed or the
page is reloaded. Another authenticated browser or device retrieves the same
backend-owned job without browser-local handoff state. A DUMB backend restart marks an active retained job
interrupted; it is not resumed automatically because the operator must first
inspect the backup bundle and current namespace paths.
GET /process/infinidysk-migration/cleanup-preview¶
Returns a short-lived, state-bound preview for permanently purging recovery material after a successful migration:
{
"available": true,
"preview_token": "<short-lived token>",
"expires_at": 1787270400,
"selected_mode": "full_namespace",
"migration_status": "completed",
"cleanup_finalized": false,
"cleanup_finalized_at": null,
"rollback_artifacts_available": true,
"deletion": {
"files": 14,
"directories": 3,
"bytes": 1048576,
"categories": [
"Migration state details",
"Preflight inventory",
"Job history",
"DUMB configuration backups and rollback bundles"
]
},
"retained": [
"Current DUMB and InfiniDysk configuration",
"InfiniDysk runtime, application data, and databases",
"Mounts, symlink libraries, and normal symlink snapshots",
"PostgreSQL cutover authorization and database-migration job records",
"Operator-managed backups outside the namespace rollback root"
]
}
expires_at is Unix time in seconds. Counts and categories are returned without
raw filesystem paths. available is false and the token is null unless the
latest migration state is safely terminal and successful, no active/unsafe
latest job exists, cleanup has not been finalized, and the calculated deletion
plan is safe. rollback_artifacts_available separately reports whether the
DUMB rollback bundle is still present. The token fingerprints the current
migration state and deletion inventory; request a new preview after expiry or
any state change.
POST /process/infinidysk-migration/cleanup¶
{
"preview_token": "<short-lived token>",
"confirmation": "REMOVE INFINIDYSK MIGRATION DATA",
"acknowledge_validation": true,
"acknowledge_rollback_loss": true
}
confirmation must match exactly; surrounding whitespace is rejected. Both
acknowledgements must be literal true. Cleanup deletes the detailed namespace
migration state, private preflight inventory, namespace job history, and
DUMB-owned migration backup/rollback bundle. It does not delete the current
DUMB/InfiniDysk
configuration, runtime, application data, databases, mounts, symlink libraries,
normal symlink snapshots, the minimal controller-owned PostgreSQL cutover
authorization and database-migration job evidence under
/config/arr-postgres-migration, or operator-managed backups outside the
namespace rollback root. The retained authorization/evidence is required so a
PostgreSQL-backed InfiniDysk remains restartable and its guarded database
rollback contract remains verifiable after namespace cleanup.
The backend replaces the detailed state with a private mode-0600 tombstone
containing only the selected mode, terminal status, and finalization metadata.
The response reports status as completed or idempotent
already_completed, sets cleanup_finalized: true,
rollback_artifacts_available: false, and notice_due: false, and returns the
actual deleted counts/categories plus the retained list. This action is
irreversible; a finalized compatibility-only migration also accepts the
retained legacy namespace as final.
POST /process/infinidysk-migration/stop-playback¶
Requests the narrowly scoped playback override for the active quiescing job. It is accepted only while verified active media playback is delaying the cutover. The worker applies its media-server scan guard, stops the listed media server through the normal DUMB process manager, and waits for InfiniDysk active reads to reach zero. Stopping the server terminates its active streams.
Inferred external Plex is deliberately excluded from this override because DUMB does not own its process. The operator must stop external playback and pause Autoscan or other scan/request producers outside DUMB; the job continues polling Plex activity and InfiniDysk reads.
This endpoint cannot override Arr queues, unavailable or unknown APIs/activity,
active InfiniDysk reads, filesystem conflicts, or other blockers. It returns
the updated job record. A stale job, a non-quiescing stage, no currently active
playback, or incorrect confirmation returns 400/409 without weakening the
migration checks.
POST /process/infinidysk-migration/apply¶
{
"mode": "retain_legacy_namespace",
"rename_attached_services": true,
"confirmation": "MIGRATE TO INFINIDYSK",
"acknowledge_external_backup": true
}
The available compatibility cutover adopts the canonical service/process
identity and can rename DUMB-generated attached instance/process labels. It
first saves a private complete-config backup under
/config/migrations/infinidysk-backups, and retains runtime, mount, symlink,
Arr category/root/tag, and media-server library paths. Both migration modes
require the external-backup acknowledgement.
The complete namespace request uses the token from the latest passing preflight and requires all four acknowledgements. The external-backup acknowledgement confirms that the operator has a current, verified backup outside the paths DUMB will migrate; DUMB's private rollback bundle is not a substitute for that backup.
{
"mode": "full_namespace",
"rename_attached_services": true,
"confirmation": "MIGRATE TO INFINIDYSK",
"preflight_token": "<short-lived preflight token>",
"acknowledge_downtime": true,
"acknowledge_library_scan": true,
"acknowledge_rollback_limits": true,
"acknowledge_external_backup": true
}
The full-namespace request returns immediately with the persisted background job:
{
"job": {
"job_id": "0123456789abcdef0123456789abcdef",
"status": "queued",
"stage": "queued",
"progress": 0
}
}
The job stops linked NeutArr, Seerr, Profilarr, and Prowlarr producers first,
temporarily sets InfiniDysk repair.enable=false through its authenticated API,
verifies the change, then polls Arr queue counts and media activity. It latches each managed Arr/media
server stopped as soon as it is safe and holds those processes through the
cutover. Inferred external Plex remains running under an API scan guard and must
remain idle; DUMB cannot stop it or pause Autoscan.
Failed or held queue entries are never deleted automatically; operators can
resolve them through the still-running Arr UI. Transient Arr queue or inventory
API failures remain pending and are retried during quiescence. Quiescence times
out after one hour and aborts before path mutation if activity or an Arr API
remains unavailable, restoring scan guards and restarting processes DUMB
stopped. The optional confirmed playback-stop request may
interrupt active streams, but the worker still verifies that provider reads
have drained before path mutation.
The original effective repair.enable value and its management source are
saved in the private rollback bundle before the pause. Existing health probes
are allowed to drain, but no new scheduled probes are started. DUMB restores
and reads back the exact prior value before reporting success. Failure handling
restores it through the running API when possible and verifies the restored
database during rollback before the job becomes terminal.
The worker repeats live safety checks immediately before applying. It then
backs up configuration and application snapshots, stops the dependency chain,
atomically moves managed runtime/mount/symlink/log and discovered attached
service paths. Nested generated paths remain explicit ordered actions after a
parent move, so child names such as radarr-nzbdav cannot be silently retained
inside a canonical parent. The provider's /content and completed-symlinks
category directories are SQLite-backed virtual paths rather than ordinary
directories to rename through FUSE. While InfiniDysk is stopped, DUMB rewrites
the fixed history, queue, and DAV category/path records that materialize those
views; the captured database is restored if rollback is required. The worker
rewrites symlink targets and saved InfiniDysk configuration,
restarts the chain, updates Arr
root/item/import-list/Radarr-collection/download-client references and tag
labels while preserving tag IDs,
updates media-server library paths, and
verifies the persisted API values. Before scan guards are restored it also
requires every planned canonical path, rejects every planned legacy source and
legacy raw symlink target, and checks canonical filesystem availability for
file-bearing Arr items and changed media-library paths. Failures trigger automatic path,
configuration, application-reference, process-name, and scan-guard rollback.
The terminal job result identifies the private backup bundle and reports
changed symlinks, InfiniDysk database records, Arr references, and media
libraries.
Historical symlink snapshots are retained under their original names. Future scheduled snapshots use the canonical name. A successful response instructs the operator to run normal Arr and media-server library scans; the migration does not initiate scans automatically.
Saved dashboard ordering, keyboard shortcuts, and notification service filters are updated when their exact process names are renamed.