x: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this directory.

Build & Verify

cd x && go build ./...     # verify compilation
cd x && go vet ./...       # static analysis
cd x && go build ./... && go vet ./...   # both

There are no tests in this module. Build + vet is the verification path.

Architecture

x/ is the implementation layer for the GOST proxy framework. Every interface defined in core/ is implemented here. The module ties the whole system together: it provides ~25 handler implementations, ~25 listener implementations, ~20 dialer implementations, ~15 connector implementations, plus config parsing, registry management, and all cross-cutting concerns.

Component pattern (applies to every handler, listener, dialer, connector)

Every component follows this exact pattern:

// 1. init() self-registration via blank import
func init() {
    registry.HandlerRegistry().Register("http", NewHandler)
}

// 2. Private struct holding options + parsed metadata
type httpHandler struct {
    md      metadata
    options handler.Options
}

// 3. Functional options constructor
func NewHandler(opts ...handler.Option) handler.Handler {
    options := handler.Options{}
    for _, opt := range opts {
        opt(&options)
    }
    return &httpHandler{options: options}
}

// 4. Init extracts typed values from generic metadata
func (h *httpHandler) Init(md md.Metadata) error {
    return h.parseMetadata(md)
}

Each component package also defines a private metadata struct and a parseMetadata(md) method that uses mdutil.GetBool/GetInt/GetString/GetDuration(md, keys...) to extract configuration. Metadata keys are lowercased and multiple fallback keys are tried (e.g., "observePeriod", "observer.period", "observer.observePeriod").

Config parsing and service composition

config/parsing/service/parse.go is the critical wiring function. ParseService(cfg) does:

1. Defaults listener type to "tcp", handler type to "auto"
2. Sets up TLS config, network namespace, authentication, admission, bypass
3. Looks up the listener and handler factories from their registries, calls them with composed options
4. Creates a service.Service (which runs the accept loop calling handler.Handle per connection)
5. Wraps the listener in order: proxyproto → metrics → stats → admission → traffic limiter → connection limiter