storage-appliance/.github/copilot-instructions.md

You are an expert storage-systems engineer and Go backend architect.

Goal: Build a modern, sleek, high-performance storage appliance management UI similar to TrueNAS/Unraid.

Tech constraints:

• Backend: Go (standard library + minimal deps), Linux-first.
• UI: Server-rendered HTML using HTMX for interactions. No SPA frameworks.
• Services to manage: disks, ZFS pools/datasets/snapshots, NFS, SMB/CIFS, S3-compatible object storage, block storage via iSCSI/LUN.
• Must include RBAC, auditing, monitoring, and safe operations with rollback where possible.

Non-functional requirements:

• Safety-first: any destructive operation requires explicit confirmation and pre-checks.
• Idempotent: operations should be safe to re-run.
• Observability: structured logs + Prometheus metrics; health checks for all subsystems.
• Security: JWT or session auth, CSRF protection for HTMX requests, strong password hashing (argon2id/bcrypt), least privilege.
• Performance: avoid heavy background polling; use HTMX partial updates; use async jobs for slow operations with progress endpoints.

Architecture requirements:

• Clean architecture with clear boundaries:
  • internal/domain: core types, interfaces, policy (no OS calls).
  • internal/service: orchestration, validation, jobs.
  • internal/infra: Linux adapters (exec, netlink, zfs, nfs, samba, targetcli, minio), database, auth.
  • internal/http: handlers, middleware, templates, htmx partials.
• Use dependency injection via interfaces; no global state.
• Implement a job runner for long tasks (create pool, scrub, snapshot, export, rsync, etc.) with persistent job state in DB.
• Persist configuration and state in SQLite/Postgres (choose SQLite initially) with migrations.

Linux integration guidelines:

• Use command adapters for ZFS (zpool/zfs), NFS exports, Samba config, iSCSI (targetcli/ LIO), and MinIO for S3.
• All commands must be executed via a safe exec wrapper with context timeout, stdout/stderr capture, and redaction of secrets.
• Never embed secrets in logs.

UI guidelines:

• HTMX endpoints return HTML partials.
• Use TailwindCSS (CDN initially) for sleek UI.
• Provide: Dashboard, Storage, Shares, Block Storage, Object Storage, Monitoring, Users/Roles, Audit Log, Settings.
• Forms must show inline validation errors and success toasts.
• Each page should degrade gracefully: show partial error panel without breaking other widgets.

RBAC:

• Roles: admin, operator, viewer (extendable).
• Fine-grained permissions by resource: storage., shares., block., object., users., settings., audit.*.
• Enforce RBAC in middleware and again at service layer.

Monitoring:

• Export /metrics (Prometheus).
• Basic host metrics: CPU/mem/disk IO, pool health, scrubs, SMART status, NFS/SMB/iSCSI service status.
• Provide a Monitoring UI page that consumes internal metrics endpoints (rendered server-side).

Deliverables:

• Production-grade code: tests for domain/service layers, lintable, clear error handling.
• Provide code in small cohesive modules, avoid giant files.

Repo-specific quick notes

• Skeleton is a Go + HTMX app with cmd/appliance run server and Makefile for dev tasks.
• Key directories: internal/http (handlers, middleware), internal/domain, internal/service, internal/infra (stubs/adapters), internal/job, migrations/.
• Run locally: make run or go run ./cmd/appliance.
• DB: uses SQLite with migrations under migrations/ and internal/infra/sqlite/db.
• Auth: temporary header-based dev-auth (X-Auth-User, X-Auth-Role) to drive role checks in middleware.
• HTMX: Templates in internal/templates use HTMX hx-get/hx-post patterns.
• Mock services for dev/test: internal/service/mock.
• Example API calls:
  • curl -H "X-Auth-User: viewer" -H "X-Auth-Role: viewer" http://127.0.0.1:8080/api/pools
  • curl -s -X POST -H "X-Auth-User: admin" -H "X-Auth-Role: admin" -H "Content-Type: application/json" -d '{"name":"tank","vdevs":["/dev/sda"]}' http://127.0.0.1:8080/api/pools

Tests and local dev

• Use go test ./... for unit tests and internal/service/mock to emulate hardware adapters.
• Tests may fallback to in-memory templates when internal/templates cannot be read.

Files to extend for new features

• For ZFS: add internal/infra/zfs adapter implementing internal/service.ZFSService.
• For SMB/NFS: add adapters implementing NFSService and SMBService.
• For object storage: add MinIO adapter in internal/infra/minio.
• For iSCSI: add an adapter under internal/infra/iscsi interacting with targetcli or kernel LIO.

If you need me to scaffold an adapter or add tests I can continue iterating.