task

Documentation

Overview

Package task is an RPC library to execute shell command with ed25519 authentication.

Index

• func FullFillRequestWithCallback(ctx *CommandServiceContext, request *Request, done DoneFunction)
• func HashCommand(command *Command) []byte
• type Command
• type CommandInterpreter
  • func CreateShellCommandInterpreter(BaseCommand string) CommandInterpreter
• type CommandServiceContext
  • func CreateServerContext(ACL []string, MaxInflights int, Interpreter CommandInterpreter) CommandServiceContext
  • func (ctx *CommandServiceContext) Execute(command *Command) ([]byte, error)
• type DoneFunction
• type Request
  • func (request *Request) CheckPermission(ACL map[string]bool) error
  • func (request *Request) Decode(reader io.Reader) error
  • func (request *Request) Encode(writer io.Writer) error
  • func (request *Request) Sign(priv ed25519.PrivateKey) error
• type Response
  • func FullFillRequest(ctx *CommandServiceContext, request *Request) *Response
  • func (response *Response) Decode(reader io.Reader) error
  • func (response *Response) Encode(writer io.Writer) error
  • func (response *Response) Error() error

Functions

func FullFillRequestWithCallback

func FullFillRequestWithCallback(ctx *CommandServiceContext, request *Request, done DoneFunction)

FullFillRequestWithCallback is a non-blocking call to take a request to perform permission check and fulfill the request. Its parallelism can be controlled by APPServerContext option `MaxInFlights`.

func HashCommand

func HashCommand(command *Command) []byte

HashCommand calculates a unique string for message authentication.

Types

type Command

type Command struct {
	// Command of the task to be executed.
	Command []string `json:"command"`
	// For security purpose, client will drop the request if the deadline is passed.
	Deadline time.Time `json:"expires"`

	// If specified, once the command is done.
	// `TaskResult` will be sent to `ReceiverChannel` with given `TaskID`.
	TaskID string `json:"taskID"`
}

Command is a structure to store a command to be executed.

type CommandInterpreter

type CommandInterpreter func(context.Context, Command) ([]byte, error)

CommandInterpreter contains the implementation of a command interpreter.

func CreateShellCommandInterpreter

func CreateShellCommandInterpreter(BaseCommand string) CommandInterpreter

CreateShellCommandInterpreter returns an interpreter that will use the `TaskName` template, and substitute all params.

type CommandServiceContext

type CommandServiceContext struct {
	// Permission check ACL.
	ACL map[string]bool
	// contains filtered or unexported fields
}

CommandServiceContext stores the context of a task. MUST be initialized with CreateAPPServerContext function.

func CreateServerContext

func CreateServerContext(ACL []string, MaxInflights int, Interpreter CommandInterpreter) CommandServiceContext

CreateServerContext initializes a TaskContext object.

func (*CommandServiceContext) Execute

func (ctx *CommandServiceContext) Execute(command *Command) ([]byte, error)

Execute is a blocking call that executes the command wrapped in `TaskCommand`. Returns OK if succeed, otherwise an error message.

type DoneFunction

type DoneFunction func(*Response)

DoneFunction is a callback with TaskResponse as its parameter.

type Request

type Request struct {
	// Actual command to be executed.
	Command Command `json:"command"`
	// (ed25519) The public key of the sender.
	SenderPubKey string `json:"sender"`
	// (ed25519) The signature of the data
	SenderSign string `json:"sign"`
}

Request is a structure to store a task request.

func (*Request) CheckPermission

func (request *Request) CheckPermission(ACL map[string]bool) error

CheckPermission will enforce permission policy in `ACL` and returns any permission error encountered.

• If `ACL` empty, permission check will pass.
• If `ACL` is not empty, this function will check:
• 1. request has a sender, and sender is in the ACL.
• 2. request has a timestamp, and it is not expired.
• 3. request has a valid ed25519 signature of `command` field.

func (*Request) Decode

func (request *Request) Decode(reader io.Reader) error

Decode hides the unmarshal detail to other layer.

func (*Request) Encode

func (request *Request) Encode(writer io.Writer) error

Encode hides the marshal detail to other layer.

func (*Request) Sign

func (request *Request) Sign(priv ed25519.PrivateKey) error

Sign will populate `SenderPubKey` and `SenderSign` fields. Any modifications on `Command` and `Metadata` fields require another Sign call.

type Response

type Response struct {
	// Task Identifier, will be the same to the request.
	TaskID string `json:"taskID"`
	// The timestmap of the command to be done.
	Finish time.Time `json:"finish"`
	// Result of the task.
	Data []byte `json:"data"`
	// IsError indicates if this response is in error state.
	IsError bool `json:"is_error"`
	// ErrorMessage represents an error state if not nil.
	ErrorMessage string `json:"error"`
}

Response is a structure to store a command execution result.

func FullFillRequest

func FullFillRequest(ctx *CommandServiceContext, request *Request) *Response

FullFillRequest is a blocking call to take a request to perform permission check and fulfill the request.

func (*Response) Decode

func (response *Response) Decode(reader io.Reader) error

Decode hides the unmarshal detail to other layer.

func (*Response) Encode

func (response *Response) Encode(writer io.Writer) error

Encode hides the marshal detail to other layer.

func (*Response) Error

func (response *Response) Error() error

Error returns an error state parsed from Response, if it is succeed, returns nil.