Documentation
¶
Index ¶
- Variables
- func BundleWorkerScript(deployPath string) (string, error)
- func EnsureUnenv(dataDir string) (string, error)
- func ResetUnenvCache()
- func ValidateCron(expr string) error
- func ValidateDatabaseID(id string) error
- type AssetsFetcher
- type CacheEntry
- type CacheStore
- type D1Bridge
- type D1ExecResult
- type D1Meta
- type DurableObjectStore
- type Engine
- func (e *Engine) CompileAndCache(siteID string, deployKey string, source string) ([]byte, error)
- func (e *Engine) EnsureSource(siteID string, deployKey string) error
- func (e *Engine) Execute(siteID string, deployKey string, env *Env, req *WorkerRequest) (result *WorkerResult)
- func (e *Engine) ExecuteScheduled(siteID string, deployKey string, env *Env, cron string) (result *WorkerResult)
- func (e *Engine) ExecuteTail(siteID string, deployKey string, env *Env, events []TailEvent) (result *WorkerResult)
- func (e *Engine) InvalidatePool(siteID string, deployKey string)
- func (e *Engine) MaxResponseBytes() int
- func (e *Engine) Shutdown()
- type EngineConfig
- type Env
- type KVListResult
- type KVPair
- type KVStore
- type KVValueWithMetadata
- type LogEntry
- type QueueMessageInput
- type QueueSender
- type R2ListOptions
- type R2ListResult
- type R2Object
- type R2PutOptions
- type R2Store
- type ServiceBindingBridge
- type ServiceBindingConfig
- type SourceLoader
- type TailEvent
- type WebSocketHandler
- type WorkerDispatcher
- type WorkerRequest
- type WorkerResponse
- type WorkerResult
Constants ¶
This section is empty.
Variables ¶
var DataDir = "./data"
DataDir is the base directory for cached polyfills. Defaults to "./data".
Functions ¶
func BundleWorkerScript ¶
BundleWorkerScript uses esbuild to bundle a worker's _worker.js entry point with all its imports into a single self-contained script. This enables ES module import/export support for worker scripts.
If the source doesn't contain any import statements, it's returned as-is to avoid unnecessary processing.
func EnsureUnenv ¶
EnsureUnenv downloads unenv and its dependencies from the npm registry into {dataDir}/polyfills/node_modules/ if not already present. Returns the path to the unenv package directory.
func ResetUnenvCache ¶
func ResetUnenvCache()
ResetUnenvCache clears the cached unenv path (used in tests).
func ValidateCron ¶
ValidateCron checks if a cron expression is a valid 5-field format. Fields: minute(0-59) hour(0-23) day(1-31) month(1-12) weekday(0-6).
func ValidateDatabaseID ¶
ValidateDatabaseID rejects database IDs that contain path traversal characters, null bytes, or are empty/too long.
Types ¶
type AssetsFetcher ¶
type AssetsFetcher interface {
Fetch(req *WorkerRequest) (*WorkerResponse, error)
}
AssetsFetcher is implemented by the static pipeline to handle env.ASSETS.fetch().
type CacheEntry ¶
CacheEntry represents a cached HTTP response (library-owned type, replaces models.CacheEntry).
type CacheStore ¶
type CacheStore interface {
Match(cacheName, url string) (*CacheEntry, error)
Put(cacheName, url string, status int, headers string, body []byte, ttl *int) error
Delete(cacheName, url string) (bool, error)
}
CacheStore backs the Cache API (site-scoped).
type D1Bridge ¶
type D1Bridge struct {
DatabaseID string
// contains filtered or unexported fields
}
D1Bridge provides Go methods that back the D1 database JS bindings. Each D1 binding gets its own isolated SQLite database, completely separate from the application's main database.
func NewD1BridgeMemory ¶
NewD1BridgeMemory creates an in-memory D1Bridge for testing.
func OpenD1Database ¶
OpenD1Database opens (or creates) an isolated SQLite database for the given database ID. The file is stored at {dataDir}/d1/{databaseID}.sqlite3.
type D1ExecResult ¶
type D1ExecResult struct {
Columns []string `json:"columns"`
Rows [][]interface{} `json:"rows"`
Meta D1Meta `json:"meta"`
}
D1ExecResult holds the result of executing a SQL statement.
type D1Meta ¶
type D1Meta struct {
ChangedDB bool `json:"changed_db"`
Changes int64 `json:"changes"`
LastRowID int64 `json:"last_row_id"`
RowsRead int `json:"rows_read"`
RowsWritten int `json:"rows_written"`
}
D1Meta holds metadata about a D1 query execution.
type DurableObjectStore ¶
type DurableObjectStore interface {
Get(namespace, objectID, key string) (string, error)
GetMulti(namespace, objectID string, keys []string) (map[string]string, error)
Put(namespace, objectID, key, valueJSON string) error
PutMulti(namespace, objectID string, entries map[string]string) error
Delete(namespace, objectID, key string) error
DeleteMulti(namespace, objectID string, keys []string) (int, error)
DeleteAll(namespace, objectID string) error
List(namespace, objectID, prefix string, limit int, reverse bool) ([]KVPair, error)
}
DurableObjectStore backs Durable Object storage.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine manages per-site worker pools and executes JS worker scripts.
func NewEngine ¶
func NewEngine(cfg EngineConfig, sourceLoader SourceLoader) *Engine
NewEngine creates an Engine with the given configuration and source loader.
func (*Engine) CompileAndCache ¶
CompileAndCache validates that a worker script compiles and stores the source for later pool creation. Returns the source bytes for disk storage.
func (*Engine) EnsureSource ¶
EnsureSource loads the worker JS source into memory if not already cached. Handles the server restart scenario where in-memory caches are lost.
func (*Engine) Execute ¶
func (e *Engine) Execute(siteID string, deployKey string, env *Env, req *WorkerRequest) (result *WorkerResult)
Execute runs the worker's fetch handler for the given request and returns the result including the response, captured logs, and any error. env must not be nil — the caller is responsible for constructing a fully-wired Env.
func (*Engine) ExecuteScheduled ¶
func (e *Engine) ExecuteScheduled(siteID string, deployKey string, env *Env, cron string) (result *WorkerResult)
ExecuteScheduled runs the worker's scheduled handler for cron triggers.
func (*Engine) ExecuteTail ¶
func (e *Engine) ExecuteTail(siteID string, deployKey string, env *Env, events []TailEvent) (result *WorkerResult)
ExecuteTail runs the worker's tail handler for log forwarding.
func (*Engine) InvalidatePool ¶
InvalidatePool marks the pool for the given site/deploy as invalid. The next Execute call will create a fresh pool.
func (*Engine) MaxResponseBytes ¶
MaxResponseBytes returns the configured maximum response body size.
type EngineConfig ¶
type EngineConfig struct {
PoolSize int // number of V8 isolates per site pool
MemoryLimitMB int // per-isolate memory limit
ExecutionTimeout int // milliseconds before worker is terminated
MaxFetchRequests int // max outbound fetches per request
FetchTimeoutSec int // per-fetch timeout in seconds
MaxResponseBytes int // max response body size
MaxScriptSizeKB int // max bundled script size
}
EngineConfig holds runtime configuration for the worker engine. This is a library-owned struct that replaces config.WorkerConfig, omitting application-level fields (MaxLogRetention, DataDir).
type Env ¶
type Env struct {
Vars map[string]string
Secrets map[string]string
// Opt-in bindings — nil means disabled
KV map[string]KVStore
Cache CacheStore
Storage map[string]R2Store
Queues map[string]QueueSender
D1Bindings map[string]string // binding name -> database ID
DurableObjects map[string]DurableObjectStore
ServiceBindings map[string]ServiceBindingConfig
// D1 configuration
D1DataDir string
// Runtime references
Assets AssetsFetcher
Dispatcher WorkerDispatcher // set by Engine before execution
SiteID string // site isolation key
}
Env holds all bindings passed to the worker as the second argument.
type KVListResult ¶
type KVListResult struct {
Keys []map[string]interface{}
ListComplete bool
Cursor string // base64-encoded offset, empty when list is complete
}
KVListResult holds the result of a List operation with pagination info.
type KVStore ¶
type KVStore interface {
Get(key string) (string, error)
GetWithMetadata(key string) (*KVValueWithMetadata, error)
Put(key, value string, metadata *string, ttl *int) error
Delete(key string) error
List(prefix string, limit int, cursor string) (*KVListResult, error)
}
KVStore backs a single KV namespace.
type KVValueWithMetadata ¶
KVValueWithMetadata holds a value and its associated metadata.
type LogEntry ¶
type LogEntry struct {
Level string `json:"level"`
Message string `json:"message"`
Time time.Time `json:"time"`
}
LogEntry is a single console.log/warn/error captured from a worker.
type QueueMessageInput ¶
QueueMessageInput is the Go representation of a batch send item.
type QueueSender ¶
type QueueSender interface {
Send(body, contentType string) (string, error)
SendBatch(messages []QueueMessageInput) ([]string, error)
}
QueueSender backs queue message production for a single queue. The queue name and site ID are baked into the implementation.
type R2ListOptions ¶
R2ListOptions configures an R2 list operation.
type R2ListResult ¶
type R2ListResult struct {
Objects []R2Object
Truncated bool
Cursor string
DelimitedPrefixes []string
}
R2ListResult holds the result of an R2 list operation.
type R2Object ¶
type R2Object struct {
Key string
Size int64
ContentType string
ETag string
LastModified time.Time
CustomMetadata map[string]string
}
R2Object holds metadata about an R2/S3-compatible object.
type R2PutOptions ¶
R2PutOptions configures an R2 put operation.
type R2Store ¶
type R2Store interface {
Get(key string) ([]byte, *R2Object, error)
Put(key string, data []byte, opts R2PutOptions) (*R2Object, error)
Delete(keys []string) error
Head(key string) (*R2Object, error)
List(opts R2ListOptions) (*R2ListResult, error)
PresignedGetURL(key string, expiry time.Duration) (string, error)
PublicURL(key string) (string, error)
}
R2Store backs R2-compatible object storage for a single bucket.
type ServiceBindingBridge ¶
type ServiceBindingBridge struct {
Dispatcher WorkerDispatcher
Env *Env
}
ServiceBindingBridge provides Go methods that back the service binding JS bindings.
func (*ServiceBindingBridge) Fetch ¶
func (sb *ServiceBindingBridge) Fetch(config ServiceBindingConfig, req *WorkerRequest) (*WorkerResponse, error)
Fetch calls the target worker's fetch handler with the given request. The target worker receives its own environment (not the caller's).
type ServiceBindingConfig ¶
ServiceBindingConfig identifies the target worker for a service binding.
type SourceLoader ¶
SourceLoader retrieves worker JS source code.
type TailEvent ¶
type TailEvent struct {
ScriptName string `json:"scriptName"`
Logs []LogEntry `json:"logs"`
Exceptions []string `json:"exceptions"`
Outcome string `json:"outcome"`
Timestamp time.Time `json:"timestamp"`
}
TailEvent represents a log event forwarded to a tail worker.
type WebSocketHandler ¶
type WebSocketHandler struct {
// contains filtered or unexported fields
}
WebSocketHandler holds references needed for WebSocket bridging after the initial fetch handler returns a 101 response with a webSocket.
func (*WebSocketHandler) Bridge ¶
func (wsh *WebSocketHandler) Bridge(ctx context.Context, httpConn *websocket.Conn)
Bridge starts the WebSocket message bridge between the HTTP connection and the V8 worker. This method blocks until the WebSocket connection closes or the timeout is reached. The worker is returned to the pool when done.
type WorkerDispatcher ¶
type WorkerDispatcher interface {
Execute(siteID, deployKey string, env *Env, req *WorkerRequest) *WorkerResult
}
WorkerDispatcher executes a worker (used by service bindings to dispatch to other workers without a direct Engine dependency).
type WorkerRequest ¶
WorkerRequest represents an incoming HTTP request to a worker.
type WorkerResponse ¶
type WorkerResponse struct {
StatusCode int
Headers map[string]string
Body []byte
HasWebSocket bool // true when status is 101 and webSocket was set
}
WorkerResponse represents the HTTP response from a worker.
type WorkerResult ¶
type WorkerResult struct {
Response *WorkerResponse
Logs []LogEntry
Error error
Duration time.Duration
WebSocket *WebSocketHandler // non-nil for WebSocket upgrade responses
}
WorkerResult wraps a response with execution metadata.
Source Files
¶
- abort.go
- assets.go
- bodytypes.go
- bundle.go
- byob_reader.go
- cache.go
- compression.go
- console.go
- cron.go
- crypto.go
- crypto_derive.go
- crypto_digeststream.go
- crypto_ecdh.go
- crypto_ed25519.go
- crypto_ext.go
- crypto_kw.go
- crypto_rsa.go
- d1.go
- durable.go
- encoding.go
- engine.go
- engineconfig.go
- eventloop.go
- eventsource.go
- fetch.go
- formdata.go
- globals.go
- htmlrewriter.go
- interfaces.go
- kv.go
- messagechannel.go
- polyfills.go
- pool.go
- queues.go
- runtime.go
- scheduler.go
- selector.go
- servicebinding.go
- storage.go
- streams.go
- tcpsocket.go
- textstreams.go
- timers.go
- types.go
- unhandledrejection.go
- urlpattern.go
- webapi.go
- websocket.go