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 func(context.Context) error) 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 hooks share a single deadline during graceful shutdown. If the drain fails, the server is force-closed and hooks receive a fresh bounded context so cleanup does not inherit an already-expired deadline.

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 func(context.Context) error) ServerOption

WithShutdownHook registers a hook run during graceful shutdown. Hooks run in reverse registration order. During a graceful drain they share the shutdown budget with the server; after a forced close they get a fresh bounded context because the drain context has already expired.

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. During a graceful drain, hooks run after the server stops serving, within the remaining shutdown budget. If the drain fails and the server is force-closed, hooks run with a fresh bounded context and may overlap abandoned handler goroutines that are still unwinding.