PBVex

Appearance

runtime ​

go
import "github.com/nathabonfim59/pbvex/backend/internal/runtime"

Index ​

func ManifestFromContext ​

go
func ManifestFromContext(ctx context.Context) (deploy.DeploymentManifest, bool)

ManifestFromContext exposes the authenticated deployment snapshot to host capabilities.

func WithAuthContext ​

go
func WithAuthContext(ctx context.Context, auth AuthContext) context.Context

WithAuthContext returns a context that carries the auth context.

func WithScheduleNamespaces ​

go
func WithScheduleNamespaces(ctx context.Context, owner, target string) context.Context

WithScheduleNamespaces binds durable component ownership to a scheduler operation without changing the public Scheduler interface.

type AuthContext ​

AuthContext carries the identity of the caller into the runtime so that storage and other host services can bind capabilities to the requester.

go
type AuthContext struct {
    IsAuthenticated bool
    // TokenIdentifier is stable across collection renames and globally unique
    // across PocketBase auth collections.
    TokenIdentifier string
    Identity        *auth.UserIdentity
    RequestID       string
}

func AuthFromContext ​

go
func AuthFromContext(ctx context.Context) (AuthContext, bool)

AuthFromContext extracts the auth context, if any.

type Bridge ​

Bridge is the host bridge exposed to the JS bundle.

go
type Bridge struct {
    // contains filtered or unexported fields
}

func (*Bridge) RegisterFunction ​

go
func (b *Bridge) RegisterFunction(descriptor goja.Value, handler goja.Value) error

RegisterFunction implements globalThis.__pbvex.registerFunction(descriptor, handler).

func (*Bridge) RegisterMigration ​

go
func (b *Bridge) RegisterMigration(descriptor, up, down goja.Value) error

RegisterMigration implements __pbvex.registerMigration(descriptor, up, down).

func (*Bridge) Verify ​

go
func (b *Bridge) Verify(descriptors []deploy.FunctionDescriptor, migrations []deploy.MigrationDescriptor) error

Verify ensures every manifest function is registered and descriptors match exactly.

type Config ​

Config controls the Goja runtime pool.

go
type Config struct {
    PoolSize int
    Timeout  time.Duration
}

func DefaultConfig ​

go
func DefaultConfig() Config

DefaultConfig returns the default runtime pool configuration.

type ContextExtender ​

ContextExtender extends the JS invocation context with host capabilities (such as storage and auth) that live outside the runtime package. It is invoked after the runtime builds the base context object so the registrar can attach services without the runtime depending on them directly.

go
type ContextExtender func(vm *goja.Runtime, ctx context.Context, app core.App, fd deploy.FunctionDescriptor, obj *goja.Object) error

type Invocation ​

Invocation carries request-scoped context for a single function invocation. It is immutable except for the context/deadline information and the nested call bookkeeping.

go
type Invocation struct {
    // Ctx is the caller context for cancellation and deadlines.
    Ctx context.Context

    // Identity is the authenticated user identity for this invocation, or nil
    // for unauthenticated requests.
    Identity *auth.UserIdentity

    // RequestID is the request identifier propagated through HTTP/realtime and
    // nested calls.
    RequestID string

    // DeploymentID identifies the deployment whose runtime is used.
    DeploymentID string

    // FunctionType is the type of the function being invoked.
    FunctionType deploy.FunctionType
    FunctionName string
    // Namespace is root or the deterministic component namespace selected by
    // the target function descriptor.
    Namespace string

    // HTTPRequest is the parsed HTTP request envelope for httpAction calls.
    HTTPRequest *deploy.HTTPRequestEnvelope

    // App and Manifest are set for database-aware invocations. When App is nil,
    // the runtime uses no-op stubs for db/storage/scheduler.
    App      core.App
    Manifest deploy.DeploymentManifest

    // MaxArgsBytes and MaxReturnBytes are wire size limits from the manifest.
    MaxArgsBytes   int64
    MaxReturnBytes int64
    RequestTimeout time.Duration

    // Depth is the current nested call depth (0 for the outer invocation).
    Depth int

    // Work is a shared, nonrefundable cumulative counter for all nested calls
    // in the invocation tree. It is a pointer so that parent, child, and
    // sibling calls all observe the same monotonically increasing budget.
    Work *int

    // NestedInvoke dispatches nested calls through a fresh runtime entry while
    // preserving this invocation tree's request-scoped state.
    NestedInvoke func(parent *Invocation, functionName string, targetType deploy.FunctionType, args any, depth int) (any, error)
}

type Manager ​

Manager is a registry of bounded Goja runtime pools keyed by deployment id.

go
type Manager struct {
    Scheduler Scheduler
    // contains filtered or unexported fields
}

func NewManager ​

go
func NewManager(config Config) *Manager

NewManager creates a new runtime manager.

func (*Manager) AddContextExtender ​

go
func (m *Manager) AddContextExtender(ext ContextExtender)

AddContextExtender appends a host capability hook. Hooks run in registration order after the runtime has installed its base database capability and before the scheduler capability is attached. Existing pools are dropped so a hook registered after compilation cannot be silently omitted.

func (*Manager) Compile ​

go
func (m *Manager) Compile(deploymentID, bundle string, descriptors []deploy.FunctionDescriptor, configs ...deploy.DeploymentConfig) error

Compile compiles and stores the bundle program for a deployment.

func (*Manager) CompileDeployment ​

go
func (m *Manager) CompileDeployment(deploymentID, bundle string, descriptors []deploy.FunctionDescriptor, migrations []deploy.MigrationDescriptor, configs ...deploy.DeploymentConfig) error

CompileDeployment stores both function and migration registration contracts.

func (*Manager) Drop ​

go
func (m *Manager) Drop(deploymentID string)

Drop removes an invalidated deployment runtime (trim, deletion, rollback transitions). It is safe for in-flight callers: they hold the old pool.

func (*Manager) Invoke ​

go
func (m *Manager) Invoke(ctx context.Context, deploymentID, functionName string, args any, authArgs ...any) (any, error)

Invoke runs the named function in a fresh bounded runtime.

func (*Manager) InvokeHTTP ​

go
func (m *Manager) InvokeHTTP(ctx context.Context, deploymentID, functionName string, httpEnvelope *deploy.HTTPRequestEnvelope, identity *auth.UserIdentity, requestID string) (*deploy.HTTPResponseEnvelope, error)

InvokeHTTP runs the named httpAction and returns an HTTP response envelope.

func (*Manager) InvokeHTTPWithDatabase ​

go
func (m *Manager) InvokeHTTPWithDatabase(ctx context.Context, deploymentID, functionName string, httpEnvelope *deploy.HTTPRequestEnvelope, identity *auth.UserIdentity, requestID string, app core.App, manifest deploy.DeploymentManifest) (*deploy.HTTPResponseEnvelope, error)

InvokeHTTPWithDatabase preserves the app and manifest snapshot for nested calls issued by an HTTP action.

func (*Manager) InvokeMigration ​

go
func (m *Manager) InvokeMigration(ctx context.Context, deploymentID, migrationID, direction string, document any, activationTime int64) (any, error)

InvokeMigration executes a pure synchronous up/down handler. The caller owns the surrounding database transaction; this method never starts one.

func (*Manager) InvokeWithDatabase ​

go
func (m *Manager) InvokeWithDatabase(ctx context.Context, deploymentID, functionName string, args any, extra ...any) (any, error)

InvokeWithDatabase is used by deploy.Service for real requests that need database access. Mutations are wrapped in a PocketBase transaction so that invalid returns, timeouts, and cancellations roll back all writes.

func (*Manager) Verify ​

go
func (m *Manager) Verify(ctx context.Context, deploymentID, bundle string, descriptors []deploy.FunctionDescriptor) error

Verify loads the bundle in a fresh runtime and confirms that every declared function is registered with an exact descriptor match.

func (*Manager) VerifyDeployment ​

go
func (m *Manager) VerifyDeployment(ctx context.Context, deploymentID, bundle string, descriptors []deploy.FunctionDescriptor, migrations []deploy.MigrationDescriptor) error

VerifyDeployment requires exact function and migration registration parity.

type MigrationError ​

MigrationError is the bounded, document-free failure produced by ctx.fail.

go
type MigrationError struct{ Message string }

func (*MigrationError) Error ​

go
func (e *MigrationError) Error() string

type Pool ​

Pool is a bounded concurrency gate for Goja runtimes for a single deployment.

go
type Pool struct {
    // contains filtered or unexported fields
}

type RuntimeInvoker ​

RuntimeInvoker is the interface used by the deploy service.

go
type RuntimeInvoker interface {
    Compile(deploymentID, bundle string, descriptors []deploy.FunctionDescriptor, config ...deploy.DeploymentConfig) error
    Verify(ctx context.Context, deploymentID, bundle string, descriptors []deploy.FunctionDescriptor) error
    Invoke(ctx context.Context, deploymentID, functionName string, args any, authArgs ...any) (any, error)
    InvokeHTTP(ctx context.Context, deploymentID, functionName string, httpEnvelope *deploy.HTTPRequestEnvelope, identity *auth.UserIdentity, requestID string) (*deploy.HTTPResponseEnvelope, error)
}

type ScheduleNamespaces ​

go
type ScheduleNamespaces struct {
    Owner  string
    Target string
}

func ScheduleNamespacesFromContext ​

go
func ScheduleNamespacesFromContext(ctx context.Context) (ScheduleNamespaces, bool)

type Scheduler ​

Scheduler is the capability exposed to mutations and actions.

go
type Scheduler interface {
    RunAfter(ctx context.Context, delayMs int64, deploymentID, functionName string, args any) (string, error)
    RunAt(ctx context.Context, epochMs int64, deploymentID, functionName string, args any) (string, error)
    Cancel(ctx context.Context, jobID string) error
}

type WireLimitError ​

WireLimitError distinguishes adversarial resource-limit failures from a malformed ordinary value. Callers intentionally turn both into the same structured public error, but the type keeps tests and hosts from treating a rejected sparse array as an internal Go failure.

go
type WireLimitError struct{ Limit string }

func (*WireLimitError) Error ​

go
func (e *WireLimitError) Error() string

Generated by gomarkdoc

Generated API reference. Source of truth is the codebase.

Copyright © 2026 PBVex authors