extensionapi

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Aug 14, 2026 License: Apache-2.0 Imports: 43 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// EnvLogLevel is the environment variable used to setup
	// the log level used that should be used by the extension.
	// The options are:
	// - "debug"
	// - "info"
	// - "warning"
	// - "error"
	EnvLogLevel = "GOTUI_LOG_LEVEL"
)
View Source 
const LoggingTimestampFormat = "2006-01-02T15:04:05.000000Z07:00"

LoggingTimestampFormat is the format used

Variables

This section is empty.

Functions

func ServeWorkspaceExtension 

func ServeWorkspaceExtension(extension WorkspaceExtension, meta Metadata) error

ServeWorkspaceExtension serves the given workspace extension with the given developer and extension metadata. This function blocks until a signal is received for the extension to shutdown, in which case the returned error is nil, or another error occurs.

Types

type Config 

type Config struct {
	// Socket is the address used to establish a secure
	// communication channel with the host: a unix socket path
	// (optionally prefixed with unix://) or a tcp://host:port URI.
	Socket string `json:"socket"`
	// Token is the oauth2 token used to authenticate
	// and authorize requests against workspace resources.
	Token *oauth2.Token `json:"token"`
	// Certificate is the certificate used to secure the connections.
	Certificate []byte `json:"certificate"`
	// Config is the user's configuration for the running extension.
	Config  map[string]any `json:"config"`
	DataDir string         `json:"datadir"`
	// InstallDir is the root, pre-expanded on the workspace host, under
	// which the host provisions resources packaged alongside this
	// extension (e.g. <InstallDir>/bin/<tool>).
	InstallDir string `json:"installdir"`
}

Config is sent by the host to the extension over stdin. It contains the connection configuration needed to establish gRPC connections and access workspace resources.

type Metadata 

type Metadata struct {
	DeveloperID      string      `json:"developer_id"`
	DeveloperEmail   string      `json:"developer_email"`
	DeveloperKey     string      `json:"developer_key"`
	ExtensionID      string      `json:"id"`
	ExtensionName    string      `json:"name"`
	ExtensionVersion string      `json:"version"`
	Permissions      Permissions `json:"permissions"`
}

Metadata represents the developer and extension metadata sent by the extension over stdout to the extension host.

type Permission 

type Permission string

Permission represents a request to access a resource. 

const (
	// PermissionFileSystem requests access to manage
	// the files in a workspace.
	PermissionFileSystem Permission = "permfs"
	// PermissionExecute requests access to execute
	// and stop processes in a workspace.
	PermissionExecute Permission = "permexec"
	// PermissionTerminal requests access to manage a workspace's ptys.
	PermissionTerminal Permission = "permpty"
	// PermissionBrowserWindowManager requests access to a browser's window manager.
	PermissionBrowserWindowManager Permission = "permwm"
	// PermissionBrowserResourceOpener requests access to open new files.
	PermissionBrowserResourceOpener Permission = "permopen"
	// PermissionNotifications requests access to send messages to the UI.
	PermissionNotifications Permission = "permnoti"
	// PermissionInterrupt requests access to interrupt the event loop.
	// This is useful if your extension handler does async updates to its state, as
	// it enables interrupting the main event loop to redraw components.
	PermissionInterrupt Permission = "permint"
	// PermissionEditor requests access to the editor.
	PermissionEditor Permission = "permed"
	// PermissionCommands requests access to registering new commands.
	PermissionCommands Permission = "permcmd"
	// PermissionStorage requests access to persistent storage.
	PermissionStorage Permission = "permstore"
	// PermissionSyntaxTree requests access to AST-level search.
	PermissionSyntaxTree Permission = "permsyntax"
	// PermissionConfig requests access to read the loaded workspace configuration.
	PermissionConfig Permission = "permcfg"
	// PermissionLSP requests access to the Language Server Protocol.
	PermissionLSP Permission = "permlsp"
	// PermissionDebugger requests access to the debugger through the DAP protocol.
	PermissionDebugger Permission = "permdap"
	// PermissionLLM requests access to host LLM completion services.
	PermissionLLM Permission = "permllm"
)

func PermissionForResource added in v0.0.18 

func PermissionForResource(resource string) (Permission, bool)

PermissionForResource returns the Permission required to access the given gRPC method. The resource should be a full gRPC method name such as "/proto.DocumentStore/Get". It returns the matching Permission and true if found, or an empty Permission and false if the resource is unknown.

type Permissions 

type Permissions map[Permission]any

Permissions is a set of Permission.

func AllPermissions 

func AllPermissions() Permissions

AllPermissions returns a set of all the permissions.

func NewPermissions 

func NewPermissions(perms ...Permission) Permissions

NewPermissions builds a new set of Permission with the given permissions.

type Workspace 

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

Workspace abstracts resources associated with a Workspace.

func NewWorkspace 

func NewWorkspace(req Config, meta Metadata) (*Workspace, error)

NewWorkspace returns a new Workspace. Extensions should use ServeWorkspaceExtension, which performs the stdin/stdout exchange necessary to receive a valid Config.

func (*Workspace) Commands added in v0.0.49 

func (w *Workspace) Commands(
	ctx context.Context,
) textapi.CommandRegistry

Commands returns the workspace's command registry, which can be used to register commands and REPL commands.

func (*Workspace) Config 

func (w *Workspace) Config(ctx context.Context) config.Config

Config returns a copy of the workspace's global configuration.

func (*Workspace) DataDir 

func (w *Workspace) DataDir(ctx context.Context) string

DataDir returns the data directory to store data to re-use across sessions.

func (*Workspace) Debugger added in v0.0.24 

func (w *Workspace) Debugger(ctx context.Context) debugapi.Debugger

Debugger returns the workspace's Debugger client, which can be used to interact with DAP-compatible debuggers.

func (*Workspace) Editor 

func (w *Workspace) Editor(ctx context.Context) textapi.Editor

Editor returns the workspace's editor which can be used to monitor and edit files, move the cursor, add location lists with or without color attributes, and even set the default background and foreground of a resource.

func (*Workspace) Executor 

func (w *Workspace) Executor(ctx context.Context) workspaceapi.Executor

Executor returns the workspace's executor, which can be used to start and stop processes.

func (*Workspace) FileSystem 

func (w *Workspace) FileSystem(ctx context.Context) workspaceapi.FileSystem

FileSystem returns the workspace's file system, which can be used to directly manipulate raw files in the workspace. Extensions that want to simply open resources as tabs in a workspace should use ResourceOpener.

func (*Workspace) FindInstalledExecutable added in v0.0.106 

func (w *Workspace) FindInstalledExecutable(
	ctx context.Context, name string,
) (string, error)

FindInstalledExecutable resolves a runnable binary provisioned alongside this extension. It looks under <InstallDir>/bin/<name> — the canonical location for executables — and verifies that the path exists on the workspace host as a regular (non-directory) file. The returned path is suitable for use with the workspace Executor.

Resolution stats the path on the workspace host, which may be a remote (e.g. ssh://) round-trip. It returns an error wrapping os.ErrNotExist when the binary is absent or resolves to a directory; callers can test this with errors.Is(err, os.ErrNotExist). Any other error (transport, permission, ...) is returned as-is so callers can distinguish a genuine miss from a probe failure. It performs no shell or command -v fallback.

Unlike FindInstalledResource, which accepts an arbitrary relative path and accepts directories, FindInstalledExecutable always looks under bin/ and rejects directories.

func (*Workspace) FindInstalledResource added in v0.0.106 

func (w *Workspace) FindInstalledResource(
	ctx context.Context, relpath string,
) (string, error)

FindInstalledResource resolves an arbitrary payload artifact provisioned alongside this extension. It looks under <InstallDir>/<relpath> and verifies that the path exists on the workspace host, whether it is a file or a directory. Use it for non-executable resources such as data files, lib/…, pkg/…, sysroots, or templates.

Resolution stats the path on the workspace host, which may be a remote (e.g. ssh://) round-trip. It returns an error wrapping os.ErrNotExist when the path is absent (testable with errors.Is(err, os.ErrNotExist)); any other error (transport, permission, ...) is returned as-is so callers can distinguish a genuine miss from a probe failure.

Unlike FindInstalledExecutable, which is restricted to bin/ and files, FindInstalledResource accepts any relative path under the install root and accepts directories.

func (*Workspace) Interrupter 

func (w *Workspace) Interrupter(ctx context.Context) term.Interrupter

Interrupter returns the workspace's event loop interrupter, which can be used to request new draws when state changes asynchronously.

func (*Workspace) LLM added in v0.0.83 

func (w *Workspace) LLM(ctx context.Context) llmapi.Service

LLM returns the workspace's LLM client. The host routes calls to whichever provider serves the requested model. Extensions must have PermissionLLM to access it; without the permission, every call returns PermissionDenied at request time.

func (*Workspace) LSP added in v0.0.16 

func (w *Workspace) LSP(ctx context.Context) semanticapi.LSP

LSP returns the workspace's LSP client, which can be used to interact with language servers.

func (*Workspace) Notifications 

func (w *Workspace) Notifications(ctx context.Context) browserapi.Notifications

Notifications returns the workspace's notifications.

func (*Workspace) Parser added in v0.0.24 

func (w *Workspace) Parser(ctx context.Context) syntaxapi.Parser

Parser returns the workspace's syntax parser, which can be used to perform AST-level searches and parsing across workspace files.

func (*Workspace) RawConn 

func (w *Workspace) RawConn() grpc.ClientConnInterface

RawConn returns the underlying raw connection to the extension host. This method should generally not be used by extensions.

func (*Workspace) RegisterCommand 

func (w *Workspace) RegisterCommand(
	cmd textapi.CommandManual, h textapi.CommandHandler,
) error

RegisterCommand registers a command to be dispatched to the given CommandHandler. Registered commands appear in the command prompt. Use RegisterCommand for editing and live-programming actions that operate on the current file and need no persistent output, such as navigating to a symbol definition, toggling a fold, or reformatting a selection.

func (*Workspace) RegisterREPLCommand added in v0.0.49 

func (w *Workspace) RegisterREPLCommand(
	cmd textapi.CommandManual, h textapi.REPLHandler,
) error

RegisterREPLCommand registers a REPL command to be dispatched to the given REPLHandler. Registered commands appear in the IDE's shell. Use RegisterREPLCommand for configuration, monitoring and troubleshooting commands that produce inspectable output the user wants to review, such as a debugger, a log viewer, or a status dashboard.

func (*Workspace) ResourceOpener 

func (w *Workspace) ResourceOpener(ctx context.Context) browserapi.ResourceOpener

ResourceOpener returns the workspace's resource opener which allows clients to access resources in the workspace. Extensions that need more control over the underlying files can use FileSystem instead.

func (*Workspace) Storage 

func (w *Workspace) Storage(ctx context.Context) storageapi.Service

Storage returns the workspace's storage facility, which can be used to persist extension data across sessions.

func (*Workspace) Terminal 

func (w *Workspace) Terminal(ctx context.Context) workspaceapi.Terminal

Terminal returns the workspace's pty capability which can be used to implement a terminal.

func (*Workspace) WindowManager 

func (w *Workspace) WindowManager(ctx context.Context) browserapi.WindowManager

WindowManager returns the workspace's window manager, which can be used to create and manipulate the workspace's browser tabs, windows and bars.

type WorkspaceExtension 

type WorkspaceExtension interface {
	ExtendWorkspace(context.Context, *Workspace, config.Config) error
}

WorkspaceExtension abstracts ExtendWorkspace, which needs to be satisfied by extensions passed to ServeWorkspaceExtension.

func FuncWorkspaceExtension 

func FuncWorkspaceExtension(
	fn func(context.Context, *Workspace, config.Config) error,
) WorkspaceExtension

FuncWorkspaceExtension returns a WorkspaceExtension that calls fn on calls to ExtendWorkspace.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.