cli

Documentation

Overview

Package cli provides lightweight command dispatch and HTTP server lifecycle helpers for Ohm applications.

Index

• Variables
• func RunHTTPServer(ctx context.Context, server *http.Server, shutdownTimeout time.Duration, ...) error
• type Command
  • func RoutesCommand(app interface{ ... }) Command
  • func ServerCommand(handler http.Handler, opts ...ServerOption) Command
• type IO
• type Option
  • func WithIO(commandIO IO) Option
• type Program
  • func New(name string, commands []Command, opts ...Option) *Program
  • func (p *Program) Run(ctx context.Context, args []string) error
• type ServerOption
  • func WithAddr(addr string) ServerOption
  • func WithServerRunner(runner ServerRunner) ServerOption
  • func WithShutdownHook(hook ShutdownHook) ServerOption
  • func WithShutdownTimeout(timeout time.Duration) ServerOption
• type ServerRunner
• type ShutdownHook

Variables

var ErrHelp = errors.New("help requested")

ErrHelp requests command help.

var ErrUsage = errors.New("usage error")

ErrUsage reports command-line usage errors.

Functions

func RunHTTPServer

func RunHTTPServer(ctx context.Context, server *http.Server, shutdownTimeout time.Duration, hooks []ShutdownHook) error

RunHTTPServer runs server until it stops or ctx is canceled, then runs the shutdown hooks. The drain and the hooks share a single deadline derived from shutdownTimeout, so total shutdown stays bounded by that budget.

Types

type Command

type Command struct {
	Name    string
	Summary string
	Usage   string
	Run     func(context.Context, IO, []string) error
}

Command is one application command.

func RoutesCommand

func RoutesCommand(app interface {
	Routes() ([]ohm.Route, error)
}) Command

RoutesCommand returns a command that prints registered routes.

func ServerCommand

func ServerCommand(handler http.Handler, opts ...ServerOption) Command

ServerCommand returns a command that boots an HTTP server.

type IO

type IO struct {
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
}

IO contains command input and output streams.

type Option

type Option func(*Program)

Option configures a Program.

func WithIO

func WithIO(commandIO IO) Option

WithIO configures the program streams.

type Program

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

Program dispatches application commands.

func New

func New(name string, commands []Command, opts ...Option) *Program

New creates a command program.

func (*Program) Run

func (p *Program) Run(ctx context.Context, args []string) error

Run dispatches args to a command.

type ServerOption

type ServerOption func(*serverConfig)

ServerOption configures ServerCommand.

func WithAddr

func WithAddr(addr string) ServerOption

WithAddr configures the default server address.

func WithServerRunner

func WithServerRunner(runner ServerRunner) ServerOption

WithServerRunner configures the server runner.

func WithShutdownHook

func WithShutdownHook(hook ShutdownHook) ServerOption

WithShutdownHook registers a hook run during graceful shutdown. Hooks run in reverse registration order, sharing the single shutdown budget with the server drain so total shutdown stays bounded by the shutdown timeout.

func WithShutdownTimeout

func WithShutdownTimeout(timeout time.Duration) ServerOption

WithShutdownTimeout configures graceful shutdown timeout.

type ServerRunner

type ServerRunner func(ctx context.Context, server *http.Server, shutdownTimeout time.Duration, hooks []ShutdownHook) error

ServerRunner runs an HTTP server and, once it stops, runs the shutdown hooks within the shutdown budget. A runner owns the full lifecycle, so custom runners are responsible for invoking the hooks they are given.

type ShutdownHook

type ShutdownHook func(context.Context) error

ShutdownHook releases resources during graceful shutdown. Hooks run after the server stops serving, within the remaining shutdown budget, and are the seam for flushing telemetry such as OpenTelemetry providers before the process exits.