Go SDK
The Go SDK provides interfaces for host HTTP, state, workspace and logging operations, plus envelope and model-event structs. Build with regular Go and the pinned Componentize Go tool; the supported recipe does not use TinyGo.
Create and build
glxdev new --kind reference --reference workflow-text-stats --language go --package-id org.example.text-stats --name "Text statistics" --publisher org.example --output ./text-stats-go
cd text-stats-go
glxdev doctor
glxdev check
go test ./...
componentize-go --wit-path wit --world contribution bindings --output generated/wit --format --pkg-name github.com/glixo-community/glixo-contribution-guest-go/generated/wit --export-pkg-name github.com/glixo-community/glixo-contribution-guest-go/generated/wit/export_provider
componentize-go --wit-path wit --world contribution build --output dist/glixo-extension.component.wasm
Use Go 1.27.1, Componentize Go 0.4.3 and go.bytecodealliance.org/pkg 0.2.3. Keep the generated module/import names aligned with your go.mod and main.go; the command above uses the Text Stats scaffold's module name. The provider template uses a different world and export package, so use its recipe rather than substituting only the world name. See the build matrix and Go project module.
Install the SDK
The scaffold contains a local SDK and a replace directive so it builds independently. Keep that route, or deliberately switch your module to the published dependency:
go get github.com/tmedanovic/glixo-community-modules/packages/extension-sdk/go@v0.1.0
If switching, remove the SDK's local replace directive and run go mod tidy; otherwise Go continues to use the local files. The public module path is the one shown above. The generated bindings and componentizer are still required. Download the source or inspect go.mod.
Packages and signatures
Import subpackages below github.com/tmedanovic/glixo-community-modules/packages/extension-sdk/go:
| Package | Types and behavior |
|---|---|
/guest |
Envelope[T], Context, Endpoint; envelope fields have camelCase JSON tags |
/state |
Store: Get(string) (string,bool,error), Set(string,string) error, List(string) ([]string,error), Delete(string) (bool,error) |
/workspace |
Reader: Search(handle,query string,limit uint32) (string,error), Read(handle,path string,maxBytes uint32) (string,error) |
/logging |
Logger.Log(level,message string) error |
/httpbroker |
Header, Request, Broker, Stream, Open, read/line size constants |
/llm |
ToolCallDetails, Usage, Event |
Read the envelope, state, workspace, logging, HTTP and event sources.
Store.Get distinguishes missing (found == false) from failure (err != nil). Do not turn permission denial into a missing key. Optional HTTP fields are pointers; absent and zero are different values. HTTPRead(handle,maxBytes) returns (bytes,more,error), where more == false is EOF. The host decides permission; implementing an interface with native network access does not supply a Glixo grant.
Export a contribution
The generated export wrapper returns types.Result[string,string]. Text Stats wires its pure handler as follows:
func Invoke(requestJSON string) types.Result[string, string] {
output, err := workflowtextstats.Handle(requestJSON)
if err != nil {
return types.Err[string, string](stableErrorCode(err))
}
return types.Ok[string, string](output)
}
This is a function excerpt: its package, imports and stableErrorCode are in the complete export file. main.go imports the generated wit_exports registration package for its side effect. Keep handwritten implementation code separate from files regenerated by the componentizer. For another feature, adapt the exported handler in the generated project's extension-specific implementation file.
Parse the host envelope with encoding/json, validate the contribution identity, and return a JSON string matching your output schema. A Go panic is not a normal WIT error result. Convert expected errors into the generated error arm, keeping codes bounded. The complete handler includes Unicode counting and input validation.
Streams, cleanup and running
httpbroker.Open(broker,request,maxLineBytes) returns a stream or error. NextLine() returns a line or io.EOF; other errors are failures. Use defer stream.Close() after a successful open. Cancel() cancels and closes once. With a nonpositive line limit, the helper selects its 1 MiB default; default reads are 16 KiB. Empty chunks do not mean EOF. See HTTP and NDJSON.
Run go test ./... on pure handlers and adapters, then compile the component. Follow signing, installation and activation to invoke it in Glixo. Native Go tests do not execute the host's permission boundary.