49 lines
1.7 KiB
Markdown
49 lines
1.7 KiB
Markdown
# AGENTS.md
|
|
|
|
## Purpose
|
|
|
|
This repository hosts a small self-hosted scratch service (pastebin-like) written in Go.
|
|
|
|
Key product constraints:
|
|
- All routes are unauthenticated by design.
|
|
- One upload creates one scratch.
|
|
- For multiple files, users must upload a single archive file.
|
|
- Scratch data is stored gzip-compressed on disk transparently.
|
|
|
|
## Project layout
|
|
|
|
- `cmd/pastebin`: service entrypoint
|
|
- `internal/config`: config loading and validation
|
|
- `internal/http`: HTTP handlers and middleware
|
|
- `internal/storage`: filesystem storage and metadata index
|
|
- `internal/cleanup`: expiration cleanup worker
|
|
- `web/templates`, `web/static`: UI assets
|
|
|
|
## API routes
|
|
|
|
- `POST /api/scratch`
|
|
- `GET /api/scratch/{id}`
|
|
- `GET /s/{id}`
|
|
- `GET /raw/{id}`
|
|
|
|
## Build and test
|
|
|
|
Use `make help` as the source of truth for available build/test targets and descriptions.
|
|
|
|
## Coding conventions
|
|
|
|
- Keep changes minimal and focused.
|
|
- Backward compatibility is not a concern unless explicitly requested.
|
|
- Preserve unauthenticated behavior unless explicitly requested.
|
|
- Keep limits/operator controls configurable via config.
|
|
- Maintain write-route protections (allowlist and rate limiting).
|
|
- Keep storage behavior transparent for clients (compression is internal).
|
|
- Add or update tests for behavior changes.
|
|
|
|
## Cobra CLI conventions
|
|
|
|
- Keep `cmd/pastebin/main.go` focused on `main()` and root command wiring.
|
|
- Put each Cobra subcommand in its own file (for example `cmd/pastebin/server.go`).
|
|
- Start the service through the explicit subcommand (`scratchbox server`), not from the root command directly.
|
|
- Validate command arguments with Cobra arg validators (for example `cobra.NoArgs`) where applicable.
|