release(v1.4.2): fix backup browsing HTTP 500 & add storage location transparency - #87

• Prevent backup file browsing HTTP 500s by auto-detecting gzip vs raw tar archives.
• Add backup storage-location endpoint and UI banner with copy-to-clipboard path.
• Gzip container/image exports when destination filename ends with .gz; bump version to 1.4.2.

graph TD
  UI["Browse Backup modal"] --> API["Extension API client"] --> BE["Backend /api"] --> PRS["PartialRestoreService"] --> PM["PolicyManager + storage config"]
  BE --> LOC["/backups/:id/location"] --> PRS
  PRS --> TAR["tar CLI (list/extract)"]
  PRS --> ST[("Backup storage")]
  DOCKER["DockerService"] --> OUT[("Export archive file")]
  PRS -->|"magic bytes detect"| TAR
  DOCKER -->|"gzip if .gz"| OUT

Loading

The following are alternative approaches to this PR:

1. Use a Node tar library with auto-detect (no tar CLI spawn)

• ➕ Avoids shelling out to tar (portability, less brittle stderr parsing).
• ➕ Can stream and detect gzip via wrapper streams without filename heuristics.
• ➕ Easier to unit test without process spawning.
• ➖ Larger refactor and potential behavior drift vs system tar.
• ➖ May be slower or have edge-case differences with large archives.
• ➖ Requires careful path-safety hardening equivalent to current CLI approach.

2. Persist compression metadata in backup manifest

• ➕ Removes runtime guessing; deterministic flags for list/extract.
• ➕ Improves UX for mixed historical backups and future formats.
• ➖ Requires schema/versioning work and migration for existing backups.
• ➖ Still needs fallback for legacy backups without metadata.

Recommendation: Keep this PR’s approach: magic-byte gzip detection + tar-flag fallback is the smallest safe change to unblock users and maintain compatibility with legacy raw-tar backups mislabeled as .tar.gz. Consider a future refactor toward a Node tar implementation or adding explicit compression metadata if tar browsing becomes a larger surface area.

Enhancement (4) +54 / -5

index.tsExpose /api/backups/:id/location endpoint +5/-0

Expose /api/backups/:id/location endpoint

• Adds a new backend route that returns resolved storage location info from PartialRestoreService for a given backup id.

packages/backend/src/index.ts

DockerService.tsOptionally gzip container/image exports based on destination name +10/-2

Optionally gzip container/image exports based on destination name

• Pipes Docker export streams through zlib gzip when the destination path ends with .gz and wires error handling for the transformed stream.

packages/backend/src/services/DockerService.ts

api.tsAdd getBackupLocation API wrapper +4/-0

Add getBackupLocation API wrapper

• Introduces a typed client call for the new backend /backups/:id/location endpoint.

packages/extension/src/api.ts

PartialRestoreBrowser.tsxShow storage location banner + enable image targets in archive list +35/-3

Show storage location banner + enable image targets in archive list

• Fetches and renders backup storage location with a copy-to-clipboard button in the Browse Backup modal. Expands archive inference to include image targets and adds supporting UI icons/state.

packages/extension/src/components/PartialRestoreBrowser.tsx

Bug fix (1) +66 / -9

PartialRestoreService.tsFix tar browsing/extraction by detecting gzip vs raw tar +66/-9

Fix tar browsing/extraction by detecting gzip vs raw tar

• Adds magic-byte gzip detection and selects the correct tar flags for listing/extraction; includes a fallback list retry to avoid HTTP 500s when archives are uncompressed despite .tar.gz naming. Adds a new getStorageLocation helper returning resolved local/remote location strings.

packages/backend/src/services/PartialRestoreService.ts

Tests (1) +8 / -1

partialRestore.test.tsExtend PartialRestoreService tests for storage location info +8/-1

Extend PartialRestoreService tests for storage location info

• Adds a PolicyManager mock for resolveStorageConfig and a new test asserting formatted storage location output for local backups.

packages/backend/src/tests/partialRestore.test.ts

Documentation (1) +14 / -0

CHANGELOG.mdAdd 1.4.2 release notes for browsing fix and storage transparency +14/-0

Add 1.4.2 release notes for browsing fix and storage transparency

• Documents the 1.4.2 release, including the tar browsing 500 fix, gzip export behavior, and the new storage-location UI/endpoint.

CHANGELOG.md

Other (7) +8 / -8

DockerfileBump DRK_VERSION build arg to 1.4.2 +2/-2

Bump DRK_VERSION build arg to 1.4.2

• Updates the Docker build argument and inline example so the published extension version reflects 1.4.2.

Dockerfile

package.jsonBump workspace version to 1.4.2 +1/-1

Bump workspace version to 1.4.2

• Updates the root package version to 1.4.2 for the release cut.

package.json

package.jsonBump backend package version to 1.4.2 +1/-1

Bump backend package version to 1.4.2

• Aligns backend package version with the 1.4.2 release.

packages/backend/package.json

package.jsonBump CLI package version to 1.4.2 +1/-1

Bump CLI package version to 1.4.2

• Aligns CLI package version with the 1.4.2 release.

packages/cli/package.json

package.jsonBump extension package version to 1.4.2 +1/-1

Bump extension package version to 1.4.2

• Aligns extension package version with the 1.4.2 release.

packages/extension/package.json

package.jsonBump MCP package version to 1.4.2 +1/-1

Bump MCP package version to 1.4.2

• Aligns MCP package version with the 1.4.2 release.

packages/mcp/package.json

package.jsonBump shared package version to 1.4.2 +1/-1

Bump shared package version to 1.4.2

• Aligns shared package version with the 1.4.2 release.

packages/shared/package.json

Description

PartialRestoreBrowser derives archive filenames from target selectors without applying the backend’s
128-character truncation, so sufficiently long selectors will produce dropdown filenames that don’t
exist in storage and make browse/extract fail for those targets.

Code

packages/extension/src/components/PartialRestoreBrowser.tsx[R60-65]

  // Infer candidate archive names from target list. The PolicyManager names
  // backup files as `{type}_{selector}.tar.gz`, so derive from targets.
  const archives = backup.targets
-    .filter(t => t.type === 'volume' || t.type === 'container')
+    .filter(t => t.type === 'volume' || t.type === 'container' || t.type === 'image')
    .map(t => `${t.type}_${t.selector.replace(/[^a-zA-Z0-9._-]/g, '_')}.tar.gz`)

Evidence

The backend truncates the sanitized selector to 128 chars when naming {type}_{selector}.tar.gz,
but the UI does not truncate; therefore, long selectors can create UI archive names that will never
match the backend-generated archive filenames.

packages/extension/src/components/PartialRestoreBrowser.tsx[60-65]
packages/backend/src/services/PolicyManager.ts[199-205]
packages/backend/src/utils/PathSafety.ts[18-23]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The frontend derives archive filenames using only a regex replacement, but the backend uses `safeFilenameFragment()` which also truncates to 128 chars. For long selectors, the UI will request a different filename than the backend created.

### Issue Context
Backend naming (authoritative): `safeFilenameFragment(selector)` does `replace(...).slice(0, 128)`.

### Fix Focus Areas
- Preferably centralize the filename derivation in shared code and reuse it in both backend and extension.
- As a minimal fix, apply the same `.slice(0, 128)` truncation in `PartialRestoreBrowser.tsx` when building `archives`.

### Fix Focus Areas (code pointers)
- packages/extension/src/components/PartialRestoreBrowser.tsx[60-65]
- packages/backend/src/utils/PathSafety.ts[18-23]
- packages/backend/src/services/PolicyManager.ts[199-205]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

getStorageLocation fabricates adapter URLs (s3://…, sftp://…, pbs://…) that don’t correspond to how
several adapters actually store backups (restic repo + tags, PBS repo string), making the new
/api/backups/:id/location response misleading and sometimes syntactically invalid.

Code

packages/backend/src/services/PartialRestoreService.ts[R44-74]

+  public async getStorageLocation(backupId: string): Promise<{ type: string; location: string; path?: string }> {
+    const backup = await this.policyManager.getBackup(backupId)
+    if (!backup) throw new NotFoundError('Backup', backupId)
+    const policy = await this.policyManager.getPolicy(backup.policyId)
+    if (!policy) throw new NotFoundError('Policy (parent)', backup.policyId)
+
+    const resolved = await this.policyManager.resolveStorageConfig(policy.storage)
+    const type = String(policy.storage?.type || 'local')
+
+    if (type === 'local') {
+      const basePath = path.resolve(resolved.path || resolved.basePath || 'data/backups')
+      const fullPath = path.join(basePath, backupId)
+      return { type: 'local', location: fullPath, path: fullPath }
+    } else if (type === 's3') {
+      const loc = `s3://${resolved.bucket || 'default'}/${resolved.prefix || ''}${backupId}`
+      return { type: 's3', location: loc }
+    } else if (type === 'smb') {
+      const loc = `\\\\${resolved.host || 'server'}\\${resolved.share || 'backups'}\\${backupId}`
+      return { type: 'smb', location: loc }
+    } else if (type === 'sftp') {
+      const loc = `sftp://${resolved.host || 'server'}:${resolved.port || 22}${resolved.path || '/backups'}/${backupId}`
+      return { type: 'sftp', location: loc }
+    } else if (type === 'pbs') {
+      const loc = `pbs://${resolved.server || 'server'}/${resolved.datastore || 'backup'}/${backupId}`
+      return { type: 'pbs', location: loc }
+    } else if (type === 'rclone') {
+      const loc = `rclone://${resolved.remote || 'remote'}:${resolved.path || ''}/${backupId}`
+      return { type: 'rclone', location: loc }
+    }
+    return { type, location: `${type}://${backupId}` }
+  }

Evidence

Restic-backed adapters store data in a repository URL and identify items via tags
(drk:<remotePath>), not by placing a backupId directory under s3://... or sftp://.... PBS
configuration is driven by a single repo string, so pbs://server/datastore/... is not derived
from real config fields.

packages/backend/src/services/PartialRestoreService.ts[44-74]
packages/backend/src/storage/adapters/ResticStorageAdapter.ts[7-16]
packages/backend/src/storage/adapters/ResticStorageAdapter.ts[43-47]
packages/backend/src/storage/adapters/S3StorageAdapter.ts[19-23]
packages/backend/src/storage/adapters/SFTPStorageAdapter.ts[22-35]
packages/backend/src/connectors/PBSConnector.ts[11-20]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`PartialRestoreService.getStorageLocation()` currently constructs ad-hoc URIs (e.g., `s3://bucket/prefix<backupId>`, `sftp://host:portpath/...`, `pbs://server/datastore/...`) that do not match the real storage model for:
- Restic-backed adapters (s3/sftp/rclone/etc.): backups are snapshots inside a repo, tagged with `drk:<remotePath>`.
- PBS adapter: config is `repo` string (user@realm@host:port:datastore), not separate `server/datastore` fields.

### Issue Context
This endpoint is user-facing (banner + copy path). Incorrect values undermine the feature and can misdirect operators during recovery.

### Fix Focus Areas
- For local: keep returning absolute local path.
- For restic-backed storage: return the resolved restic repo location (as the adapter would compute it) and optionally include the logical tag/prefix (e.g., `drk:${backupId}/`).
- For PBS: return/echo the resolved `repo` (and maybe namespace/prefix semantics) rather than a fabricated `pbs://...` URL.
- Normalize joins (`prefix` separators, leading slashes) instead of string concatenation.

### Fix Focus Areas (code pointers)
- packages/backend/src/services/PartialRestoreService.ts[44-74]
- packages/backend/src/storage/adapters/ResticStorageAdapter.ts[7-16]
- packages/backend/src/storage/adapters/S3StorageAdapter.ts[19-23]
- packages/backend/src/storage/adapters/SFTPStorageAdapter.ts[22-35]
- packages/backend/src/connectors/PBSConnector.ts[11-20]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

isGzipped() swallows all open/read errors by returning true and does not guarantee fd cleanup if
read fails after open, which can both misclassify archives and leak file descriptors under repeated
failures.

Code

packages/backend/src/services/PartialRestoreService.ts[R98-107]

+  private async isGzipped(filePath: string): Promise<boolean> {
+    try {
+      const fd = await fs.open(filePath, 'r')
+      const buf = Buffer.alloc(2)
+      await fs.read(fd, buf, 0, 2, 0)
+      await fs.close(fd)
+      return buf[0] === 0x1f && buf[1] === 0x8b
+    } catch {
+      return true
+    }

Evidence

The current implementation closes the fd only on the happy path and returns true for any
exception, conflating I/O failures with gzip detection and risking fd leakage when an exception
occurs mid-probe.

packages/backend/src/services/PartialRestoreService.ts[98-107]
packages/backend/src/services/PartialRestoreService.ts[76-94]
packages/backend/src/services/PartialRestoreService.ts[137-149]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`isGzipped()` catches all errors and returns `true`, which can hide real filesystem issues and lead to confusing downstream tar failures. Additionally, if `fs.read` throws after `fs.open` succeeds, the fd won’t be closed.

### Issue Context
This runs on browse/extract paths and should be safe under partial I/O failures.

### Fix Focus Areas
- Ensure fd is closed via `finally` (or use `fs.promises.open()` FileHandle and `handle.close()` in finally).
- Do not treat generic I/O errors as “gzipped”; either rethrow (preferred) or return an explicit “unknown” and let callers try both tar modes.
- Optionally mirror `tarList()` fallback behavior in `extractFile()` when format detection is uncertain.

### Fix Focus Areas (code pointers)
- packages/backend/src/services/PartialRestoreService.ts[98-107]
- packages/backend/src/services/PartialRestoreService.ts[76-94]
- packages/backend/src/services/PartialRestoreService.ts[137-149]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

copyPath() triggers clipboard writes without awaiting/catching and sets “Copied” before the write
succeeds; it also starts a timeout without cleanup, potentially leaving a pending timer after the
modal closes.

Code

packages/extension/src/components/PartialRestoreBrowser.tsx[R85-90]

+  const copyPath = () => {
+    if (!locationInfo?.location) return
+    navigator.clipboard.writeText(locationInfo.location)
+    setCopied(true)
+    setTimeout(() => setCopied(false), 2000)
+  }

Evidence

navigator.clipboard.writeText is a Promise-returning API that can fail; the current implementation
neither awaits nor handles rejection and sets copied state unconditionally, then schedules a delayed
state update with no cleanup.

packages/extension/src/components/PartialRestoreBrowser.tsx[85-90]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The UI marks the path as copied immediately and does not handle clipboard failures (permission / insecure context / API missing). It also creates a timeout that isn’t cleared if the component unmounts quickly.

### Issue Context
This is a UX/reliability issue: users can see “Copied” when the copy actually failed.

### Fix Focus Areas
- Make `copyPath` async and `await navigator.clipboard.writeText(...)`.
- Only set `copied=true` after success; on failure, show an error or keep `copied=false`.
- Store timeout id in a ref and clear it on unmount (cleanup effect).

### Fix Focus Areas (code pointers)
- packages/extension/src/components/PartialRestoreBrowser.tsx[85-90]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools