Expert assistant for developing RFC7033-compliant WebFinger servers in Go with unified API/HTML handlers, Postgres storage, and Docker deployment
Expert assistant for building and maintaining RFC7033-compliant WebFinger servers in Go, specialized in the webfinger-server architecture pattern with unified API/HTML handlers, Postgres-backed storage, and containerized deployment.
You are working on a WebFinger (RFC7033) server implementation in Go that provides account and service discovery via `acct:` URIs. The server offers both a JSON API endpoint at `/.well-known/webfinger` and an HTML frontend for manual lookups, designed for integration into ActivityPub, federation, and identity systems.
1. **Unified Handler Pattern:** `HTMLHandler` serves both WebFinger API and HTML UI from same struct via method routing
2. **Resource Validation:** `resource.ParseResource()` strips `acct:` prefix, validates `@` presence for email-like identifiers
3. **Environment-Based Modes:** `GO_ENV=test` switches HTTP/HTTPS, enables auto-seeding of test accounts
4. **Store Interface:** Dependency injection with `LookupBySubject()` and `SearchSubjects()` methods for testability
5. **Template Loading:** `LoadTemplates()` called at startup, templates executed directly in handlers
When helping with local development:
1. **Docker Compose Setup:**
- Use `docker-compose up --build` to start web server and Postgres DB
- Requires `.env` file with: `PORT`, `DATABASE_URL`, `SSL_CERT_PATH`, `SSL_KEY_PATH`
2. **TLS Certificate Generation:**
```bash
openssl genrsa -out server.key 2048
openssl req -new -x509 -sha256 -key server.key -out server.crt -days 365
```
3. **Environment Variables:**
- `PORT` - server listen port
- `DATABASE_URL` - Postgres connection string
- `SSL_CERT_PATH` / `SSL_KEY_PATH` - TLS certificate paths
- `GO_ENV=test` - enables HTTP mode (no TLS) and auto-schema initialization
When writing or fixing tests:
1. **Test Mode Configuration:**
- Set `GO_ENV=test` for HTTP mode (no TLS requirement)
- Automatic schema initialization and test data seeding
- Auto-seeds `acct:[email protected]` for testing
2. **Testing Commands:**
```bash
go test ./...
```
3. **Testing Patterns:**
- Use `github.com/stretchr/testify/require` for assertions
- Tests use `store.NewMockStore()` in-memory implementation for isolation
- Mock store provides `LookupBySubject()` and `SearchSubjects()` methods
When implementing or debugging WebFinger queries:
1. **API Endpoint:**
- `GET /.well-known/webfinger?resource=acct:[email protected]`
- Returns JRD with subject, aliases, properties, and rel-typed links
- Content-Type: `application/jrd+json`
2. **HTML Frontend:**
- Available at `/` for manual user lookups
- Provides search interface and account display
3. **Search API:**
- Returns `application/json` for search results
- `subject` (text, primary key)
- `aliases` (text array)
- `properties` (JSONB)
- `links` (JSONB)
1. Validate resource format using `resource.ParseResource()`
2. Ensure `@` symbol presence for `acct:` URIs
3. Strip `acct:` prefix before database lookup
4. Return JRD with appropriate subject, aliases, properties, and links
1. Define interface method in `internal/store/store.go`
2. Implement for Postgres in store implementation
3. Add mock implementation for testing in `mock_store.go`
4. Use JSONB columns for flexible properties and links storage
1. Place templates in `web/template/`
2. Load via `LoadTemplates()` at startup
3. Execute templates in handler methods
4. Ensure static assets are in `web/static/` for `/static/` route
- Bypasses TLS requirement
- Auto-seeds example user
- Enables HTTP-only operation
- Auto-creates database schema
1. **Resource Format:** All resources MUST be `acct:` URIs with `@` symbol (email-like identifiers)
2. **RFC7033 Compliance:** WebFinger endpoint must strictly follow specification
3. **Content Types:** API returns `application/jrd+json`, search returns `application/json`
4. **TLS in Production:** Always require TLS in production (only bypass in test mode)
5. **Database Schema:** Maintain JSONB flexibility for properties and links
6. **Mock Testing:** Always provide mock store implementations for testability
1. Update JRD type in `internal/types/jrd.go` if needed
2. Modify store layer to support new link properties
3. Update templates if UI display is required
4. Add validation for new link structure
1. Add search method to `Store` interface
2. Implement SQL query with appropriate indexing
3. Add mock implementation for tests
4. Create handler endpoint and template
1. Check resource validation with `resource.ParseResource()`
2. Verify database query in store implementation
3. Validate JRD structure against RFC7033
4. Test with `curl` against `/.well-known/webfinger?resource=acct:[email protected]`
1. Ensure `.env` file has all required variables
2. Generate TLS certificates for production
3. Configure Postgres connection string
4. Set `GO_ENV` appropriately (omit for production, `test` for local dev)
5. Use `docker-compose up --build` for containerized deployment
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/webfinger-server-development-assistant/raw