transport

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Sep 13, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package transport is cloudrig's front door: one handler on one port, serving REST over HTTP/1.1 and gRPC over cleartext HTTP/2 at once.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Protocols

func Protocols() *http.Protocols

Protocols is the set every cloudrig listener uses: HTTP/1.1 plus cleartext HTTP/2. Go 1.24 serves h2c from net/http, so this costs no dependency.

Types

type ClockStatus

type ClockStatus struct {
	// Mode is "manual" when the clock is client-controlled, else "real".
	Mode string `json:"mode"`
	Now  string `json:"now"`
	// Pending is the number of timers still scheduled — scheduled tasks, ack
	// deadlines, TTLs — waiting for the clock to reach them. Virtual mode only.
	Pending int `json:"pending"`
}

ClockStatus is the /_emu/clock body.

type Config

type Config struct {
	Clock clock.Clock

	// Version is reported by /_emu/health. Empty means "dev".
	Version string

	// Runner describes the function runner.
	Runner RunnerInfo

	// Functions hosts deployed functions. Nil means none are served.
	Functions FunctionHost

	// Mounts are service handlers keyed by path prefix, tried before the
	// built-in mux. Services own their own routing, so the front door needs no
	// knowledge of their URL grammar.
	Mounts map[string]http.Handler

	// Fallback handles paths no route claimed. Cloud Storage needs it: the Go
	// client downloads from /{bucket}/{object}, which has no prefix to mount
	// on and is only distinguishable from anything else by asking.
	Fallback http.Handler

	// Reset clears emulator state. An empty project clears everything.
	Reset func(ctx context.Context, project string) error

	// GRPC handles requests on the gRPC branch. Nil answers them with 501.
	GRPC http.Handler

	// Faults fails requests on purpose. Nil fails nothing.
	Faults *faults.Set

	// Services hosts deployed Cloud Run services. Nil means none are served.
	Services ServiceHost

	// Drain waits for the asynchronous work a clock jump sets off (task and
	// scheduler deliveries, triggered function invocations). Called after a
	// virtual-clock advance/goto so the response follows the side effects. Nil
	// waits for nothing.
	Drain func()
}

Config wires a Handler. Clock is required; everything else has a default.

type FaultRule

type FaultRule struct {
	Method  string  `json:"method,omitempty"`
	Path    string  `json:"path"`
	Status  int     `json:"status,omitempty"`
	Message string  `json:"message,omitempty"`
	Latency string  `json:"latency,omitempty"`
	Count   int     `json:"count,omitempty"`
	Rate    float64 `json:"rate,omitempty"`
}

FaultRule is the wire form of a fault rule. Latency is a Go duration string ("2s") rather than nanoseconds so the API reads the way the CLI writes it.

type FunctionHost

type FunctionHost interface {
	// Route resolves a request path to a function and the path it should see.
	Route(escapedPath string) (h http.Handler, rest string, ok bool)

	// Admin serves the deploy, list, describe and delete API.
	Admin() http.Handler
}

FunctionHost serves deployed functions and their admin API.

Route takes the whole path rather than a name so that URL grammar — the project and location prefix among it — stays in the functions package. The front door knows only that something claimed the request.

type Handler

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

Handler is the h2c front door.

func New

func New(cfg Config) *Handler

New builds the front door. Routes register here so the endpoint set is readable in one place.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP splits gRPC from REST. Real clients send a subtype (application/grpc+proto), hence the prefix test rather than equality.

type HandlerFunc

type HandlerFunc func(w http.ResponseWriter, r *http.Request, p Params) error

HandlerFunc is a route handler. Returning an error is the normal failure path: the router renders it through gerr.

type Health

type Health struct {
	Status  string     `json:"status"`
	Version string     `json:"version"`
	Uptime  string     `json:"uptime"`
	Runner  RunnerInfo `json:"runner"`
}

Health is the /_emu/health body.

type Params

type Params map[string]string

Params holds the decoded capture values from a matched route.

type Router

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

Router matches on EscapedPath, never Path: net/http decodes Path first, which makes a%2Fb and a/b indistinguishable. GCP resource names need both.

It is exported so service packages can declare their own routes without the front door having to know about them.

func NewRouter

func NewRouter() *Router

NewRouter returns an empty Router.

func (*Router) Handle

func (rt *Router) Handle(method, pattern string, h HandlerFunc)

Handle registers a route. Braced segments capture; everything else matches literally. There is no multi-segment wildcard because nothing needs one.

func (*Router) Matches

func (rt *Router) Matches(method, escapedPath string) bool

Matches reports whether any route would handle this request, so a caller can try something else before the mux answers 404.

func (*Router) ServeHTTP

func (rt *Router) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP dispatches to a matching route, rendering a handler's error and distinguishing 404 from 405.

type RunnerInfo

type RunnerInfo struct {
	Configured string `json:"configured"`
	Mode       string `json:"mode"`
}

RunnerInfo separates what was asked for from what is in force, so health stays honest while no runner exists.

type ServiceHost

type ServiceHost interface {
	Route(escapedPath string) (h http.Handler, rest string, ok bool)
}

ServiceHost resolves a request to a running Cloud Run service. It is the same shape as FunctionHost's Route: the front door knows only that something claimed the request.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL