se2

README

se2-go

Go client library for the Suborbital Extension Engine (SE2)

Usage

In a Go project, run

go get github.com/suborbital/se2-go@latest

Every operation with SE2 is done with a se2.Client. Here's a simple example that fetches exisiting plugins for a user and namespace.

package main

import (
    "log"

    "github.com/suborbital/se2-go"
)

func main() {
    token, exists := os.LookupEnv("SE2_ENV_TOKEN")
    if !exists {
        log.Fatal("could not find token")
    }

    client, err := se2.NewClient(se2.LocalConfig(), token)
    if err != nil {
        log.Fatal(err)
    }

    // get a list of plugins
    plugins, err := client.UserPlugins("userID", "namespace")
    if err != nil {
        log.Fatal(err)
    }

    for _, r := range plugins {
        log.Println(r.FQMN)
    }
}

See examples folder for more.

Documentation

Index

• type BuildResult
• type Client
  • func NewClient(config *Config, envToken string) (*Client, error)
  • func NewLocalClient(envToken string) (*Client, error)
  • func (c *Client) BuildPlugin(plugin *Plugin, template string, source io.Reader) (*BuildResult, error)
  • func (c *Client) BuildPluginString(plugin *Plugin, template, source string) (*BuildResult, error)
  • func (c *Client) BuilderFeatures() (*FeaturesResponse, error)
  • func (c *Client) BuilderHealth() (bool, error)
  • func (c *Client) BuilderTemplate(plugin *Plugin, template string) (*EditorStateResponse, error)
  • func (c *Client) EditorToken(plugin *Plugin) (string, error)
  • func (c *Client) Exec(plugin *Plugin, body io.Reader) ([]byte, string, error)
  • func (c *Client) ExecRef(ref string, body io.Reader) ([]byte, string, error)
  • func (c *Client) ExecRefString(ref string, body string) ([]byte, string, error)
  • func (c *Client) ExecString(plugin *Plugin, body string) ([]byte, string, error)
  • func (c *Client) ExecutionResult(uuid string) ([]byte, error)
  • func (c *Client) ExecutionResultMetadata(uuid string) (*ExecMetadata, error)
  • func (c *Client) ExecutionResultsMetadata(plugin *Plugin) ([]ExecMetadata, error)
  • func (c *Client) GetDraft(plugin *Plugin) (*EditorStateResponse, error)
  • func (c *Client) PromoteDraft(plugin *Plugin) (*PromoteDraftResponse, error)
  • func (c *Client) UserPlugins(identifier string, namespace string) ([]*tenant.Module, error)
• type Config
  • func CustomConfig(execHost string, adminHost string, builderHost string) (*Config, error)
  • func DefaultConfig(builderHost string) (*Config, error)
  • func LocalConfig() *Config
• type EditorStateResponse
• type ExecError
• type ExecMetadata
• type ExecResponse
• type FeatureLanguage
• type FeaturesResponse
• type Plugin
  • func NewPlugin(environment, tenant, namespace, name string) *Plugin
  • func (m *Plugin) URI() string
• type PromoteDraftResponse
• type TestPayload
• type TokenResponse
• type UserPluginsResponse

Types

type BuildResult

type BuildResult struct {
	Succeeded bool   `json:"succeeded"`
	OutputLog string `json:"outputLog"`
}

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is used for interacting with the SE2 API

func NewClient

func NewClient(config *Config, envToken string) (*Client, error)

NewClient creates a Client with a Config

func NewLocalClient

func NewLocalClient(envToken string) (*Client, error)

NewLocalClient quickly sets up a Client with a LocalConfig. Useful for testing.

func (*Client) BuildPlugin

func (c *Client) BuildPlugin(plugin *Plugin, template string, source io.Reader) (*BuildResult, error)

BuildPlugin triggers a remote build for the given plugin and source code. See also: Client.BuildPluginString()

Example

This plugin is useful for reading from a filesystem or from an http.Response.Body

plugin := se2.NewPlugin("com.suborbital", "acmeco", "default", "hello")
file, _ := os.Open("hello.rs")
result, err := client.BuildPlugin(plugin, file)

func (*Client) BuildPluginString

func (c *Client) BuildPluginString(plugin *Plugin, template, source string) (*BuildResult, error)

BuildPluginString triggers a remote build for the given plugin and source code. See also: Client.BuildPlugin()

func (*Client) BuilderFeatures

func (c *Client) BuilderFeatures() (*FeaturesResponse, error)

BuilderFeatures lists the features present on the builder, such as testing capabilities.

func (*Client) BuilderHealth

func (c *Client) BuilderHealth() (bool, error)

BuilderHealth is used to check that the builder is healthy and responding to requests.

func (*Client) BuilderTemplate

func (c *Client) BuilderTemplate(plugin *Plugin, template string) (*EditorStateResponse, error)

BuilderTemplate gets the plugin template for the provided plugin and template name.

func (*Client) EditorToken

func (c *Client) EditorToken(plugin *Plugin) (string, error)

EditorToken gets an editor token for the provided plugin. Note: this library manages editor tokens for you, so you most likely do not need to use this function.

func (*Client) Exec

func (c *Client) Exec(plugin *Plugin, body io.Reader) ([]byte, string, error)

Exec remotely executes the provided plugin using the body as input. See also: ExecString()

func (*Client) ExecRef

func (c *Client) ExecRef(ref string, body io.Reader) ([]byte, string, error)

ExecRef remotely executes the provided plugin using the body as input, by plugin reference. See also: ExecRefString()

func (*Client) ExecRefString

func (c *Client) ExecRefString(ref string, body string) ([]byte, string, error)

ExecRefString sets up a buffer with the provided string and calls ExecRef

func (*Client) ExecString

func (c *Client) ExecString(plugin *Plugin, body string) ([]byte, string, error)

ExecString sets up a buffer with the provided string and calls Exec

func (*Client) ExecutionResult

func (c *Client) ExecutionResult(uuid string) ([]byte, error)

ExecutionResult returns the result of the provided plugin execution.

func (*Client) ExecutionResultMetadata

func (c *Client) ExecutionResultMetadata(uuid string) (*ExecMetadata, error)

ExecutionResultMetadata returns metadata for the provided plugin execution.

func (*Client) ExecutionResultsMetadata

func (c *Client) ExecutionResultsMetadata(plugin *Plugin) ([]ExecMetadata, error)

ExecutionResultsMetadata returns metadata for the 5 most recent execution results for the provided plugin.

func (*Client) GetDraft

func (c *Client) GetDraft(plugin *Plugin) (*EditorStateResponse, error)

GetDraft gets the most recently build source code for the provided plugin. Must have the .FQFMURI field set.

func (*Client) PromoteDraft

func (c *Client) PromoteDraft(plugin *Plugin) (*PromoteDraftResponse, error)

PromoteDraft takes the most recent build of the provided plugin and deploys it so it can be run.

func (*Client) UserPlugins

func (c *Client) UserPlugins(identifier string, namespace string) ([]*tenant.Module, error)

UserPlugins gets a list of the deployed plugins for the given identifier and namespace.

type Config

type Config struct {
	// contains filtered or unexported fields
}

Config combines the common configuration options for the three Suborbital Extension Engine APIs (Administrative, Builder, and Execution)

func CustomConfig

func CustomConfig(execHost string, adminHost string, builderHost string) (*Config, error)

Custom Configuration

func DefaultConfig

func DefaultConfig(builderHost string) (*Config, error)

DefaultConfig takes the given host and creates a SE2 config with the K8S default ports. Everything except the scheme and hostname are considered. You need to provide your builder host domain.

func LocalConfig

func LocalConfig() *Config

LocalConfig generates a Configuration for SE2 running in docker-compose

type EditorStateResponse

type EditorStateResponse struct {
	Lang     string        `json:"lang"`
	Contents string        `json:"contents"`
	Tests    []TestPayload `json:"tests"`
}

EditorStateResponse is a response to requests to get editorState

type ExecError

type ExecError struct {
	Code    int    `json:"code"`
	Message string `json:"string"`
}

type ExecMetadata

type ExecMetadata struct {
	UUID      string    `json:"uuid"`
	Timestamp time.Time `json:"timestamp"`
	Success   bool      `json:"success"`
	Error     ExecError `json:"error"`
}

type ExecResponse

type ExecResponse struct {
	Response []byte
	UUID     string
}

type FeatureLanguage

type FeatureLanguage struct {
	ID     string `json:"identifier"`
	Short  string `json:"short"`
	Pretty string `json:"pretty"`
}

type FeaturesResponse

type FeaturesResponse struct {
	Features  []string          `json:"features"`
	Langauges []FeatureLanguage `json:"languages"`
}

type Plugin

type Plugin struct {
	Environment string
	Tenant      string
	Namespace   string
	Name        string
}

func NewPlugin

func NewPlugin(environment, tenant, namespace, name string) *Plugin

NewPlugin instantiates a local v1.0.0 plugin that can be used for various calls with se2.Client. Note: this constructor alone does not perform any actions on a remote SE2 instance.

func (*Plugin) URI

func (m *Plugin) URI() string

type PromoteDraftResponse

type PromoteDraftResponse struct {
	Version string `json:"version"`
}

type TestPayload

type TestPayload struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Payload     string `json:"payload"`
}

TestPayload is a single test for a plugin

type TokenResponse

type TokenResponse struct {
	Token string `json:"token"`
}

type UserPluginsResponse

type UserPluginsResponse struct {
	Plugins []*tenant.Module `json:"modules"`
}