gobeyond

README

GoBeyond

GoBeyond is an experimental, MIT-licensed application framework for building web experiences, durable workflows, and AI agents in one Go application. React owns interactive UI, Go owns the site and durable runtimes, and Temporal is an optional durability layer for the definitions that need it.

[!WARNING] GoBeyond is under heavy active development. APIs, filesystem conventions, generated artifacts, and hosting contracts can and likely will change before a stable release. Pin exact alpha versions and review the changelog when upgrading.

Build the page, the long-running work behind it, and the agent that helps the user—without shipping a Node production runtime.

Node is used for development and builds. The site and workflow runtimes are Go executables; an optional root middleware.go runs in the same Go process and slot as the application. Simple redirects and same-origin rewrites live in gobeyond.json, which can be evaluated by the platform edge and by the Go origin when the edge is bypassed. Browser JavaScript, CSS, images, and fonts can also be served from a CDN.

One project, three primitives

Primitive	Author in	Use it for	Runtime
Web	app/, optional middleware.go, gobeyond.json	React pages, typed actions, HTTP APIs, middleware, redirects, rewrites, and request-time data	Go site server, optional platform policy evaluation, and browser assets
Workflows	workflows/	Durable orchestration and reusable standalone activities	Temporal queue workers
Agents	agents/	Typed handlers or AI agents with tools and streaming	Direct in the site process, or durable through Temporal

All three surfaces share ordinary application code under internal/:

app/                         web routes, actions, and APIs
middleware.go                optional authored Go middleware in the app slot
gobeyond.json                optional edge/origin redirects and rewrites
agents/<id>/                 one typed or AI agent definition
workflows/<id>/              one workflow or standalone activity definition
internal/                    shared services, integrations, and policy
generated/                   GoBeyond-owned projections and registries

The compiler discovers definitions from the filesystem, generates safe Go registries, and groups durable work by logical task queue. Application code does not maintain worker mains, provider plumbing, session routes, or Temporal registration by hand.

Web

page.tsx is the source of truth for initial markup and browser interaction. A sibling page.go opts a route into request-time Go data; actions.go adds typed mutations and app/api/**/route.go adds Go HTTP endpoints.

An optional root middleware.go defines exactly one Middleware(next gb.Handler) gb.Handler hook. It runs in the same Go process and slot as the application handlers. gobeyond.json carries the smaller redirect/rewrite policy that the platform edge may evaluate before cache/origin routing and the Go runtime evaluates again when the edge is bypassed.

app/products/[slug]/page.tsx        React content and interaction
app/products/[slug]/page.go         request-time props, status, and metadata
app/products/[slug]/actions.go      authorization and mutations
app/api/products/route.go           Go HTTP API

GoBeyond compiles the documented portable React profile into a language-neutral rendering plan. Go returns meaningful HTML and React hydrates the same component tree. It is not a TypeScript-to-Go translator, a general JavaScript SSR engine, or an exact Next.js replacement.

Workflows

Each immediate child of workflows/ defines one workflow or standalone activity. Workflow-owned activities and child workflows stay inside that definition folder. Empty task queues inherit from their owner and ultimately resolve to the logical default queue.

workflows/orders/workflow.go
workflows/orders/activities/charge/activity.go
workflows/send-receipt/activity.go

Builds emit one Go poller binary per resolved queue. Local and preview modes supervise those binaries when Temporal definitions are present; GoBeyond does not start or manage Temporal itself.

Agents

Each immediate child of agents/ defines one agent. Typed handlers run directly by default for low latency. DefineAI hides model streaming, tools, provider binding, and the model/tool loop behind a compiler-visible definition and an instructions.md prompt.

Set Durable: true per agent to run model and tool steps as Temporal activities. Direct and durable agents share the generated session API and the browser-safe @go-beyond/agents client, so durability is an execution choice rather than a different application contract.

Try the repository

Requirements: Go 1.24+, Node 22+, and pnpm 10.33.0.

pnpm install
go run ./cmd/gobeyond doctor
go run ./cmd/gobeyond generate
go run ./cmd/gobeyond dev

The public address defaults to http://localhost:3000. Development builds a replacement Go server on a fresh internal port, switches the stable proxy only after readiness passes, and keeps the last working server online after failed builds. When middleware exists, development also bundles and runs it in front of each candidate Go server. Direct agents run with the site process.

When the project contains workflows or durable agents, dev also builds and supervises the required queue workers. They retry while user-managed Temporal is unavailable. Pass --no-workflows to run the site and direct agents without Temporal pollers.

The durable example includes local Temporal setup and web, workflow, and agent entry points:

docker compose -f examples/durables-site/docker-compose.temporal.yml up -d
export GOBEYOND_WEBSITE=examples/durables-site
go run ./cmd/gobeyond dev

Build and verify

go run ./cmd/gobeyond generate --check
go test ./...
go test ./... -C imageopt/s3
pnpm -r test
go run ./cmd/gobeyond build
./scripts/verify-node-free-server.sh

The nested imageopt/s3 module is tested separately so the AWS SDK stays out of the root module graph. A build emits:

dist/
  static/    CDN documents and browser assets
  server/    Go site executable, rendering plans, and runtime manifest
  workers/   Go Temporal poller binaries grouped by logical task queue
  deploy/    route, worker, policy, and artifact manifests

Preview serves the complete built application and supervises its built queue workers:

go run ./cmd/gobeyond preview
go run ./cmd/gobeyond preview --no-workflows

What you can build today

• Web: portable cross-file React components render meaningful HTML from Go, hydrate without a second template, and support typed Go data, actions, APIs, metadata, caching, redirects, 404 responses, and soft navigation.
• Workflows: filesystem definitions compile into deterministic workflow and activity registrations, inherit logical queues, and run in supervised local, preview, and production worker binaries.
• Agents: typed and AI definitions expose one session/streaming contract; direct execution favors latency while durable execution uses granular model and tool activities with exact build-revision fencing.
• Production: site and worker runtimes are Go binaries; authored request middleware is compiled into the site process, while the small policy artifact may also be evaluated by the platform edge. The server artifact audit rejects Node/npm executables and dependency trees under dist/server.

The web conformance gate renders the same portable fixture with Go, hydrates it in a browser-like DOM using pinned React, asserts zero recoverable hydration errors, and verifies post-hydration interaction.

Web rendering boundary

SEO-critical initial markup may use project-owned components, schema-backed props, deterministic expressions, typed conditions, and stable keyed maps. Event handlers and effect bodies stay browser JavaScript. Unsupported render behavior may downgrade only at an explicit client boundary; unmarked unsupported behavior and contract failures remain fatal.

Rich HTML crosses an explicit SafeHTML boundary. Static props and generated route data are public and must never contain secrets. Vite exposes only VITE_* environment values to browser modules; unprefixed provider, database, and CMS credentials remain server-side.

See the architecture and web guides for the complete portability, caching, metadata, image, and deployment contracts.

Documentation

Start with the documentation map, or go directly to a primitive:

• Build agents
• Build workflows and activities
• Add a React page
• Connect request-time Go data
• Add a typed action
• Add a Go API
• Add request middleware
• Architecture and runtime boundaries
• AWS deployment reference

Status

GoBeyond is alpha software, as the warning above describes. Web compatibility is deliberately pinned to React 19.2.8. Workflow and agent APIs are evolving, and hosted persistence and revision retention depend on the selected deployment adapter.

Documentation

Overview

Package gobeyond defines the public request-time contracts used by GoBeyond page loaders, actions, API handlers, middleware, and durable workers.

Index

• Constants
• func Fetch(ctx context.Context, request *http.Request) (*http.Response, error)
• func NormalizeEnvironment(env string) (string, error)
• func NormalizeTaskQueueID(id string) (string, error)
• func TaskQueueName(taskQueueID, environment string) (string, error)
• func WithFetcher(ctx context.Context, fetcher Fetcher) context.Context
• type ActionContext
• type ActionResult
• type Alternate
• type CacheMode
• type CachePolicy
  • func PublicRevalidate(fresh, stale, staleIfError time.Duration) CachePolicy
  • func (p CachePolicy) HeaderValue() string
• type DeadlinePolicy
• type Fetcher
• type FetcherFunc
  • func (f FetcherFunc) Fetch(ctx context.Context, request *http.Request) (*http.Response, error)
• type Handler
• type Icons
• type JSONLD
• type Metadata
  • func (m Metadata) IsNoIndex() bool
  • func (m Metadata) Validate(publicOrigin string, indexable bool) error
• type Middleware
• type MiddlewareConfig
• type OpenGraph
• type OpenGraphImage
• type PageConfig
• type PageContext
• type PagePrefetchConfig
• type PagePrefetchImage
• type PageResult
  • func NotFound[T any](props T, metadata Metadata) PageResult[T]
  • func OK[T any](props T, metadata Metadata) PageResult[T]
  • func Redirect[T any](location string, permanent bool) PageResult[T]
• type ProxyPolicy
• type RequestContext
• type Response
  • func Rewrite(path string) Response
• type ResultKind
• type Twitter

Constants

const (
	MaxTaskQueueIDBytes = 48
	MaxEnvironmentBytes = 32
	MaxTaskQueueBytes   = 82 // taskQueueId + "__" + environment
	TaskQueueSeparator  = "__"
	DefaultTaskQueueID  = "default"
	LocalEnvironment    = "local"
	PreviewEnvironment  = "preview"
)

Durable length budgets (ADR 006). Stricter than Temporal's 1000-byte ID limit.

const RenderAPIVersion = "gobeyond.render/v1alpha1"

Functions

func Fetch

func Fetch(ctx context.Context, request *http.Request) (*http.Response, error)

Fetch dispatches a GoBeyond application request. The runtime first attempts same-slot dispatch and transparently uses the trusted platform-origin path only when the current build has no matching route. Application responses and errors are never replayed through the fallback.

func NormalizeEnvironment

func NormalizeEnvironment(env string) (string, error)

NormalizeEnvironment validates an environment slug used in task queue names.

func NormalizeTaskQueueID

func NormalizeTaskQueueID(id string) (string, error)

NormalizeTaskQueueID validates and returns a logical task queue id. Empty becomes "default".

func TaskQueueName

func TaskQueueName(taskQueueID, environment string) (string, error)

TaskQueueName returns {taskQueueId}__{environment}.

func WithFetcher

func WithFetcher(ctx context.Context, fetcher Fetcher) context.Context

WithFetcher binds the framework fetch implementation to a request context. It is intended for runtime and adapter integrations; application code should call Fetch instead of installing its own transport.

Types

type ActionContext

type ActionContext struct {
	Context      context.Context
	Request      *http.Request
	PublicOrigin string
	Params       map[string]string
	Values       map[string]any
	BuildID      string
}

type ActionResult

type ActionResult[T any] struct {
	Data        T                 `json:"data,omitempty"`
	FieldErrors map[string]string `json:"fieldErrors,omitempty"`
	RedirectTo  string            `json:"redirectTo,omitempty"`
	// Deprecated: RefreshRoutes was never read by the runtime. Actions that
	// need the client to refresh routes after a mutation should call
	// cache.RevalidatePath / cache.RevalidateTag; the runtime emits recorded
	// paths and tags in cache.ActionEnvelope.Refresh.
	RefreshRoutes []string `json:"refreshRoutes,omitempty"`
}

type Alternate

type Alternate struct {
	Language string `json:"language"`
	URL      string `json:"url"`
}

type CacheMode

type CacheMode string

const (
	CachePrivateNoStore CacheMode = "private_no_store"
	CachePublic         CacheMode = "public"
)

type CachePolicy

type CachePolicy struct {
	Mode                 CacheMode `json:"mode"`
	MaxAge               int       `json:"maxAge,omitempty"`
	SharedMaxAge         int       `json:"sharedMaxAge,omitempty"`
	StaleWhileRevalidate int       `json:"staleWhileRevalidate,omitempty"`
	StaleIfError         int       `json:"staleIfError,omitempty"`
}

func PublicRevalidate

func PublicRevalidate(fresh, stale, staleIfError time.Duration) CachePolicy

PublicRevalidate returns a public policy that keeps browser responses stale while allowing shared caches to retain and asynchronously refresh them. Non-positive durations disable their corresponding directive.

func (CachePolicy) HeaderValue

func (p CachePolicy) HeaderValue() string

type DeadlinePolicy

type DeadlinePolicy struct {
	Loader time.Duration
	Render time.Duration
	Action time.Duration
	API    time.Duration
}

type Fetcher

type Fetcher interface {
	Fetch(context.Context, *http.Request) (*http.Response, error)
}

Fetcher is the runtime-bound implementation used by Fetch. Hosted runtimes install one on the request context; application code only calls Fetch and does not need to know whether the target is handled in-process or by the platform origin.

type FetcherFunc

type FetcherFunc func(context.Context, *http.Request) (*http.Response, error)

FetcherFunc adapts a function to Fetcher.

func (FetcherFunc) Fetch

func (f FetcherFunc) Fetch(ctx context.Context, request *http.Request) (*http.Response, error)

type Handler

type Handler func(*RequestContext) (Response, error)

type Icons

type Icons struct {
	Icon       string `json:"icon,omitempty"`
	AppleTouch string `json:"appleTouch,omitempty"`
}

type JSONLD

type JSONLD map[string]any

JSONLD is serialized by the document renderer with script-safe escaping. Values must be composed solely of JSON-compatible primitives, arrays, and maps.

type Metadata

type Metadata struct {
	Lang        string      `json:"lang"`
	Title       string      `json:"title"`
	Description string      `json:"description,omitempty"`
	Canonical   string      `json:"canonical,omitempty"`
	Robots      string      `json:"robots,omitempty"`
	OpenGraph   OpenGraph   `json:"openGraph,omitempty"`
	Twitter     Twitter     `json:"twitter,omitempty"`
	Icons       Icons       `json:"icons,omitempty"`
	Alternates  []Alternate `json:"alternates,omitempty"`
	JSONLD      []JSONLD    `json:"jsonLd,omitempty"`
}

func (Metadata) IsNoIndex

func (m Metadata) IsNoIndex() bool

IsNoIndex reports whether the robots directives explicitly prevent this document from being indexed. A route's generated indexability flag can be conservative for static TypeScript-only routes, so an explicit robots directive is authoritative at document-render time.

func (Metadata) Validate

func (m Metadata) Validate(publicOrigin string, indexable bool) error

type Middleware

type Middleware func(Handler) Handler

Middleware is the one application request hook. A root middleware.go exports a function with this shape; the generated server invokes the resulting handler in the same process and execution slot as the application.

type MiddlewareConfig

type MiddlewareConfig struct {
	Patterns []string
	Methods  []string
}

MiddlewareConfig configures the retained low-level rule adapter.

Deprecated: new applications should compose one root Go Middleware handler.

type OpenGraph

type OpenGraph struct {
	Type        string          `json:"type,omitempty"`
	Title       string          `json:"title,omitempty"`
	Description string          `json:"description,omitempty"`
	URL         string          `json:"url,omitempty"`
	SiteName    string          `json:"siteName,omitempty"`
	Locale      string          `json:"locale,omitempty"`
	Image       *OpenGraphImage `json:"image,omitempty"`
	// Images is retained for compatibility. Prefer Image when dimensions and
	// descriptive metadata are available.
	Images []string `json:"images,omitempty"`
}

type OpenGraphImage

type OpenGraphImage struct {
	URL    string `json:"url"`
	Width  int    `json:"width,omitempty"`
	Height int    `json:"height,omitempty"`
	Alt    string `json:"alt,omitempty"`
	Type   string `json:"type,omitempty"`
}

type PageConfig

type PageConfig struct {
	Revalidate int
	Tags       []string
	Prefetch   PagePrefetchConfig
}

PageConfig declares the compiler-visible cache contract for a Go-owned page payload. GoBeyond generates the sibling page.schema.ts from this value and the page's Props type.

type PageContext

type PageContext struct {
	Context context.Context
	Request *http.Request
	// PublicOrigin is the absolute origin resolved for this request.
	PublicOrigin string
	Params       map[string]string
	Values       map[string]any
	BuildID      string
}

type PagePrefetchConfig

type PagePrefetchConfig struct {
	Data   bool
	Images []PagePrefetchImage
}

PagePrefetchConfig opts a route into private, in-tab data warming and explicit image variants after the runtime payload arrives.

type PagePrefetchImage

type PagePrefetchImage struct {
	Path string
	W    int
	Q    int
	F    string
}

PagePrefetchImage identifies a string prop and the exact imageSrc variant to warm. Path is dot-separated from the page props root.

type PageResult

type PageResult[T any] struct {
	Kind       ResultKind        `json:"kind"`
	Props      T                 `json:"props,omitempty"`
	Metadata   Metadata          `json:"metadata,omitempty"`
	Status     int               `json:"status,omitempty"`
	Headers    map[string]string `json:"headers,omitempty"`
	Cache      CachePolicy       `json:"cache"`
	RedirectTo string            `json:"redirectTo,omitempty"`
	ErrorCode  string            `json:"errorCode,omitempty"`
	Message    string            `json:"message,omitempty"`
}

func NotFound

func NotFound[T any](props T, metadata Metadata) PageResult[T]

func OK

func OK[T any](props T, metadata Metadata) PageResult[T]

func Redirect

func Redirect[T any](location string, permanent bool) PageResult[T]

type ProxyPolicy

type ProxyPolicy = policy.Policy

ProxyPolicy is the validated build-scoped policy shared by the origin runtime and the platform edge. It is an alias so generated applications can expose the policy without importing an implementation package in their authored middleware contract.

type RequestContext

type RequestContext struct {
	Context      context.Context
	Request      *http.Request
	PublicOrigin string
	Params       map[string]string
	Values       map[string]any
	BuildID      string
}

type Response

type Response struct {
	Status    int
	Headers   http.Header
	Body      []byte
	RewriteTo string
}

func Rewrite

func Rewrite(path string) Response

type ResultKind

type ResultKind string

const (
	ResultOK            ResultKind = "ok"
	ResultRedirect      ResultKind = "redirect"
	ResultNotFound      ResultKind = "not_found"
	ResultPublicError   ResultKind = "public_error"
	ResultInternalError ResultKind = "internal_error"
)

type Twitter

type Twitter struct {
	Card        string   `json:"card,omitempty"`
	Title       string   `json:"title,omitempty"`
	Description string   `json:"description,omitempty"`
	Site        string   `json:"site,omitempty"`
	ImageAlt    string   `json:"imageAlt,omitempty"`
	Images      []string `json:"images,omitempty"`
}