api

Documentation

Overview

Package api contains definitions useful for accessing the HTTP and websocket APIs. See https://github.com/gate-computer/gate/blob/main/doc/web-api.md for general documentation.

This package avoids dependencies to the server implementation.

Index

• Constants
• Variables
• func AuthorizationBearerEd25519(privateKey ed25519.PrivateKey, tokenHeader []byte, claims *Claims) (string, error)
• func AuthorizationBearerLocal(claims *Claims) (string, error)
• func EncodeKnownModule(hashSum []byte) string
• func ErrorStatus(err error) int
• type Call
• type CallConnection
• type Claims
• type ConnectionStatus
• type Features
• type IO
• type IOConnection
• type InstanceInfo
• type InstanceUpdate
• type Instances
• type ModuleInfo
• type Modules
• 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-0/"              // The API.
	PathModule        = Path + "module"         // Base of relative module URIs.
	PathModuleSources = Path + "module/"        // Module source directory.
	PathKnownModules  = Path + "module/sha256/" // Known module directory.
	PathInstances     = Path + "instance/"      // Instance ids.
)

Request URL paths.

const (
	ParamFeature     = "feature"
	ParamAction      = "action"
	ParamModuleTag   = "module.tag"   // For pin or snapshot action.
	ParamFunction    = "function"     // For call, launch or resume action.
	ParamInstance    = "instance"     // For call or launch action.
	ParamInstanceTag = "instance.tag" // For call, launch or update action.
	ParamLog         = "log"          // For call, launch or resume action.
)

Query parameters.

const (
	FeatureAll   = "*"
	FeatureScope = "scope"
)

Queryable features.

const (
	ActionPin    = "pin"    // Put (known), post (source) or websocket (call/launch).
	ActionUnpin  = "unpin"  // Post (known).
	ActionCall   = "call"   // Put (known), post (any) or websocket (any).
	ActionLaunch = "launch" // Put (known), post (any).
)

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

const (
	ActionIO       = "io"       // Post or websocket.
	ActionWait     = "wait"     // Post.
	ActionKill     = "kill"     // Post.
	ActionSuspend  = "suspend"  // Post.
	ActionResume   = "resume"   // Post.
	ActionSnapshot = "snapshot" // Post.
	ActionDelete   = "delete"   // Post.
	ActionUpdate   = "update"   // Post.
	ActionDebug    = "debug"    // Post.  See the debug package.
)

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 (
	HeaderAccept        = "Accept"
	HeaderAuthorization = "Authorization" // "Bearer" JSON Web Token.
	HeaderOrigin        = "Origin"
	HeaderTE            = "Te" // Accepted transfer encodings.
)

HTTP request headers.

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

HTTP request or response headers.

const (
	HeaderLocation = "Location"      // Absolute path to known module.
	HeaderInstance = "Gate-Instance" // UUID.
)

HTTP response headers.

const (
	SignAlgEdDSA = "EdDSA"
	SignAlgNone  = "none"
)

The supported signature algorithms.

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 update and debug content type.

const ContentTypeWebAssembly = "application/wasm"

The supported module content type.

const (
	HeaderStatus = "Gate-Status" // Status of instance as JSON.
)

HTTP response headers or trailers.

const KeyCurveEd25519 = "Ed25519"

The supported elliptic curve.

const KeyTypeOctetKeyPair = "OKP"

The supported key type.

const KnownModuleHash = crypto.SHA256

KnownModuleHash algorithm for converting module content to its raw id within the KnownModuleSource. The id string can be formed by encoding the hash digest with EncodeKnownModule.

const KnownModuleSource = "sha256"

KnownModuleSource is the name of the built-in directory of modules the content of which are known to the server and/or the client.

const TETrailers = "trailers"

An accepted transfer encoding.

Variables

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

FunctionRegexp matches a valid function name.

Functions

func AuthorizationBearerEd25519

func AuthorizationBearerEd25519(privateKey ed25519.PrivateKey, tokenHeader []byte, claims *Claims) (string, error)

AuthorizationBearerEd25519 creates a signed JWT token (JWS). TokenHeader must have been encoded beforehand.

func AuthorizationBearerLocal

func AuthorizationBearerLocal(claims *Claims) (string, error)

AuthorizationBearerLocal creates an unsecured JWT token.

func EncodeKnownModule

func EncodeKnownModule(hashSum []byte) string

EncodeKnownModule converts module content hash digest to its id within KnownModuleSource. The input can be obtained using KnownModuleHash.

func ErrorStatus

func ErrorStatus(err error) int

ErrorStatus returns HTTP response status code representing an error.

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 path to known module.
	Instance string `json:"instance,omitempty"` // UUID.
}

Reply to Call message.

type Claims

type Claims struct {
	Exp   int64    `json:"exp,omitempty"`   // 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.
	Input  bool   `json:"input,omitempty"`
}

Secondary text message on successful ActionCall or ActionIO websocket connection. There may be multiple, and binary messages may be interleaved between them. The final status is reported just before normal connection closure.

The input flag is a hint that the program is expecting to receive data on this connection. The amount and pace is unspecified; the flag might not repeat even if the program continues to receive.

type Features

type Features struct {
	Scope []string `json:"scope,omitempty"`
}

Features supported by the server.

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 InstanceInfo

type InstanceInfo struct {
	Instance  string   `json:"instance"`
	Module    string   `json:"module"`
	Status    Status   `json:"status"`
	Transient bool     `json:"transient,omitempty"`
	Debugging bool     `json:"debugging,omitempty"`
	Tags      []string `json:"tags,omitempty"`
}

InstanceInfo 'r' mation.

type InstanceUpdate

type InstanceUpdate struct {
	Persist bool     `json:"transient,omitempty"`
	Tags    []string `json:"tags,omitempty"`
}

Instance update request content.

type Instances

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

Response to a PathInstances request.

type ModuleInfo

type ModuleInfo struct {
	ID   string   `json:"id"`
	Tags []string `json:"tags,omitempty"`
}

ModuleInfo 'r' mation.

type Modules

type Modules struct {
	Modules []ModuleInfo `json:"modules"`
}

Response to PathKnownModules 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.