feat(registry/coder/modules): add archive

Author: mafredri

registry/coder/modules/archive/README.md

@@ -0,0 +1,147 @@
+---
+display_name: Archive
+description: Create a user-invokable script that archives selected files/folders with gzip, zstd, or none.
+icon: ../../../../.icons/tool.svg
+verified: false
+tags: [backup, archive, tar, helper]
+---
+
+# Archive
+
+This module installs a small, robust script in your workspace that you can run to create a tar archive from a list of files and directories. It supports gzip, zstd, or no compression, prints only the resulting archive path to stdout, and writes all status/log output to stderr.
+
+The module can also optionally run on workspace stop to automatically create an archive.
+
+- Depends on: `tar` (and `gzip` or `zstd` if you select those compression modes)
+- Script install location: `$CODER_SCRIPT_BIN_DIR/coder-archive-create` and `$CODER_SCRIPT_BIN_DIR/coder-archive-extract`
+- Default wrapper names: `coder-archive-create` and `coder-archive-extract` (customize via `create_script_name` and `extract_script_name`)
+- The installer script (run_on_start) decodes and writes a library (`archive-lib.sh`) to `$CODER_SCRIPT_DATA_DIR`, and generates wrappers in `$CODER_SCRIPT_BIN_DIR` (default names `coder-archive-create` and `coder-archive-extract`) that:
+  - injects DEFAULT*\* values from Terraform (via TF*\* variables) into the wrapper
+  - sources `$CODER_SCRIPT_DATA_DIR/archive-lib.sh`
+  - executes `create_archive "$@"` (and for extraction, `extract_archive "$@"`)
+- The stop script (when `create_archive_on_stop = true`) runs the create wrapper.
+
+## Features
+
+- Archive selected paths into a single `.tar`, `.tar.gz`, or `.tar.zst`.
+- Compression algorithms: `gzip`, `zstd`, `none`.
+- Optional custom output directory and archive base name.
+- Newline-delimited include list, plus extra paths provided at runtime.
+- Industry-standard Bash best practices (strict mode, safe path handling, non-clobbering outputs).
+- Prints only the final archive path to stdout; all other messages go to stderr.
+- Optional `run_on_stop` script to create an archive automatically when the workspace stops.
+
+## Usage
+
+Basic example:
+
+    module "archive" {
+      count    = data.coder_workspace.me.start_count
+      source   = "registry.coder.com/coder/archive/coder"
+      version  = "0.0.1"
+      agent_id = coder_agent.example.id
+
+      # Paths to include in the archive (files or directories)
+      paths = [
+        "~/project",
+        "~/notes.txt",
+        "/var/log/some-app",
+      ]
+    }
+
+Customize compression and output:
+
+    module "archive" {
+      count    = data.coder_workspace.me.start_count
+      source   = "registry.coder.com/coder/archive/coder"
+      version  = "0.0.1"
+      agent_id = coder_agent.example.id
+
+      paths        = ["~/project", "~/notes.txt"]
+      compression  = "zstd"          # "gzip" | "zstd" | "none"
+      output_dir   = "~/backups"     # defaults to /tmp
+      archive_name = "my-backup"     # base name without extension
+      # script_name  = "my-archiver" # optional alternative script filename
+    }
+
+Enable auto-archive on stop:
+
+    module "archive" {
+      count    = data.coder_workspace.me.start_count
+      source   = "registry.coder.com/coder/archive/coder"
+      version  = "0.0.1"
+      agent_id = coder_agent.example.id
+
+      paths        = ["~/project", "~/notes.txt"]
+      compression  = "gzip"
+      run_on_stop  = true
+    }
+
+## Running the script
+
+Once the workspace starts, the module installs a script:
+
+- Paths: `$CODER_SCRIPT_BIN_DIR/coder-archive-create` and `$CODER_SCRIPT_BIN_DIR/coder-archive-extract` (installed by a run_on_start installer)
+- Usage:
+
+      coder-archive-create [options] [extra_paths...]
+        -c, --compression <gzip|zstd|none>   Compression algorithm (default from module)
+        -o, --output-dir <dir>               Output directory (default: /tmp)
+        -n, --name <name>                    Archive base name without extension (default: workspace-backup-<timestamp>)
+        -h, --help                           Show help
+
+Examples:
+
+- Use module defaults:
+
+      coder-archive-create
+
+- Override compression and output directory at runtime:
+
+      coder-archive-create --compression zstd --output-dir ~/backups
+
+- Add extra paths on the fly:
+
+      coder-archive-create ~/extra-file.txt /tmp/scratch
+
+- Print archive path to a file (keeps logs out of the captured output):
+
+      coder-archive-create 1> ~/last-archive-path.txt
+
+Notes:
+
+- Only the final archive path is printed to stdout. All other output (progress, warnings, errors) goes to stderr.
+- The script ensures the output filename does not overwrite existing archives by appending a numeric suffix when necessary.
+
+## Inputs
+
+- `agent_id` (string, required): ID of the Coder agent.
+- `paths` (list(string), required): Files/directories to include in the archive.
+- `compression` (string, optional, default: `"gzip"`): One of `gzip`, `zstd`, or `none`.
+- `archive_name` (string, optional, default: `""`): Base name without extension. If empty, a name like `workspace-backup-<timestamp>` is generated.
+- `output_dir` (string, optional, default: `"/tmp"`): Where to write the archive.
+- `create_archive_on_stop` (bool, optional, default: `false`): If `true`, creates a `run_on_stop` script that runs the create wrapper on workspace stop.
+- `create_script_name` (string, optional, default: `"coder-archive-create"`): The create wrapper filename installed into `$CODER_SCRIPT_BIN_DIR`.<br>
+- `extract_script_name` (string, optional, default: `"coder-archive-extract"`): The extract wrapper filename installed into `$CODER_SCRIPT_BIN_DIR`.<br>
+- `extract_on_start` (bool, optional, default: `false`): If `true`, waits for a matching archive and extracts it on start.<br>
+- `extract_timeout_seconds` (number, optional, default: `60`): Max seconds to wait for an archive when `extract_on_start` is enabled.<br>
+- `extract_interval_seconds` (number, optional, default: `2`): Poll interval (seconds) when waiting for an archive on start.
+
+## Outputs
+
+- `archive_path` (string): Expected archive path if `archive_name` is set; empty if `archive_name` is not set.
+
+## Requirements
+
+- `tar` is required.
+- `gzip` is required if `compression = "gzip"`.
+- `zstd` is required if `compression = "zstd"`.
+
+## Behavior
+
+- Installs `$CODER_SCRIPT_DATA_DIR/archive-lib.sh` and two wrappers in `$CODER_SCRIPT_BIN_DIR`; wrappers set defaults, source the library, and run `create_archive`/`extract_archive`. If `extract_on_start` is true, the installer waits and extracts before finishing.
+- Paths with spaces are handled safely by passing them to `tar` as separate arguments (not via a files-from list).
+- `~` is expanded to `$HOME` for inputs and outputs.
+- Missing or invalid include paths are safely skipped with warnings.
+- The module will not overwrite existing archives; it appends a numeric suffix to the filename when necessary.
+- The script sets a restrictive umask (`077`) so archives are only readable by the user by default.

registry/coder/modules/archive/archive.tftest.hcl

@@ -0,0 +1,44 @@
+# Minimal terraform tests for the archive module
+
+mock_provider "coder" {}
+
+run "apply_defaults" {
+  command = apply
+
+  variables {
+    agent_id = "agent-123"
+    paths    = ["~/project", "/etc/hosts"]
+  }
+
+
+
+
+
+  assert {
+    condition     = output.archive_path == ""
+    error_message = "archive_path should be empty when archive_name is not set"
+  }
+}
+
+run "apply_with_name" {
+  command = apply
+
+  variables {
+    agent_id               = "agent-123"
+    paths                  = ["/etc/hosts"]
+    archive_name           = "nightly"
+    output_dir             = "/tmp/backups"
+    compression            = "zstd"
+    create_archive_on_stop = true
+    create_script_name     = "custom-archiver"
+  }
+
+  assert {
+    condition     = output.archive_path == "/tmp/backups/nightly.tar.zst"
+    error_message = "archive_path should be computed from archive_name + output_dir + extension"
+  }
+
+
+
+
+}