cmds

package module
v1.0.20 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 9, 2018 License: MIT Imports: 14 Imported by: 0

README

go-ipfs-cmds

standard-readme compliant

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

View Source
const (
	// General purpose
	Undefined = ""

	// EncodingTypes
	JSON        = "json"
	XML         = "xml"
	Protobuf    = "protobuf"
	Text        = "text"
	TextNewline = "textnl"

	// PostRunTypes
	CLI = "cli"
)

Supported EncodingType constants.

View Source
const (
	EncShort     = "enc"
	EncLong      = "encoding"
	RecShort     = "r"
	RecLong      = "recursive"
	ChanOpt      = "stream-channels"
	TimeoutOpt   = "timeout"
	OptShortHelp = "h"
	OptLongHelp  = "help"
)

Flag names

View Source
const DefaultOutputEncoding = JSON

Variables

View Source
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)
	},
}
View Source
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"} }
	},
}
View Source
var ErrIncorrectType = errors.New("The command returned a value with a different type than expected")
View Source
var ErrNoFormatter = ClientError("This command cannot be formatted to plain text")
View Source
var ErrNotCallable = ClientError("This command can't be called directly. Try one of its subcommands.")

ErrNotCallable signals a command that cannot be called.

View Source
var (
	ErrRcvdError = fmt.Errorf("received command error")
)
View Source
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

View Source
var OptionRecursivePath = cmdkit.BoolOption(RecLong, RecShort, "Add directory paths recursively").WithDefault(false)
View Source
var OptionStreamChannels = cmdkit.BoolOption(ChanOpt, "Stream channel output")
View Source
var OptionTimeout = cmdkit.StringOption(TimeoutOpt, "set a global timeout on the command")

Functions

func ClientError

func ClientError(msg string) error

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 EmitOnce added in v0.4.7

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 HandleError added in v0.4.4

func HandleError(err error, res Response, re ResponseEmitter) bool

HandleError handles the error from cmds.Response.Next(), it returns true if Next() should be called again

func MakeEncoder

func MakeEncoder(f func(*Request, io.Writer, interface{}) error) func(*Request) func(io.Writer) Encoder

func MakeTypedEncoder added in v1.0.1

func MakeTypedEncoder(f interface{}) func(*Request) func(io.Writer) Encoder

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

func (c *Command) CheckArguments(req *Request) error

CheckArguments checks that we have all the required string arguments, loading any from stdin if necessary.

func (*Command) DebugValidate added in v1.0.9

func (c *Command) DebugValidate() map[string][]error

DebugValidate checks if the command tree is well-formed.

This operation is slow and should be called from tests only.

func (*Command) Get

func (c *Command) Get(path []string) (*Command, error)

Get resolves and returns the Command addressed by path

func (*Command) GetOptions

func (c *Command) GetOptions(path []string) (map[string]cmdkit.Option, error)

GetOptions returns the options in the given path of commands

func (*Command) ProcessHelp

func (c *Command) ProcessHelp()

func (*Command) Resolve

func (c *Command) Resolve(pth []string) ([]*Command, error)

Resolve returns the subcommands at the given path

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 EncoderFunc added in v0.3.0

type EncoderFunc func(req *Request) func(w io.Writer) Encoder

type EncoderMap added in v0.3.0

type EncoderMap map[EncodingType]EncoderFunc

type EncodingEmitter

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 added in v1.0.0

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 added in v1.0.0

type Executor interface {
	Execute(req *Request, re ResponseEmitter, env Environment) error
}

func NewExecutor added in v1.0.0

func NewExecutor(root *Command) Executor

type Flusher

type Flusher interface {
	Flush() error
}

type Function

type Function func(*Request, ResponseEmitter, Environment)

Function is the type of function that Commands use. It reads from the Request, and writes results to the ResponseEmitter.

type Head struct {
	Len uint64
	Err *cmdkit.Error
}

func (Head) Error

func (h Head) Error() *cmdkit.Error

func (Head) Length

func (h Head) Length() uint64
type Header interface {
	Head() Head
}

type MakeEnvironment added in v1.0.0

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 added in v1.0.0

type MakeExecutor func(*Request, interface{}) (Executor, error)

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 added in v0.4.12

type MaybeError struct {
	Value interface{} // needs to be a pointer
	Error cmdkit.Error
	// contains filtered or unexported fields
}

func (*MaybeError) Get added in v0.4.12

func (m *MaybeError) Get() interface{}

func (*MaybeError) UnmarshalJSON added in v0.4.12

func (m *MaybeError) UnmarshalJSON(data []byte) error

type PostRunMap

type PostRunMap map[PostRunType]func(*Request, ResponseEmitter) ResponseEmitter

PostRunMap is the map used in Command.PostRun.

type PostRunType added in v1.0.0

type PostRunType string

PostRunType defines which PostRunFunc should be used

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

func (rl *ReqLog) SetKeepTime(t time.Duration)

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 added in v1.0.0

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 added in v1.0.0

func (req *Request) FillDefaults() error

fillDefault fills in default values if option has not been set

func (*Request) ParseBodyArgs added in v1.0.0

func (req *Request) ParseBodyArgs() error

func (*Request) SetOption

func (req *Request) SetOption(name string, value interface{})

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.
	// The error can also be ErrRcvdError if an error has been emitted.
	// In this case the emitted error can be accessed using the Error() method.
	Next() (interface{}, error)
	RawNext() (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 {
	// closes http conn or channel
	io.Closer

	// SetLength sets the length of the output
	// err is an interface{} so we don't have to manually convert to error.
	SetLength(length uint64)

	// SetError sets the response error
	// err is an interface{} so we don't have to manually convert to error.
	SetError(err interface{}, code cmdkit.ErrorType)

	// 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

type Single added in v0.4.7

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.

func (Single) GoString added in v0.4.7

func (s Single) GoString() string

func (Single) String added in v0.4.7

func (s Single) String() string

type StdinArguments added in v1.0.11

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

type WriterResponseEmitter

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

func NewWriterResponseEmitter

func NewWriterResponseEmitter(w io.WriteCloser, req *Request, enc func(*Request) func(io.Writer) Encoder) *WriterResponseEmitter

func (*WriterResponseEmitter) Close

func (re *WriterResponseEmitter) Close() error

func (*WriterResponseEmitter) Emit

func (re *WriterResponseEmitter) Emit(v interface{}) error

func (*WriterResponseEmitter) Head

func (re *WriterResponseEmitter) Head() Head

func (*WriterResponseEmitter) SetEncoder added in v0.2.3

func (re *WriterResponseEmitter) SetEncoder(mkEnc func(io.Writer) Encoder)

func (*WriterResponseEmitter) SetError

func (re *WriterResponseEmitter) SetError(v interface{}, errType cmdkit.ErrorType)

func (*WriterResponseEmitter) SetLength

func (re *WriterResponseEmitter) SetLength(length uint64)

Directories

Path Synopsis
examples

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL