2ead66f012
- Move gemini URL parsing from common/ to gemini/ package - Add structured status codes in gemini/status_codes.go - Improve error handling with proper Gemini status codes - Update configuration field naming (Listen -> ListenAddr) - Add UTF-8 validation for URLs - Enhance security with better path validation - Add CLAUDE.md for development guidance - Include example content in srv/ directory - Update build system to use standard shell
2.7 KiB
2.7 KiB
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Project Overview
Gemserve is a simple Gemini protocol server written in Go that serves static files over TLS-encrypted connections. The Gemini protocol is a lightweight, privacy-focused alternative to HTTP designed for serving text-based content.
Development Commands
# Build, test, and format everything
make
# Run tests only
make test
# Build binary to ./dist/gemserve
make build
# Format code with gofumpt and gci
make fmt
# Run golangci-lint
make lint
# Run linter with auto-fix
make lintfix
# Clean build artifacts
make clean
# Run the server (after building)
./dist/gemserve
# Generate TLS certificates for development
certs/generate.sh
Architecture
Core Components
- main.go: Entry point with TLS server setup, signal handling, and graceful shutdown
- server/: Request processing, file serving, and Gemini protocol response handling
- gemini/: Gemini protocol implementation (URL parsing, status codes, path normalization)
- config/: CLI-based configuration system
- uid/: Connection ID generation for logging
Key Patterns
- Security First: All file operations use
filepath.IsLocal()and path cleaning to prevent directory traversal - Error Handling: Uses structured errors with
xerrorspackage for consistent error propagation - Logging: Structured logging with configurable levels via internal logging package
- Testing: Table-driven tests with parallel execution, heavy focus on security edge cases
Request Flow
- TLS connection established on port 1965
- Read up to 1KB request (Gemini spec limit)
- Parse and normalize Gemini URL
- Validate path security (prevent traversal)
- Serve file or directory index with appropriate MIME type
- Send response with proper Gemini status codes
Configuration
Server configured via CLI flags:
--listen: Server address (default: localhost:1965)--root-path: Directory to serve files from--dir-indexing: Enable directory browsing--log-level: Logging verbosity--response-timeout: Response timeout in seconds
Testing Strategy
- server/server_test.go: Path security and file serving tests
- gemini/url_test.go: URL parsing and normalization tests
- Focus on security edge cases (Unicode, traversal attempts, malformed URLs)
- Use parallel test execution for performance
Security Considerations
- All connections require TLS certificates (stored in certs/)
- Path traversal protection is critical - test thoroughly when modifying file serving logic
- Request size limited to 1KB per Gemini specification
- Input validation on all URLs and paths