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 xerrors package 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

2.7 KiB Raw Blame History