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)

Source Files

View all Source files

Directories

Path Synopsis
examples
adder
adder/local
adder/remote/client
adder/remote/server

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.