release v0.8.8

Author: novnc

.github/instructions/copilot-instructions.md

@@ -121,70 +121,109 @@ type PasteStore interface {
 ## Code Organization
 
 ```
-/
-├── main.go              # Entry point, config, router setup
-├── config/
-│   └── config.go        # Configuration struct and parsing
-├── storage/
-│   ├── interface.go     # PasteStore interface
-│   ├── filesystem.go    # Filesystem implementation (server mode)
-│   └── s3.go            # S3 implementation (Lambda mode)
-├── handlers/
-│   ├── paste.go         # Upload, view, raw endpoints
-│   ├── burn.go          # Burn-after-read functionality
-│   ├── meta.go          # Metadata endpoint
-│   └── system.go        # Health endpoint
-├── models/
-│   └── paste.go         # Paste struct and utilities
-├── static/
-│   ├── index.html       # Web UI
-│   ├── style.css        # Styling
-│   └── script.js        # Frontend JS
-└── utils/
-    ├── slug.go          # Slug generation
-    └── mime.go          # Content-type detection
+## nclip Copilot Instructions (2025)
+
+This document describes the current architecture, coding conventions, testing and deployment practices for `nclip`. It's targeted at contributors and any automated copilot/coding agent assisting with the codebase.
+
+### 1) Test and Script Cleanup (must follow)
+
+All integration tests and scripts must clean up the artifacts they create. Recommended patterns:
+- Create test artifacts with a predictable prefix (e.g. `nclip-test-<slug>`), and delete only matching files during cleanup.
+- When prefixing isn't possible, delete files in `./data` only if they are recently modified (e.g. `-mmin -60`) and/or explicitly recorded in a temp file during the test run.
+- Always remove temporary files in `/tmp/` created by tests (use explicit names).
+
+This avoids accidental deletion of unrelated data and keeps CI reproducible.
+
+---
+
+### 2) High-level Architecture
+
+- Language: Go (1.25+ recommended)
+- HTTP framework: Gin
+- Storage abstraction: `PasteStore` interface (Filesystem and S3 implementations)
+- Data model: JSON metadata + raw binary content
+- Configuration: environment variables and CLI flags
+
+### 3) API Endpoints (current)
+
+- GET / — Web UI (upload form)
+- POST / — Upload paste (returns paste URL)
+- POST /burn/ — Burn-after-read paste
+- GET /{slug} — HTML view
+- GET /raw/{slug} — Raw content download (sets Content-Disposition)
+- GET /api/v1/meta/{slug} — Metadata JSON
+- GET /json/{slug} — Alias for metadata
+- GET /health — Health check
+
+### 4) Data Types
+
+Paste metadata (canonical):
+
+```go
+type Paste struct {
+    ID            string     `json:"id"`
+    CreatedAt     time.Time  `json:"created_at"`
+    ExpiresAt     *time.Time `json:"expires_at,omitempty"`
+    Size          int64      `json:"size"`
+    ContentType   string     `json:"content_type"`
+    BurnAfterRead bool       `json:"burn_after_read"`
+    ReadCount     int        `json:"read_count"`
+}
 ```
 
-## Testing Strategy
+### 5) Storage interface
+
+```go
+type PasteStore interface {
+    StoreContent(id string, content []byte) error
+    StoreMetadata(id string, meta *Paste) error
+    GetMetadata(id string) (*Paste, error)
+    GetContent(id string) ([]byte, error)
+    Delete(id string) error
+    IncrementReadCount(id string) error
+}
+```
+
+Note: The concrete methods in this repository follow this pattern (filesystem uses files, S3 uses object + metadata JSON files).
+
+### 6) Implementation notes
+
+- Content-Type: Prefer client-provided `Content-Type` header; fall back to filename extension and then content-based detection. Keep `utils/mime.go` small and testable.
+- Filenames: Download endpoints should include a user-friendly extension (via `utils.ExtensionByMime`). Text content should be served inline; binaries as attachments.
+- Burn-after-read: Ensure atomic delete after the first successful read (store-level delete or transactional approach).
+- Slugs: Uppercase alphanumeric by default; configurable length.
+
+### 7) Error handling and logging
+
+- Return JSON errors: `{ "error": "message" }`
+- Use appropriate HTTP status codes
+- Prefer structured logs (key/value or JSON); guard verbose debug behind a debug flag or environment variable
 
-- Unit tests for all storage implementations
-- HTTP endpoint tests using httptest
-- Mock PasteStore for handler testing
-- Integration tests with real storage backends
-- Test both Lambda and server deployment modes
+### 8) Testing
 
+- Unit tests for utils, storage, and services
+- Handler tests using httptest and a Mock PasteStore
+- Integration tests (scripts/integration-test.sh) exercise the real binary and filesystem backend
+- CI runs: unit tests, `golangci-lint` (includes `gocyclo`), and integration tests on main/dev branches
 
-## Environment Variables
+### 9) CI / Linting
 
-All main configuration is via these environment variables (all have CLI flag equivalents):
+- `golangci-lint` is used (configurable via `.golangci.yml`). `gocyclo` is enabled; keep functions under complexity thresholds where practical. Refactor complex helpers into small, testable functions.
 
-| Environment Variable      | CLI Flag         | Description                                 |
-|--------------------------|------------------|---------------------------------------------|
-| NCLIP_PORT               | --port           | HTTP server port (default: 8080)            |
-| NCLIP_URL                | --url            | Base URL for paste links                    |
-| NCLIP_SLUG_LENGTH        | --slug-length    | Length of generated paste IDs (default: 5)  |
-| NCLIP_BUFFER_SIZE        | --buffer-size    | Max upload size in bytes (default: 5MB)     |
-| NCLIP_TTL                | --ttl            | Default paste expiration (default: 24h)     |
-| NCLIP_DATA_DIR           | --data-dir       | Local data directory (default: ./data)      |
-| NCLIP_S3_BUCKET          | --s3-bucket      | S3 bucket for Lambda mode                   |
-| NCLIP_S3_PREFIX          | --s3-prefix      | S3 key prefix (optional)                    |
+### 10) Deployment
 
-**Note:**
-- `GIN_MODE`, `AWS_LAMBDA_FUNCTION_NAME`, and `S3_BUCKET` are used only in deployment workflows (e.g., GitHub Actions, Lambda detection), not for app configuration.
-- NCLIP_MONGO_URL and --mongo-url are no longer supported.
+- Server mode: standard HTTP server with filesystem storage
+- Lambda mode: S3-backed, same codebase. Use `AWS_LAMBDA_FUNCTION_NAME` or environment-driven adapter to detect Lambda runtime. Wrap Gin with an adapter (aws-lambda-go-api-proxy or similar).
 
+### 11) Security and operational notes
 
-## Deployment Modes
+- No authentication required by design; consider adding rate-limiting or abuse protection for public deployments.
+- Ensure S3 permissions are scoped to required actions only.
 
-1. **Server mode**: Uses filesystem, full HTTP server
-2. **AWS Lambda**: Uses S3, same codebase with Lambda adapter
-3. **Both Lambda and server mode should use the same main.go, and use the AWS_LAMBDA_FUNCTION_NAME variable to determine the mode. (Don't separate 2 main.go for 2 modes )**
+---
 
-Both modes share identical API and behavior.
+If you want, I can also:
+- Convert integration-test cleanup to a prefix-based approach, or
+- Add a short contributor checklist in this file with exact commands to run locally (build, run server, run integration tests).
 
-## Lambda Deployment with S3
-- The Lambda code should support http v2.0 payload format. (This is the default for new Lambda functions behind an API Gateway HTTP API.)
-- Use AWS Lambda Go SDK
-- Wrap Gin router with Lambda adapter
-- S3 bucket is specified via `NCLIP_S3_BUCKET` env var
-- Ensure the Lambda execution role has permissions for S3 actions: `s3:GetObject`, `s3:PutObject`, `s3:DeleteObject`
+If you'd like this file split into separate CONTRIBUTING.md and ARCHITECTURE.md files I can create them as well.

.github/workflows/test.yml

@@ -296,7 +296,8 @@ jobs:
         if: failure()
         uses: actions/upload-artifact@v4
         with:
-          name: integration-test-artifacts
+          # include matrix.go-version and run id to avoid name collisions when multiple matrix jobs run in parallel
+          name: integration-test-artifacts-${{ matrix.go-version }}-run${{ github.run_id }}
           path: |
             nclip
             scripts/

.gitignore

@@ -48,4 +48,5 @@ go.work
 bootstrap
 main
 core.*
+.nfs.*
 

.golangci.yml

@@ -2,7 +2,7 @@ version: "2"
 
 run:
   timeout: 5m
-  tests: false  # Skip test files to avoid errcheck issues
+  tests: false # Skip test files to avoid errcheck issues
 
 linters:
   enable:
@@ -14,3 +14,9 @@ linters:
     - misspell
     - unconvert
     - gocyclo
+
+  settings:
+    gocyclo:
+      # Minimal code complexity to report.
+      # Default: 30 (but we recommend 10-20)
+      min-complexity: 15

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 johnwmail
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -12,21 +12,18 @@ A modern, high-performance HTTP clipboard app written in Go with Gin framework.
 ## Table of Contents
 
 - [Overview](#overview)
-- [Features](#-features)
-- [Quick Start](#-quick-start)
-- [API Endpoints](#-api-endpoints)
-- [Client Usage Examples](#-usage-examples)
-- [Storage Architecture](#storage-architecture)
-- [Configuration](#-configuration)
-- [Deployment](#deployment)
-  - [Docker](#-docker-deployment)
-  - [Kubernetes](#kubernetes)
-  - [AWS Lambda](#-aws-lambda-deployment)
-- [Monitoring](#-monitoring)
-- [Development](#-development)
-- [Contributing](#-contributing)
-- [License](#-license)
-- [Links](#-links)
+- [Features](#✨-features)
+- [Quick Start](#🚀-quick-start)
+- [API Endpoints](#📋-api-endpoints)
+- [Storage Backends](#🗄️-storage-backends)
+- [Configuration](#⚙️-configuration)
+- [Deployment](#☁️-deployment)
+  - [Docker](#🐳-docker-deployment)
+  - [Kubernetes](#☸️-kubernetes-deployment)
+  - [AWS Lambda](#☁️-aws-lambda-deployment)
+- [Monitoring](#📊-monitoring)
+- [Development](#🔧-development)
+- [Links](#🔗-links)
 
 ## Overview
 
@@ -119,9 +116,7 @@ export NCLIP_TTL=24h
 ./nclip
 ```
 
-## � Deployment
-
-nclip supports multiple deployment methods: Docker, Kubernetes, and AWS Lambda. Choose the deployment that best fits your needs.
+## ☁️ Deployment
 
 ### Quick Start Options
 
@@ -284,7 +279,7 @@ export NCLIP_PORT=3000
 ./nclip --url https://demo.nclip.app --ttl 48h
 ```
 
-## �� Monitoring
+## 📊 Monitoring
 
 - **Health Check**: `GET /health` - Returns 200 OK with system status
 - **Structured Logging**: JSON format with request tracing
@@ -332,79 +327,6 @@ go run main.go
 bash scripts/integration-tests.sh
 ```
 
-### Project Structure
-```
-/
-├── main.go              # Unified entry point (server mode + Lambda)
-├── main_test.go         # Integration tests
-├── config/              # Configuration management
-│   ├── config.go        # Configuration loading from env vars and CLI flags
-│   └── config_test.go   # Configuration tests
-├── handlers/            # HTTP request handlers
-│   ├── paste.go         # Main paste upload/retrieval handler
-│   ├── paste_test.go    # Paste handler tests
-│   ├── meta.go          # Metadata API handler
-│   ├── meta_test.go     # Metadata handler tests
-│   ├── system.go        # System endpoints (health, etc.)
-│   ├── system_test.go   # System handler tests
-│   ├── webui.go         # Web UI handler
-│   ├── webui_test.go    # Web UI tests
-│   ├── retrieval/       # Paste retrieval handlers
-│   └── upload/          # Paste upload handlers
-├── internal/            # Private application code
-│   └── services/        # Business logic services
-│       └── paste_service.go # Paste business logic
-├── models/              # Data models and structures
-│   ├── paste.go         # Paste data model
-│   └── paste_test.go    # Paste model tests
-├── storage/             # Storage abstraction layer
-│   ├── interface.go     # PasteStore interface definition
-│   ├── interface_test.go # Interface tests
-│   ├── filesystem.go    # Filesystem storage (server mode)
-│   ├── filesystem_test.go # Filesystem storage tests
-│   ├── s3.go            # S3 storage (Lambda mode)
-│   ├── s3_test.go       # S3 storage tests
-│   ├── s3util.go        # S3 utility functions
-│   ├── s3util_test.go   # S3 utility tests
-│   └── storage_test.go  # Storage integration tests
-├── utils/               # Shared utilities
-│   ├── debug.go         # Debug logging utilities
-│   ├── debug_test.go    # Debug utility tests
-│   ├── mime.go          # MIME type detection
-│   ├── mime_test.go     # MIME detection tests
-│   ├── slug.go          # Slug generation utilities
-│   └── slug_test.go     # Slug generation tests
-├── static/              # Static web assets
-│   ├── index.html       # Main web UI
-│   ├── favicon.ico      # Favicon
-│   ├── style.css        # CSS styles
-│   ├── script.js        # JavaScript functionality
-│   └── view.html        # Paste view template
-├── docs/                # Documentation
-│   ├── CLIENTS.md       # Client usage examples
-│   ├── CONTAINER_CLEANUP.md # Container management
-│   ├── INTEGRATION-TESTS.md # Integration testing
-│   ├── KUBERNETES.md    # Kubernetes deployment
-│   └── LAMBDA.md        # AWS Lambda deployment
-├── k8s/                 # Kubernetes manifests
-│   ├── deployment.yaml  # Deployment configuration
-│   ├── service.yaml     # Service configuration
-│   ├── ingress.yaml     # Ingress configuration
-│   ├── namespace.yaml   # Namespace definition
-│   ├── kustomization.yaml # Kustomize configuration
-│   └── pvc.yaml         # Persistent volume claim
-├── scripts/             # Utility scripts
-│   └── integration-test.sh # Integration test runner
-├── .github/             # GitHub configuration
-│   └── workflows/       # GitHub Actions workflows
-├── Dockerfile           # Docker image definition
-├── docker-compose.yml   # Docker Compose configuration
-├── go.mod               # Go module definition
-├── go.sum               # Go module checksums
-├── .golangci.yml        # Go linting configuration
-└── .gitignore           # Git ignore rules
-```
-
 ## 🔗 Links
 
 - **Documentation**: [docs/](docs/)

main.go

@@ -94,7 +94,12 @@ func main() {
 		log.Println("Lambda mode: Using S3 storage")
 	} else {
 		// Server mode: Use filesystem
-		store, err = storage.NewFilesystemStore()
+		// Ensure data directory exists before initializing filesystem storage
+		dataDir := os.Getenv("NCLIP_DATA_DIR")
+		if dataDir == "" {
+			dataDir = "./data"
+		}
+		store, err = storage.NewFilesystemStore(dataDir)
 		if err != nil {
 			log.Fatalf("Failed to initialize filesystem storage: %v", err)
 		}