README
¶
go-ipfs-cmds
ipfs commands library
cmds offers tools for describing and calling commands both locally and remotely, as well as encoding, formatting and transferring the result. It is the successor of go-ipfs/commands and contains a legacy layer such that it can handle previously defined commands.
Based on go-ipfs/commands.
Documentation
https://godoc.org/github.com/ipfs/go-ipfs-cmds
Contribute
Feel free to join in. All welcome. Open an issue!
This repository falls under the IPFS Code of Conduct.
Want to hack on IPFS?
License
MIT
Documentation
¶
Overview ¶
Package cmds helps building both standalone and client-server applications.
Semantics ¶
The basic building blocks are requests, commands, emitters and responses. A command consists of a description of the parameters and a function. The function is passed the request as well as an emitter as arguments. It does operations on the inputs and sends the results to the user by emitting them.
There are a number of emitters in this package and subpackages, but the user is free to create their own.
Commands ¶
A command is a struct containing the commands help text, a description of the arguments and options, the command's processing function and a type to let the caller know what type will be emitted. Optionally one of the functions PostRun and Encoder may be defined that consumes the function's emitted values and generates a visual representation for e.g. the terminal. Encoders work on a value-by-value basis, while PostRun operates on the value stream.
Emitters ¶
An emitter has the Emit method, that takes the command's function's output as an argument and passes it to the user.
type ResponseEmitter interface {
io.Closer
SetLength(length uint64)
SetError(err interface{}, code cmdkit.ErrorType)
Emit(value interface{}) error
}
The command's function does not know what kind of emitter it works with, so the same function may run locally or on a server, using an rpc interface. Emitters can also send errors using the SetError method.
The user-facing emitter usually is the cli emitter. Values emitter here will be printed to the terminal using either the Encoders or the PostRun function.
Responses ¶
A response is a value that the user can read emitted values from.
type Response interface {
Request() Request
Error() *cmdkit.Error
Length() uint64
Next() (interface{}, error)
}
Responses have a method Next() that returns the next emitted value and an error value. If the last element has been received, the returned error value is io.EOF. If the application code has sent an error using SetError, the error ErrRcvdError is returned on next, indicating that the caller should call Error(). Depending on the reponse type, other errors may also occur.
Pipes ¶
Pipes are pairs (emitter, response), such that a value emitted on the emitter can be received in the response value. Most builtin emitters are "pipe" emitters. The most prominent examples are the channel pipe and the http pipe.
The channel pipe is backed by a channel. The only error value returned by the response is io.EOF, which happens when the channel is closed.
The http pipe is backed by an http connection. The response can also return other errors, e.g. if there are errors on the network.
Examples ¶
To get a better idea of what's going on, take a look at the examples at https://github.com/ipfs/go-ipfs-cmds/tree/master/examples.
Index ¶
- Constants
- Variables
- func ClientError(msg string) error
- func Copy(re ResponseEmitter, res Response) error
- func EmitChan(re ResponseEmitter, ch <-chan interface{}) error
- func EmitOnce(re ResponseEmitter, v interface{}) error
- func MakeEncoder(f func(*Request, io.Writer, interface{}) error) func(*Request) func(io.Writer) Encoder
- func MakeTypedEncoder(f interface{}) func(*Request) func(io.Writer) Encoder
- func NewChanResponsePair(req *Request) (ResponseEmitter, Response)
- type Command
- func (c *Command) Call(req *Request, re ResponseEmitter, env Environment)
- func (c *Command) CheckArguments(req *Request) error
- func (c *Command) DebugValidate() map[string][]error
- func (c *Command) Get(path []string) (*Command, error)
- func (c *Command) GetOptions(path []string) (map[string]cmdkit.Option, error)
- func (c *Command) ProcessHelp()
- func (c *Command) Resolve(pth []string) ([]*Command, error)
- func (c *Command) Walk(visitor CommandVisitor)
- type CommandVisitor
- type Decoder
- type Encoder
- type EncoderFunc
- type EncoderMap
- type EncodingEmitter
- type EncodingType
- type Environment
- type Executor
- type Flusher
- type Function
- type MakeEnvironment
- type MakeExecutor
- type MaybeError
- type PostRunMap
- type PostRunType
- type ReqLog
- type ReqLogEntry
- type Request
- type Response
- type ResponseEmitter
- type Single
- type StdinArguments
- type TextEncoder
Constants ¶
const ( // General purpose Undefined = "" // EncodingTypes JSON = "json" XML = "xml" Protobuf = "protobuf" Text = "text" TextNewline = "textnl" // PostRunTypes CLI = "cli" )
Supported EncodingType constants.
const ( EncShort = "enc" EncLong = "encoding" RecShort = "r" RecLong = "recursive" ChanOpt = "stream-channels" TimeoutOpt = "timeout" OptShortHelp = "h" OptLongHelp = "help" )
Flag names
const DefaultOutputEncoding = JSON
Variables ¶
var ( // ErrNotCallable signals a command that cannot be called. ErrNotCallable = ClientError("This command can't be called directly. Try one of its subcommands.") // ErrNoFormatter signals that the command can not be formatted. ErrNoFormatter = ClientError("This command cannot be formatted to plain text") // ErrIncorrectType signales that the commands returned a value with unexpected type. ErrIncorrectType = errors.New("The command returned a value with a different type than expected") )
var ( ErrClosedEmitter = errors.New("cmds: emit on closed emitter") ErrClosingClosedEmitter = errors.New("cmds: closing closed emitter") )
var Decoders = map[EncodingType]func(w io.Reader) Decoder{ XML: func(r io.Reader) Decoder { return xml.NewDecoder(r) }, JSON: func(r io.Reader) Decoder { return json.NewDecoder(r) }, }
var Encoders = EncoderMap{ XML: func(req *Request) func(io.Writer) Encoder { return func(w io.Writer) Encoder { return xml.NewEncoder(w) } }, JSON: func(req *Request) func(io.Writer) Encoder { return func(w io.Writer) Encoder { return json.NewEncoder(w) } }, Text: func(req *Request) func(io.Writer) Encoder { return func(w io.Writer) Encoder { return TextEncoder{w: w} } }, TextNewline: func(req *Request) func(io.Writer) Encoder { return func(w io.Writer) Encoder { return TextEncoder{w: w, suffix: "\n"} } }, }
var OptionEncodingType = cmdkit.StringOption(EncLong, EncShort, "The encoding type the output should be encoded with (json, xml, or text)").WithDefault("text")
options that are used by this package
var OptionRecursivePath = cmdkit.BoolOption(RecLong, RecShort, "Add directory paths recursively").WithDefault(false)
var OptionStreamChannels = cmdkit.BoolOption(ChanOpt, "Stream channel output")
var OptionTimeout = cmdkit.StringOption(TimeoutOpt, "set a global timeout on the command")
Functions ¶
func ClientError ¶
func Copy ¶
func Copy(re ResponseEmitter, res Response) error
Copy sends all values received on res to re. If res is closed, it closes re.
func EmitChan ¶
func EmitChan(re ResponseEmitter, ch <-chan interface{}) error
func EmitOnce ¶
func EmitOnce(re ResponseEmitter, v interface{}) error
EmitOnce is a helper that emits a value wrapped in Single, to signal that this will be the only value sent.
func MakeEncoder ¶
func NewChanResponsePair ¶
func NewChanResponsePair(req *Request) (ResponseEmitter, Response)
Types ¶
type Command ¶
type Command struct {
Options []cmdkit.Option
Arguments []cmdkit.Argument
PreRun func(req *Request, env Environment) error
// Run is the function that processes the request to generate a response.
// Note that when executing the command over the HTTP API you can only read
// after writing when using multipart requests. The request body will not be
// available for reading after the HTTP connection has been written to.
Run Function
PostRun PostRunMap
Encoders EncoderMap
Helptext cmdkit.HelpText
// External denotes that a command is actually an external binary.
// fewer checks and validations will be performed on such commands.
External bool
// Type describes the type of the output of the Command's Run Function.
// In precise terms, the value of Type is an instance of the return type of
// the Run Function.
//
// ie. If command Run returns &Block{}, then Command.Type == &Block{}
Type interface{}
Subcommands map[string]*Command
}
Command is a runnable command, with input arguments and options (flags). It can also have Subcommands, to group units of work into sets.
func (*Command) Call ¶
func (c *Command) Call(req *Request, re ResponseEmitter, env Environment)
Call invokes the command for the given Request
func (*Command) CheckArguments ¶
CheckArguments checks that we have all the required string arguments, loading any from stdin if necessary.
func (*Command) DebugValidate ¶
DebugValidate checks if the command tree is well-formed.
This operation is slow and should be called from tests only.
func (*Command) GetOptions ¶
GetOptions returns the options in the given path of commands
func (*Command) ProcessHelp ¶
func (c *Command) ProcessHelp()
func (*Command) Walk ¶
func (c *Command) Walk(visitor CommandVisitor)
Walks tree of all subcommands (including this one)
type CommandVisitor ¶
type CommandVisitor func(*Command)
type Decoder ¶
type Decoder interface {
Decode(value interface{}) error
}
Decoder decodes values into value (which should be a pointer).
type Encoder ¶
type Encoder interface {
Encode(value interface{}) error
}
Encoder encodes values onto e.g. an io.Writer. Examples are json.Encoder and xml.Encoder.
type EncoderMap ¶
type EncoderMap map[EncodingType]EncoderFunc
type EncodingEmitter ¶ added in v1.0.22
type EncodingEmitter interface {
ResponseEmitter
SetEncoder(func(io.Writer) Encoder)
}
type EncodingType ¶
type EncodingType string
EncodingType defines a supported encoding
func GetEncoding ¶
func GetEncoding(req *Request) EncodingType
GetEncoding returns the EncodingType set in a request, falling back to JSON
type Environment ¶
type Environment interface {
// Context returns the environment's context.
Context() context.Context
}
Environment is the environment passed to commands. The only required method is Context.
type Executor ¶
type Executor interface {
Execute(req *Request, re ResponseEmitter, env Environment) error
}
func NewExecutor ¶
type Function ¶
type Function func(*Request, ResponseEmitter, Environment) error
Function is the type of function that Commands use. It reads from the Request, and writes results to the ResponseEmitter.
type MakeEnvironment ¶
type MakeEnvironment func(context.Context, *Request) (Environment, error)
MakeEnvironment takes a context and the request to construct the environment that is passed to the command's Run function. The user can define a function like this to pass it to cli.Run.
type MakeExecutor ¶
MakeExecutor takes the request and environment variable to construct the executor that determines how to call the command - i.e. by calling Run or making an API request to a daemon. The user can define a function like this to pass it to cli.Run.
type MaybeError ¶
type MaybeError struct {
Value interface{} // needs to be a pointer
Error *cmdkit.Error
// contains filtered or unexported fields
}
func (*MaybeError) Get ¶
func (m *MaybeError) Get() (interface{}, error)
func (*MaybeError) UnmarshalJSON ¶
func (m *MaybeError) UnmarshalJSON(data []byte) error
type PostRunMap ¶
type PostRunMap map[PostRunType]func(Response, ResponseEmitter) error
PostRunMap is the map used in Command.PostRun.
type ReqLog ¶
type ReqLog struct {
Requests []*ReqLogEntry
// contains filtered or unexported fields
}
func (*ReqLog) Add ¶
func (rl *ReqLog) Add(req *Request) *ReqLogEntry
func (*ReqLog) AddEntry ¶
func (rl *ReqLog) AddEntry(rle *ReqLogEntry)
func (*ReqLog) ClearInactive ¶
func (rl *ReqLog) ClearInactive()
func (*ReqLog) Finish ¶
func (rl *ReqLog) Finish(rle *ReqLogEntry)
func (*ReqLog) Report ¶
func (rl *ReqLog) Report() []*ReqLogEntry
Report generates a copy of all the entries in the requestlog
func (*ReqLog) SetKeepTime ¶
type ReqLogEntry ¶
type ReqLogEntry struct {
StartTime time.Time
EndTime time.Time
Active bool
Command string
Options map[string]interface{}
Args []string
ID int
}
func (*ReqLogEntry) Copy ¶
func (r *ReqLogEntry) Copy() *ReqLogEntry
type Request ¶
type Request struct {
Context context.Context
Root, Command *Command
Path []string
Arguments []string
Options cmdkit.OptMap
Files files.File
// contains filtered or unexported fields
}
Request represents a call to a command from a consumer
func NewRequest ¶
func NewRequest(ctx context.Context, path []string, opts cmdkit.OptMap, args []string, file files.File, root *Command) (*Request, error)
NewRequest returns a request initialized with given arguments An non-nil error will be returned if the provided option values are invalid
func (*Request) BodyArgs ¶
func (req *Request) BodyArgs() StdinArguments
BodyArgs returns a scanner that returns arguments passed in the body as tokens.
Returns nil if there are no arguments to be consumed via stdin.
func (*Request) FillDefaults ¶
fillDefault fills in default values if option has not been set
func (*Request) ParseBodyArgs ¶
type Response ¶
type Response interface {
Request() *Request
Error() *cmdkit.Error
Length() uint64
// Next returns the next emitted value.
// The returned error can be a network or decoding error.
Next() (interface{}, error)
}
Response is the result of a command request. Response is returned to the client.
func NewReaderResponse ¶
func NewReaderResponse(r io.Reader, encType EncodingType, req *Request) Response
type ResponseEmitter ¶
type ResponseEmitter interface {
// Close closes the underlying transport.
Close() error
// CloseWithError closes the underlying transport and makes subsequent read
// calls return the passed error.
CloseWithError(error) error
// SetLength sets the length of the output
// err is an interface{} so we don't have to manually convert to error.
SetLength(length uint64)
// Emit sends a value.
// If value is io.Reader we just copy that to the connection
// other values are marshalled.
Emit(value interface{}) error
}
ResponseEmitter encodes and sends the command code's output to the client. It is all a command can write to.
func NewFlushForwarder ¶
func NewFlushForwarder(re ResponseEmitter, f Flusher) ResponseEmitter
func NewWriterResponseEmitter ¶
func NewWriterResponseEmitter(w io.WriteCloser, req *Request, enc func(*Request) func(io.Writer) Encoder) ResponseEmitter
type Single ¶
type Single struct {
Value interface{}
}
Single can be used to signal to any ResponseEmitter that only one value will be emitted. This is important e.g. for the http.ResponseEmitter so it can set the HTTP headers appropriately.
type StdinArguments ¶
type StdinArguments interface {
io.ReadCloser
// Scan reads in the next argument and returns true if there is an
// argument to read.
Scan() bool
// Argument returns the next argument.
Argument() string
// Err returns any errors encountered when reading in arguments.
Err() error
}
StdinArguments is used to iterate through arguments piped through stdin.
It closely mimics the bufio.Scanner interface but also implements the ReadCloser interface.
type TextEncoder ¶
type TextEncoder struct {
// contains filtered or unexported fields
}
func (TextEncoder) Encode ¶
func (e TextEncoder) Encode(v interface{}) error
Source Files
Directories