k8shell

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 23, 2026 License: AGPL-3.0 Imports: 12 Imported by: 0

README

k8shell-go

Go SDK for the k8shell API.

Installation

go get github.com/k8shell-io/k8shell-go

Usage

import "github.com/k8shell-io/k8shell-go"

c := k8shell.New("https://k8shell.example.com", token)

// List workspaces
workspaces, err := c.ListWorkspaces(ctx, "", false)

// Create a workspace from a blueprint
resp, err := c.CreateWorkspace(ctx, k8shell.WorkspaceCreateRequest{
    Username:  "alice",
    Blueprint: "go-dev",
})

// Stream creation progress (SSE)
stream, err := c.MonitorWorkspace(ctx, resp.MonitorURL)
defer stream.Close()

Client options

Option Description
WithDebug() Log request/response headers to stderr
WithDebugWriter(w) Log to a custom io.Writer (implies WithDebug)
WithInsecure() Skip TLS certificate verification

Browser login flow

Use NewAnonymous to acquire a PAT without a pre-existing token:

anon := k8shell.NewAnonymous("https://k8shell.example.com")

providers, err := anon.ListProviders(ctx)
// redirect user to the provider login URL, then poll:
for {
    token, err := anon.PollToken(ctx, oauthState)
    if err != nil { /* handle */ }
    if token != nil {
        c := k8shell.New("https://k8shell.example.com", token.Token)
        break
    }
    time.Sleep(2 * time.Second)
}

Error handling

Non-2xx responses return *APIError with the HTTP status code and an optional message from the response body:

var apiErr *k8shell.APIError
if errors.As(err, &apiErr) {
    fmt.Println(apiErr.StatusCode, apiErr.Message)
}

API reference

Method Description
ListProviders(ctx) Identity providers that support browser login
PollToken(ctx, state) Poll for a PAT after browser login
GetProfile(ctx) Authenticated user's profile
ListUsers(ctx) All users visible to the token
ListSessions(ctx, username, all) SSH sessions for a user
ListWorkspaces(ctx, username, all) Workspaces visible to the token
CreateWorkspace(ctx, req) Submit a workspace creation request
GetWorkspace(ctx, name) Workspace details by name
DeleteWorkspace(ctx, name, deleteData) Stop (and optionally delete) a workspace
MonitorWorkspace(ctx, monitorURL) Open SSE stream for a workspace job

License

AGPL-3.0-only

Documentation

Overview

Package k8shell provides a Go client for the k8shell API.

Create an authenticated client with a server URL and personal access token:

c := k8shell.New("https://k8shell.example.com", token)
ws, err := c.ListWorkspaces(ctx, "", false)

For browser-based login, use NewAnonymous to perform the OAuth web flow without a token, then construct an authenticated client from the returned PAT.

Index

Constants

View Source
const CapabilityOnboardUserWebFlow = "OnboardUserWebFlow"

CapabilityOnboardUserWebFlow is the provider capability required for browser-based login.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError

type APIError struct {
	StatusCode int
	Message    string
	// contains filtered or unexported fields
}

APIError is returned for non-2xx responses and carries the HTTP status code and an optional message from the response body.

func (*APIError) Error

func (e *APIError) Error() string

func (*APIError) Unwrap added in v0.1.0

func (e *APIError) Unwrap() error

Unwrap returns the underlying cause, enabling errors.Is/errors.As traversal.

type Client

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

Client is an authenticated HTTP client for the k8shell API.

func New

func New(server, token string, opts ...Option) *Client

New creates an authenticated Client for the given server URL and PAT token.

func NewAnonymous

func NewAnonymous(server string, opts ...Option) *Client

NewAnonymous creates an unauthenticated Client, useful for the browser login flow.

func (*Client) CreateWorkspace

func (c *Client) CreateWorkspace(ctx context.Context, req WorkspaceCreateRequest) (*WorkspaceCreateResponse, error)

CreateWorkspace submits a workspace creation request and returns the 202 response containing the workspace name, job ID, and SSE monitor URL.

func (*Client) DeleteWorkspace

func (c *Client) DeleteWorkspace(ctx context.Context, name string, deleteData bool) error

DeleteWorkspace shuts down the named workspace. When deleteData is true, workspace storage is permanently deleted.

func (*Client) GetProfile

func (c *Client) GetProfile(ctx context.Context) (*models.User, error)

GetProfile returns the profile of the authenticated user.

func (*Client) GetWorkspace

func (c *Client) GetWorkspace(ctx context.Context, name string) (*models.WorkspaceDetails, error)

GetWorkspace returns the details of the named workspace.

func (*Client) ListProviders

func (c *Client) ListProviders(ctx context.Context) ([]string, error)

ListProviders returns the names of identity providers that support the OnboardUserWebFlow capability (i.e. browser-based login).

func (*Client) ListSessions

func (c *Client) ListSessions(ctx context.Context, username string, all bool) ([]models.SSHSession, error)

ListSessions returns SSH sessions for the given username, or for the authenticated user when username is empty. When all is true, all sessions (including ended ones) are returned.

func (*Client) ListUsers

func (c *Client) ListUsers(ctx context.Context) ([]models.User, error)

ListUsers returns all users visible to the authenticated token.

func (*Client) ListWorkspaces

func (c *Client) ListWorkspaces(ctx context.Context, username string, all bool) ([]models.WorkspaceDetails, error)

ListWorkspaces returns workspaces visible to the authenticated token. When username is non-empty the results are filtered by owner. When all is true, workspaces in all states are included.

func (*Client) MonitorWorkspace

func (c *Client) MonitorWorkspace(ctx context.Context, monitorURL string) (io.ReadCloser, error)

MonitorWorkspace opens an SSE stream at monitorURL and returns the response body for the caller to consume. monitorURL may be a full URL or a path relative to the client's server. The caller is responsible for closing the returned ReadCloser.

func (*Client) PollToken

func (c *Client) PollToken(ctx context.Context, state string) (*models.UserToken, error)

PollToken checks whether the PAT for the given OAuth state is ready. Returns (nil, nil) when the login is still pending (202 Accepted), or (token, nil) once the token is issued (200 OK).

type Option

type Option func(*Client)

Option configures a Client.

func WithDebug

func WithDebug() Option

WithDebug enables request/response header logging.

func WithDebugWriter added in v0.1.0

func WithDebugWriter(w io.Writer) Option

WithDebugWriter sets the writer used for debug output and implies WithDebug.

func WithInsecure

func WithInsecure() Option

WithInsecure disables TLS certificate verification.

type WorkspaceCreateRequest

type WorkspaceCreateRequest struct {
	Username  string `json:"username"`
	Blueprint string `json:"blueprint,omitempty"`
	RepoOwner string `json:"repoOwner,omitempty"`
	RepoName  string `json:"repoName,omitempty"`
	RepoRef   string `json:"repoRef,omitempty"`
}

WorkspaceCreateRequest is the payload for creating a workspace. Either Blueprint or (RepoOwner + RepoName) must be set.

type WorkspaceCreateResponse

type WorkspaceCreateResponse struct {
	Workspace  string `json:"workspace"`
	JobID      string `json:"jobId"`
	MonitorURL string `json:"monitorUrl"`
}

WorkspaceCreateResponse is the 202 Accepted body returned by CreateWorkspace.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL