httpserver

Documentation

Overview

Package httpserver provides a factory for creating agent HTTP servers. This eliminates ~125 lines of boilerplate per agent.

Index

• type Builder
  • func NewBuilder(name string, port int) *Builder
  • func (b *Builder) Build() (*Server, error)
  • func (b *Builder) WithDualModeLog() *Builder
  • func (b *Builder) WithHandler(path string, handler http.Handler) *Builder
  • func (b *Builder) WithHandlerFunc(path string, handler http.HandlerFunc) *Builder
  • func (b *Builder) WithHealthHandler(handler http.HandlerFunc) *Builder
  • func (b *Builder) WithTimeouts(read, write, idle time.Duration) *Builder
• type Config
• type Server
  • func New(cfg Config) (*Server, error)
  • func (s *Server) Addr() string
  • func (s *Server) Start() error
  • func (s *Server) StartAsync()
  • func (s *Server) StartWithListener(listener net.Listener) error
  • func (s *Server) Stop(ctx context.Context) error

Types

type Builder

type Builder struct {
	// contains filtered or unexported fields
}

Builder provides a fluent interface for building server configs.

func NewBuilder

func NewBuilder(name string, port int) *Builder

NewBuilder creates a new server config builder.

func (*Builder) Build

func (b *Builder) Build() (*Server, error)

Build creates the server.

func (*Builder) WithDualModeLog

func (b *Builder) WithDualModeLog() *Builder

WithDualModeLog enables the dual mode log message.

func (*Builder) WithHandler

func (b *Builder) WithHandler(path string, handler http.Handler) *Builder

WithHandler adds an http.Handler for the given path.

func (*Builder) WithHandlerFunc

func (b *Builder) WithHandlerFunc(path string, handler http.HandlerFunc) *Builder

WithHandlerFunc adds an http.HandlerFunc for the given path.

func (*Builder) WithHealthHandler

func (b *Builder) WithHealthHandler(handler http.HandlerFunc) *Builder

WithHealthHandler sets a custom health check handler.

func (*Builder) WithTimeouts

func (b *Builder) WithTimeouts(read, write, idle time.Duration) *Builder

WithTimeouts sets all timeouts.

type Config

type Config struct {
	// Name is a descriptive name for the server (used in logs).
	Name string

	// Port is the port to listen on. Required.
	Port int

	// Handlers maps paths to HTTP handlers.
	// Example: {"/research": researchHandler, "/synthesize": synthesizeHandler}
	Handlers map[string]http.Handler

	// HandlerFuncs maps paths to HTTP handler functions.
	// Example: {"/research": agent.HandleResearchRequest}
	HandlerFuncs map[string]http.HandlerFunc

	// ReadTimeout is the maximum duration for reading the entire request.
	// Default is 30 seconds.
	ReadTimeout time.Duration

	// WriteTimeout is the maximum duration before timing out writes of the response.
	// Default is 120 seconds (for long-running agent operations).
	WriteTimeout time.Duration

	// IdleTimeout is the maximum amount of time to wait for the next request.
	// Default is 60 seconds.
	IdleTimeout time.Duration

	// HealthPath is the path for the health check endpoint.
	// Default is "/health".
	HealthPath string

	// HealthHandler is a custom health check handler.
	// If nil, a simple "OK" response handler is used.
	HealthHandler http.HandlerFunc

	// EnableDualModeLog logs a message about dual HTTP/A2A mode.
	// Default is false.
	EnableDualModeLog bool
}

Config holds the configuration for an agent HTTP server.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server wraps an HTTP server with convenient lifecycle methods.

func New

func New(cfg Config) (*Server, error)

New creates a new agent HTTP server. This is a factory that eliminates ~25 lines of boilerplate per agent.

func (*Server) Addr

func (s *Server) Addr() string

Addr returns the configured address.

func (*Server) Start

func (s *Server) Start() error

Start starts the HTTP server. This method blocks until the server is stopped.

func (*Server) StartAsync

func (s *Server) StartAsync()

StartAsync starts the HTTP server in the background. Returns immediately. Use Stop() to shut down the server.

func (*Server) StartWithListener

func (s *Server) StartWithListener(listener net.Listener) error

StartWithListener starts the server using the provided listener. Useful for testing or when you need control over the listener.

func (*Server) Stop

func (s *Server) Stop(ctx context.Context) error

Stop gracefully shuts down the server.