Categorygithub.com/mstoykov/cmd
modulepackage
1.3.0
Repository: https://github.com/mstoykov/cmd.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
24
Dependents
0
Files
1.2k SLOC

# README

GitHub release GoDoc Build Status Go Report Card License

Go Command Framework

This is a framework to create well-behaving commands.

Features

  • Context-based goroutine management.
  • Signal handlers.
  • Graceful stop/restart for any kind of network servers.
  • Logging options.
  • Enhanced http.Server.
  • Ultra fast UUID-like ID generator.
  • Activity tracking.
  • Support for systemd socket activation.

Requirements

Go 1.7 or better.

Specifications

Commands using this framework implement these external specifications:

Command-line options

  • -logfile FILE

    Output logs to FILE instead of standard error.

  • -loglevel LEVEL

    Change logging threshold to LEVEL. Default is info.
    LEVEL is one of critical, error, warning, info, or debug.

  • -logfmt FORMAT

    Change log formatter. Default is plain.
    FORMAT is one of plain, logfmt, or json.

Signal Handlers

  • SIGUSR1

    If -logfile is specified, this signal make the program reopen the log file to cooperate with an external log rotation program.

    On Windows, this is not implemented.

  • SIGINT and SIGTERM

    These signals cancel the context of the global environment, and hence goroutines registered with the environment. Usually this will result in graceful stop of network servers, if any.

    On Windows, only SIGINT is handled.

  • SIGHUP

    This signal is used to restart network servers gracefully. Internally, the main (master) process restarts its child process. The PID of the master process thus will not change.

    There is one limitation: the location of log file cannot be changed by graceful restart. To change log file location, the server need to be (gracefully) stopped and started.

    On Windows, this is not implemented.

Environment variables

  • REQUEST_ID_HEADER

    The value of this variable is used as HTTP header name. The HTTP header is used to track activities across services. The default header name is "X-Cybozu-Request-ID".

  • CYBOZU_LISTEN_FDS

    This is used internally for graceful restart.

Usage

Read Tutorial, the design notes and godoc.

Real world examples

Pull requests are welcome to add your project to this list!

License

MIT

# Packages

No description provided by the author

# Functions

Cancel cancels the base context of the global environment.
CommandContext is similar to exec.CommandContext, but returns *LogCmd with its Context set to ctx.
FieldsFromContext returns a map of fields containing context information.
GenerateID genereates an ID using the default generator.
Go starts a goroutine that executes f in the global environment.
GoWithID calls Go with a context having a new request tracking ID.
IsSignaled returns true if err returned by Wait indicates that the program has received SIGINT or SIGTERM.
NewEnvironment creates a new Environment.
NewIDGenerator creates a new IDGenerator.
Stop just declares no further Go will be called.
SystemdListeners returns listeners from systemd socket activation.
UTF8StringFromBytes returns a valid UTF-8 string from maybe invalid slice of bytes.
Wait waits for Stop or Cancel, and for all goroutines started by Go to finish.
WithRequestID returns a new context with a request ID as a value.

# Constants

RequestIDContextKey is a context key for request ID.

# Structs

AccessLog is to decode access log records from HTTPServer.
Environment implements context-based goroutine management.
ExecLog is a struct to decode command execution log from LogCmd.
Graceful is a struct to implement graceful restart servers.
HTTPClient is a thin wrapper for *http.Client.
HTTPServer is a wrapper for http.Server.
IDGenerator generates ID suitable for request tracking.
LogCmd is a wrapper for *exec.Cmd to record command execution results.
LogConfig configures cybozu-go/log's default logger.
RequestLog is to decode request log from HTTPClient.
Server is a generic network server that accepts connections and invokes Handler in a goroutine for each connection.

# Interfaces

StdResponseWriter is the interface implemented by the ResponseWriter from http.Server.