Skip to main content

🤝 Contributing

💻 Development Workflow​

📋 Prerequisites​

  • Go 1.26+ — required for compilation
  • Node.js 20+ — required for building the documentation site

🔨 Building​

End users: Use the setup script instead — see Installation. The go build workflow below is for development and testing only.

# Compile the binary
go build -o tresor.exe .

# Build with version info
go build -ldflags "-X main.version=1.0.0 -X main.commit=abc123" -o tresor.exe .

🧪 Running Tests​

# All unit tests
go test ./...

# Single package
go test ./internal/engine/...

# E2E integration (requires running daemon)
./tresor.exe run --config config.yaml &
go test -tags=integration ./e2e/...

See the /Tresor-docs/docs/dev/testing page for the full verification sequence.

📝 Code Style​

  • Follow Go conventions (gofmt for formatting, govet for static analysis)
  • Match existing code patterns: naming, comment density, error handling
  • Use table-driven tests for comprehensive coverage
  • Write tests before or alongside implementation

🔌 Adding a New Plugin​

Build custom traffic modifications as JavaScript API V2 packages: transform request metadata and bodies, response headers and bodies, or SSE events and collection behavior. Explore Ladbaby/Tresor-plugins for examples and inspiration, then implement the behavior your application needs. Packages support hot reload: install and enable a new version without rebuilding or restarting the gateway; future requests use it while in-flight requests retain their pinned package.

Automatic API format conversion is handled by the native Go layer.

  1. Create a package directory with manifest.json (api_version: 2) and a CommonJS JavaScript entry file.
  2. Implement the needed synchronous hooks using internal/jsplugins/api.d.ts. Do not add user configuration or logging capabilities.
  3. Run tresor plugin lint <directory> and tresor plugin pack <directory> --output <new-file>; neither executes source.
  4. Install into a test daemon with tresor plugin install <directory> and add the plugin ID to a matching routing rule.
  5. Test buffered and streaming requests, malformed inputs, failure termination, and cleanup. Bump the manifest version for changed published source.

See the Plugin System guide for the native/JS boundary, lifecycle, packaging, and runtime limitations.

🌐 Modifying the Web UI​

The web UI source files are in internal/api/web/:

  • index.html — Page structure and tab content (downstreams, aliases, rules, settings, about)
  • style.css — Styling and responsive layout
  • app.js — Application logic, API calls, dynamic rendering, login screen, theme toggle

The embedded files are compiled into the binary via //go:embed web/* in internal/api/embed.go. After editing, rebuild the binary.

🧪 Testing Web UI Changes​

  1. Rebuild: go build -o tresor.exe .
  2. Start the daemon: ./tresor.exe run --config config.yaml
  3. Navigate to each affected tab in the browser
  4. Perform core interactions (create, edit, delete, hot-switch)
  5. Verify the UI reflects expected state and no JavaScript errors occur

📚 Documentation​

The documentation site is a standalone Docusaurus project (repo: ladbaby/Tresor-docs). Docs source files are in docs-content/, organized under user/ and dev/ subdirectories.

# Install dependencies (first time only)
npm install

# Start development server with hot reload
npm start

# Build for production
npm run build

# Serve the built site locally
npm run serve

✏️ Documentation Conventions​

  • Use .mdx format for all documentation pages
  • Frontmatter must include title and description
  • Use <Tabs> and <TabItem> for platform-specific instructions
  • Link between related pages using absolute paths with the full site path (e.g., /Tresor-docs/docs/user/configuration)
  • Keep user docs focused on what and why; keep developer docs focused on how

📬 Pull Request Process​

  1. Fork the repository and create a feature branch
  2. Make your changes following the code style guidelines
  3. Run the full test suite: go test ./...
  4. Update documentation if your change affects user-facing behavior
  5. Submit the pull request with a clear description of changes
  6. Ensure CI checks pass (build, tests)

📌 Git Conventions​

  • Commit messages follow conventional commit style: type(scope): message
    • Types: feat, fix, docs, ci, refactor, test
    • Example: fix(engine): handle nil pipeline context in streaming transform
  • Keep commits focused and atomic
  • Squash related commits before merging