webapi

Documentation

Overview

Package webapi contains definitions useful for accessing the HTTP and websocket APIs. See https://github.com/tsavola/gate/blob/master/Web.md for general documentation.

Index

• Constants
• Variables
• type Call
• type CallConnection
• type Claims
• type ConnectionStatus
• type IO
• type IOConnection
• type InstanceStatus
• type Instances
• type ModuleRef
• type ModuleRefs
• type PublicKey
  • func PublicKeyEd25519(publicKey []byte) *PublicKey
• type Status
  • func (status Status) String() (s string)
• type TokenHeader
  • func TokenHeaderEdDSA(publicKey *PublicKey) *TokenHeader
  • func (header *TokenHeader) MustEncode() []byte

Constants

const (
	Path           = "/gate/"               // The API.
	PathModule     = "/gate/module"         // Base of relative module URIs.
	PathModules    = "/gate/module/"        // Module sources.
	PathModuleRefs = "/gate/module/sha384/" // Module reference ids.
	PathInstances  = "/gate/instance/"      // Instance ids.
)

Request URL paths.

const (
	ParamAction   = "action"
	ParamFunction = "function" // For call, launch or resume action.
	ParamInstance = "instance" // For call or launch action.
	ParamDebug    = "debug"    // For call, launch or resume action.
)

Query parameters.

const (
	ActionRef    = "ref"    // Put (reference), post (source) or websocket (call/launch).
	ActionUnref  = "unref"  // Post (reference).
	ActionCall   = "call"   // Put (reference), post (any) or websocket (any).
	ActionLaunch = "launch" // Put (reference), post (any).
)

Actions on modules. ActionRef can be combined with ActionCall or ActionLaunch in a single request (ParamAction appears twice in the URL).

const (
	ActionIO       = "io"       // Post or websocket.
	ActionStatus   = "status"   // Post.
	ActionWait     = "wait"     // Post.
	ActionKill     = "kill"     // Post.
	ActionSuspend  = "suspend"  // Post.
	ActionResume   = "resume"   // Post.
	ActionSnapshot = "snapshot" // Post.
	ActionDelete   = "delete"   // Post.
	ActionDebug    = "debug"    // Post.
)

Actions on instances. ActionWait can be combined with ActionKill or ActionSuspend in a single request (ParamAction appears twice in the URL). ActionSuspend can be combined with ActionLaunch on a module: the instance will be created in StateSuspended or StateHalted.

const (
	HeaderContentLength = "Content-Length"
	HeaderContentType   = "Content-Type"
)

HTTP request or response headers.

const (
	HeaderLocation = "Location"        // Absolute module ref path.
	HeaderInstance = "X-Gate-Instance" // UUID.
	HeaderStatus   = "X-Gate-Status"   // Status of instance as JSON.
)

HTTP response headers.

const (
	StateRunning    = "RUNNING"
	StateSuspended  = "SUSPENDED"
	StateHalted     = "HALTED"
	StateTerminated = "TERMINATED"
	StateKilled     = "KILLED"
)

Instance state enumeration.

const (
	CauseNormal = ""

	// Abnormal causes for StateSuspended:
	CauseCallStackExhausted = "CALL_STACK_EXHAUSTED"
	CauseABIDeficiency      = "ABI_DEFICIENCY"
	CauseBreakpoint         = "BREAKPOINT"

	// Abnormal causes for StateKilled:
	CauseUnreachable                   = "UNREACHABLE"
	CauseMemoryAccessOutOfBounds       = "MEMORY_ACCESS_OUT_OF_BOUNDS"
	CauseIndirectCallIndexOutOfBounds  = "INDIRECT_CALL_INDEX_OUT_OF_BOUNDS"
	CauseIndirectCallSignatureMismatch = "INDIRECT_CALL_SIGNATURE_MISMATCH"
	CauseIntegerDivideByZero           = "INTEGER_DIVIDE_BY_ZERO"
	CauseIntegerOverflow               = "INTEGER_OVERFLOW"
	CauseABIViolation                  = "ABI_VIOLATION"
	CauseInternal                      = "INTERNAL"
)

Instance state cause enumeration. Empty value means that the cause is a normal one (e.g. client action, successful completion).

The cause enumeration is open-ended: new values may appear in the future.

const AuthorizationTypeBearer = "Bearer"

The supported authorization type.

const ContentTypeJSON = "application/json"

The supported instance debug content type.

const ContentTypeWebAssembly = "application/wasm"

The supported module content type.

const (
	HeaderAuthorization = "Authorization" // "Bearer" JSON Web Token.
)

HTTP request headers.

const KeyCurveEd25519 = "Ed25519"

The supported elliptic curve.

const KeyTypeOctetKeyPair = "OKP"

The supported key type.

const ModuleRefHash crypto.Hash = serverapi.ModuleRefHash

Algorithm for converting module content to reference id. A reference id string can be formed by encoding a hash digest with base64.RawURLEncoding.

const ModuleRefSource = serverapi.ModuleRefSource

Name of the module reference source and associated content hash algorithm.

const SignAlgEdDSA = "EdDSA"

The supported signature algorithm.

Variables

var FunctionRegexp = regexp.MustCompile("^[A-Za-z0-9-._]{1,31}$")

FunctionRegexp matches a valid function name.

Types

type Call

type Call struct {
	Authorization string `json:"authorization,omitempty"`
	ContentType   string `json:"content_type,omitempty"`
	ContentLength int64  `json:"content_length,omitempty"`
}

ActionCall websocket request message.

type CallConnection

type CallConnection struct {
	Location string `json:"location,omitempty"` // Absolute module ref path.
	Instance string `json:"instance,omitempty"` // UUID.
}

Reply to Call message.

type Claims

type Claims struct {
	Exp   int64    `json:"exp"`             // Expiration time.
	Aud   []string `json:"aud,omitempty"`   // https://authority/api
	Nonce string   `json:"nonce,omitempty"` // Unique during expiration period.
	Scope string   `json:"scope,omitempty"`
}

JSON Web Token payload.

type ConnectionStatus

type ConnectionStatus struct {
	Status Status `json:"status"` // Instance status after disconnection.
}

Second and final text message on successful ActionCall or ActionIO websocket connection.

type IO

type IO struct {
	Authorization string `json:"authorization"`
}

ActionIO websocket request message.

type IOConnection

type IOConnection struct {
	Connected bool `json:"connected"`
}

Reply to IO message.

type InstanceStatus

type InstanceStatus struct {
	Instance  string `json:"instance"`
	Status    Status `json:"status"`
	Transient bool   `json:"transient,omitempty"`
	Debugging bool   `json:"debugging,omitempty"`
}

An item in an Instances response.

type Instances

type Instances struct {
	Instances []InstanceStatus `json:"instances"`
}

Response to a PathInstances request.

type ModuleRef

type ModuleRef = serverapi.ModuleRef

An item in a ModuleRefs response.

type ModuleRefs

type ModuleRefs = serverapi.ModuleRefs

Response to PathModuleRefs request.

type PublicKey

type PublicKey struct {
	Kty string `json:"kty"`           // Key type.
	Crv string `json:"crv,omitempty"` // Elliptic curve.
	X   string `json:"x,omitempty"`   // Base64url-encoded unpadded public key.
}

JSON Web Key.

func PublicKeyEd25519

func PublicKeyEd25519(publicKey []byte) *PublicKey

PublicKeyEd25519 creates a JWK for a JWT header.

type Status

type Status struct {
	State  string `json:"state,omitempty"`
	Cause  string `json:"cause,omitempty"`
	Result int    `json:"result,omitempty"` // Meaningful if StateHalted or StateTerminated.
	Error  string `json:"error,omitempty"`  // Optional details for abnormal causes.
}

Status response header.

func (Status) String

func (status Status) String() (s string)

type TokenHeader

type TokenHeader struct {
	Alg string     `json:"alg"`           // Signature algorithm.
	JWK *PublicKey `json:"jwk,omitempty"` // Public side of signing key.
}

JSON Web Token header.

func TokenHeaderEdDSA

func TokenHeaderEdDSA(publicKey *PublicKey) *TokenHeader

TokenHeaderEdDSA creates a JWT header.

func (*TokenHeader) MustEncode

func (header *TokenHeader) MustEncode() []byte

MustEncode to a JWT component.