commands

Documentation

Index

• Constants
• Variables
• func ClientError(msg string) error
• type ChannelMarshaler
  • func (cr *ChannelMarshaler) Read(p []byte) (int, error)
• type Command
  • func (c *Command) Call(req Request) Response
  • func (c *Command) CheckArguments(req Request) 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) Subcommand(id string) *Command
  • func (c *Command) Walk(visitor CommandVisitor)
• type CommandVisitor
• type Context
  • func (c *Context) Close()
  • func (c *Context) Context() context.Context
  • func (c *Context) GetConfig() (*config.Config, error)
  • func (c *Context) GetNode() (*core.IpfsNode, error)
  • func (c *Context) LogRequest(req *cmds.Request) func()
  • func (c *Context) NodeWithoutConstructing() *core.IpfsNode
• type EncodingType
• type ErrorType
• type Function
• type Marshaler
• type MarshalerMap
• type ReqLog
  • func (rl *ReqLog) Add(req Request) *ReqLogEntry
  • func (rl *ReqLog) AddEntry(rle *ReqLogEntry)
  • func (rl *ReqLog) ClearInactive()
  • func (rl *ReqLog) Finish(rle *ReqLogEntry)
  • func (rl *ReqLog) Report() []*ReqLogEntry
  • func (rl *ReqLog) SetKeepTime(t time.Duration)
• type ReqLogEntry
  • func (r *ReqLogEntry) Copy() *ReqLogEntry
• type Request
  • func NewEmptyRequest() (Request, error)
  • func NewRequest(path []string, opts cmdkit.OptMap, args []string, file files.File, ...) (Request, error)
• type Response
  • func NewResponse(req Request) Response

Constants

const (
	JSON     = "json"
	XML      = "xml"
	Protobuf = "protobuf"
	Text     = "text"
)

Supported EncodingType constants.

Variables

var ErrIncorrectType = errors.New("The command returned a value with a different type than expected")

var ErrNoFormatter = ClientError("This command cannot be formatted to plain text")

var ErrNotCallable = ClientError("This command can't be called directly. Try one of its subcommands.")

ErrNotCallable signals a command that cannot be called.

Functions

func ClientError

func ClientError(msg string) error

Types

type ChannelMarshaler

type ChannelMarshaler struct {
	Channel   <-chan interface{}
	Marshaler func(interface{}) (io.Reader, error)
	Res       Response
	// contains filtered or unexported fields
}

func (*ChannelMarshaler) Read

func (cr *ChannelMarshaler) Read(p []byte) (int, error)

type Command

type Command struct {
	Options   []cmdkit.Option
	Arguments []cmdkit.Argument
	PreRun    func(req Request) 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    Function
	Marshalers map[EncodingType]Marshaler
	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) Response

Call invokes the command for the given Request

func (*Command) CheckArguments

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

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) Subcommand

func (c *Command) Subcommand(id string) *Command

Subcommand returns the subcommand with the given id

func (*Command) Walk

func (c *Command) Walk(visitor CommandVisitor)

Walks tree of all subcommands (including this one)

type CommandVisitor

type CommandVisitor func(*Command)

type Context

type Context struct {
	Online     bool
	ConfigRoot string
	ReqLog     *ReqLog

	LoadConfig func(path string) (*config.Config, error)

	ConstructNode func() (*core.IpfsNode, error)
	// contains filtered or unexported fields
}

func (*Context) Close

func (c *Context) Close()

Close cleans up the application state.

func (*Context) Context

func (c *Context) Context() context.Context

Context returns the node's context.

func (*Context) GetConfig

func (c *Context) GetConfig() (*config.Config, error)

GetConfig returns the config of the current Command exection context. It may load it with the providied function.

func (*Context) GetNode

func (c *Context) GetNode() (*core.IpfsNode, error)

GetNode returns the node of the current Command exection context. It may construct it with the provided function.

func (*Context) LogRequest

func (c *Context) LogRequest(req *cmds.Request) func()

LogRequest adds the passed request to the request log and returns a function that should be called when the request lifetime is over.

func (*Context) NodeWithoutConstructing

func (c *Context) NodeWithoutConstructing() *core.IpfsNode

NodeWithoutConstructing returns the underlying node variable so that clients may close it.

type EncodingType

type EncodingType string

EncodingType defines a supported encoding

type ErrorType

type ErrorType uint

ErrorType signfies a category of errors

type Function

type Function func(Request, Response)

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

type Marshaler

type Marshaler func(Response) (io.Reader, error)

Marshaler is a function that takes in a Response, and returns an io.Reader (or an error on failure)

type MarshalerMap

type MarshalerMap map[EncodingType]Marshaler

MarshalerMap is a map of Marshaler functions, keyed by EncodingType (or an error on failure)

type ReqLog

type ReqLog struct {
	Requests []*ReqLogEntry
	// contains filtered or unexported fields
}

ReqLog is a log of requests

func (*ReqLog) Add

func (rl *ReqLog) Add(req Request) *ReqLogEntry

Add creates a ReqLogEntry from a request and adds it to the log

func (*ReqLog) AddEntry

func (rl *ReqLog) AddEntry(rle *ReqLogEntry)

AddEntry adds an entry to the log

func (*ReqLog) ClearInactive

func (rl *ReqLog) ClearInactive()

ClearInactive removes stale entries

func (*ReqLog) Finish

func (rl *ReqLog) Finish(rle *ReqLogEntry)

Finish marks an entry in the log as finished

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)

SetKeepTime sets a duration after which an entry will be considered inactive

type ReqLogEntry

type ReqLogEntry struct {
	StartTime time.Time
	EndTime   time.Time
	Active    bool
	Command   string
	Options   map[string]interface{}
	Args      []string
	ID        int
	// contains filtered or unexported fields
}

ReqLogEntry is an entry in the request log

func (*ReqLogEntry) Copy

func (r *ReqLogEntry) Copy() *ReqLogEntry

Copy returns a copy of the ReqLogEntry

type Request

type Request interface {
	Path() []string
	Option(name string) *cmdkit.OptionValue
	Options() cmdkit.OptMap
	SetOption(name string, val interface{})
	SetOptions(opts cmdkit.OptMap) error
	Arguments() []string
	StringArguments() []string
	SetArguments([]string)
	Files() files.File
	SetFiles(files.File)
	Context() context.Context
	InvocContext() *Context
	SetInvocContext(Context)
	Command() *Command
	Values() map[string]interface{}
	Stdin() io.Reader
	VarArgs(func(string) error) error

	ConvertOptions() error
}

Request represents a call to a command from a consumer

func NewEmptyRequest

func NewEmptyRequest() (Request, error)

NewEmptyRequest initializes an empty request

func NewRequest

func NewRequest(path []string, opts cmdkit.OptMap, args []string, file files.File, cmd *Command, optDefs map[string]cmdkit.Option) (Request, error)

NewRequest returns a request initialized with given arguments An non-nil error will be returned if the provided option values are invalid

type Response

type Response interface {
	Request() Request

	// Set/Return the response Error
	SetError(err error, code cmdkit.ErrorType)
	Error() *cmdkit.Error

	// Sets/Returns the response value
	SetOutput(interface{})
	Output() interface{}

	// Sets/Returns the length of the output
	SetLength(uint64)
	Length() uint64

	// underlying http connections need to be cleaned up, this is for that
	Close() error
	SetCloser(io.Closer)

	// Marshal marshals out the response into a buffer. It uses the EncodingType
	// on the Request to chose a Marshaler (Codec).
	Marshal() (io.Reader, error)

	// Gets a io.Reader that reads the marshalled output
	Reader() (io.Reader, error)

	// Gets Stdout and Stderr, for writing to console without using SetOutput
	Stdout() io.Writer
	Stderr() io.Writer
}

Response is the result of a command request. Handlers write to the response, setting Error or Value. Response is returned to the client.

func NewResponse

func NewResponse(req Request) Response

NewResponse returns a response to match given Request