Help us shape the future of Go! Take the 2026 Go Developer Survey

gcprun

package
v1.9.0 Latest Latest
Warning

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

 Go to latest Published: Oct 27, 2026 License: MIT Imports: 51 Imported by: 0

README

Cloud Run

Parity grade: B · SDK cloud.google.com/go/run@v1.23.0 · last audited 2026-10-26 (61b7b4a94)

Coverage

Metric Value
PARITY entries audited 20 (20 ok)
Feature families 13 (5 ok, 8 partial)
Known gaps 5
Deferred items 0
Resource leaks clean
Known gaps
  • WorkerPools, Instances, Builds and Locations are not served.
  • Only the first container of a job task is run; sidecars, volumes and probes apply to services only. VPC access, resource limits and readiness probes are stored but not applied.
  • Cloud Storage FUSE, NFS and Cloud SQL volumes are not supported (the revision fails to deploy with a message).
  • The URI is an http .localhost address, not https://*.run.app.
  • update_mask nested paths replace the whole top-level field.

More

Documentation

Index

Constants

View Source 
const (
	// DefaultPort is the dedicated gRPC listener's default TCP port.
	DefaultPort = 8126
	// DefaultIngressPort is the default TCP port of the HTTP listener that fronts deployed services.
	DefaultIngressPort = 8127
	// EngineAuto runs workloads in the container runtime when one is reachable.
	EngineAuto = "auto"
	// EngineNone never starts containers: services stay deployable but serve 503, jobs fail.
	EngineNone = "none"
	// DefaultStartupTimeout bounds how long a new revision may take to accept connections.
	DefaultStartupTimeout = 4 * time.Minute
)
View Source 
const (

	// DefaultIdleTimeout is how long an idle instance above the minimum is kept; Cloud Run documents "up to 15 minutes".
	DefaultIdleTimeout = 15 * time.Minute
)

Variables

View Source 
var ErrNilAppContext = errors.New("gcprun: nil app context")

ErrNilAppContext is returned when Init is called with a nil AppContext.

Functions

This section is empty.

Types

type API 

type API struct {
	Services   runpb.ServicesServer
	Revisions  runpb.RevisionsServer
	Jobs       runpb.JobsServer
	Executions runpb.ExecutionsServer
	Tasks      runpb.TasksServer
}

API groups the Cloud Run Admin servers for in-process callers (dashboard proxy).

type Clock 

type Clock interface {
	Now() time.Time
	NewTimer(d time.Duration) Timer
	AfterFunc(d time.Duration, f func()) Timer
}

Clock abstracts time so idle scale-down, request queueing and probe schedules can be driven by tests.

type ConfigProvider 

type ConfigProvider interface {
	GetGCPRunSettings() Settings
}

ConfigProvider extracts Cloud Run configuration from the AppContext Config.

type Handler 

type Handler struct {
	Backend *InMemoryBackend

	// Port is the gRPC port; IngressPort the HTTP ingress port. Zero binds an ephemeral port, negative disables ingress.
	Port        int
	IngressPort int
	// contains filtered or unexported fields
}

Handler serves the Cloud Run Admin API (v2) on a dedicated gRPC listener and an HTTP ingress for services.

func NewHandler 

func NewHandler(backend *InMemoryBackend) *Handler

NewHandler creates a Handler; callers override the ports from Settings.

func (*Handler) API 

func (h *Handler) API() *API

API exposes the Cloud Run servers for in-process callers.

func (*Handler) Addr 

func (h *Handler) Addr() string

Addr returns the bound gRPC address, or "" before StartWorker.

func (*Handler) ExtractOperation 

func (h *Handler) ExtractOperation(*echo.Context) string

ExtractOperation is unused: requests never reach the shared router.

func (*Handler) ExtractResource 

func (h *Handler) ExtractResource(*echo.Context) string

ExtractResource is unused: requests never reach the shared router.

func (*Handler) GetSupportedOperations 

func (h *Handler) GetSupportedOperations() []string

GetSupportedOperations lists the supported gRPC methods.

func (*Handler) Handler 

func (h *Handler) Handler() echo.HandlerFunc

Handler returns a 404 handler; the real API is gRPC on the dedicated port.

func (*Handler) IngressAddr 

func (h *Handler) IngressAddr() string

IngressAddr returns the bound ingress address, or "" when ingress is off.

func (*Handler) MatchPriority 

func (h *Handler) MatchPriority() int

MatchPriority is irrelevant because RouteMatcher never matches.

func (*Handler) Name 

func (h *Handler) Name() string

Name returns the service name.

func (*Handler) Reset 

func (h *Handler) Reset()

Reset clears all in-memory state.

func (*Handler) Restore 

func (h *Handler) Restore(ctx context.Context, data []byte) error

Restore implements persistence.Persistable by delegating to the backend.

func (*Handler) RouteMatcher 

func (h *Handler) RouteMatcher() service.Matcher

RouteMatcher never matches: Cloud Run runs on its own listeners.

func (*Handler) Shutdown 

func (h *Handler) Shutdown(ctx context.Context)

Shutdown stops both listeners, aborts running workloads and removes their containers.

func (*Handler) Snapshot 

func (h *Handler) Snapshot(ctx context.Context) []byte

Snapshot implements persistence.Persistable by delegating to the backend.

func (*Handler) StartWorker 

func (h *Handler) StartWorker(ctx context.Context) error

StartWorker binds both listeners synchronously so a port conflict is returned to the caller.

type InMemoryBackend 

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

InMemoryBackend holds all Cloud Run state under one lock.

func NewInMemoryBackend 

func NewInMemoryBackend() *InMemoryBackend

NewInMemoryBackend creates an empty backend with no container runtime.

func (*InMemoryBackend) CancelExecution 

func (b *InMemoryBackend) CancelExecution(
	ctx context.Context, in *runpb.CancelExecutionRequest,
) (*longrunningpb.Operation, error)

CancelExecution stops a running execution and returns once its tasks have been cancelled.

func (*InMemoryBackend) Close 

func (b *InMemoryBackend) Close()

Close stops all containers and releases idle connections.

func (*InMemoryBackend) CreateJob 

func (b *InMemoryBackend) CreateJob(in *runpb.CreateJobRequest) (*longrunningpb.Operation, error)

CreateJob stores a job; it is ready immediately.

func (*InMemoryBackend) CreateService 

func (b *InMemoryBackend) CreateService(in *runpb.CreateServiceRequest) (*longrunningpb.Operation, error)

CreateService stores a service with its first revision and deploys it in the background.

func (*InMemoryBackend) DeleteExecution 

func (b *InMemoryBackend) DeleteExecution(
	ctx context.Context, in *runpb.DeleteExecutionRequest,
) (*longrunningpb.Operation, error)

DeleteExecution cancels a running execution and removes it with its tasks.

func (*InMemoryBackend) DeleteJob 

func (b *InMemoryBackend) DeleteJob(in *runpb.DeleteJobRequest) (*longrunningpb.Operation, error)

DeleteJob removes the job with its executions and tasks, cancelling any that still run.

func (*InMemoryBackend) DeleteRevision 

func (b *InMemoryBackend) DeleteRevision(in *runpb.DeleteRevisionRequest) (*longrunningpb.Operation, error)

DeleteRevision removes a revision that is not serving traffic and stops its container.

func (*InMemoryBackend) DeleteService 

func (b *InMemoryBackend) DeleteService(in *runpb.DeleteServiceRequest) (*longrunningpb.Operation, error)

DeleteService removes the service, its revisions and their containers.

func (*InMemoryBackend) Drain 

func (b *InMemoryBackend) Drain()

Drain blocks until every background deployment and execution has finished.

func (*InMemoryBackend) GetExecution 

func (b *InMemoryBackend) GetExecution(name string) (*runpb.Execution, error)

GetExecution returns the named execution.

func (*InMemoryBackend) GetIamPolicy 

func (b *InMemoryBackend) GetIamPolicy(in *iampb.GetIamPolicyRequest) (*iampb.Policy, error)

GetIamPolicy returns the policy of a service or job, empty when none was set.

func (*InMemoryBackend) GetJob 

func (b *InMemoryBackend) GetJob(name string) (*runpb.Job, error)

GetJob returns the named job.

func (*InMemoryBackend) GetRevision 

func (b *InMemoryBackend) GetRevision(name string) (*runpb.Revision, error)

GetRevision returns the named revision.

func (*InMemoryBackend) GetService 

func (b *InMemoryBackend) GetService(name string) (*runpb.Service, error)

GetService returns the named service.

func (*InMemoryBackend) GetTask 

func (b *InMemoryBackend) GetTask(name string) (*runpb.Task, error)

GetTask returns the named task.

func (*InMemoryBackend) IngressHandler 

func (b *InMemoryBackend) IngressHandler() http.Handler

IngressHandler serves <service>-<hash>-<region>.localhost (and <tag>---<that>) by proxying to the container of the revision picked from the service's traffic split.

func (*InMemoryBackend) ListExecutions 

func (b *InMemoryBackend) ListExecutions(in *runpb.ListExecutionsRequest) ([]*runpb.Execution, string, error)

ListExecutions lists a job's executions, newest name last.

func (*InMemoryBackend) ListJobs 

func (b *InMemoryBackend) ListJobs(in *runpb.ListJobsRequest) ([]*runpb.Job, string, error)

ListJobs lists the jobs under a location ordered by name.

func (*InMemoryBackend) ListRevisions 

func (b *InMemoryBackend) ListRevisions(in *runpb.ListRevisionsRequest) ([]*runpb.Revision, string, error)

ListRevisions lists a service's revisions ordered by name.

func (*InMemoryBackend) ListServices 

func (b *InMemoryBackend) ListServices(in *runpb.ListServicesRequest) ([]*runpb.Service, string, error)

ListServices lists the services under a location ordered by name.

func (*InMemoryBackend) ListTasks 

func (b *InMemoryBackend) ListTasks(in *runpb.ListTasksRequest) ([]*runpb.Task, string, error)

ListTasks lists an execution's tasks by index.

func (*InMemoryBackend) Reset 

func (b *InMemoryBackend) Reset()

Reset stops every workload and clears all state.

func (*InMemoryBackend) Restore 

func (b *InMemoryBackend) Restore(ctx context.Context, data []byte) error

Restore loads a snapshot. Work in flight at snapshot time is not resumed: unfinished executions fail, unfinished deployments fail, and revisions start their containers again on first request.

func (*InMemoryBackend) RunJob 

func (b *InMemoryBackend) RunJob(in *runpb.RunJobRequest) (*longrunningpb.Operation, error)

RunJob starts an execution of the job and returns an operation that resolves when it completes.

func (*InMemoryBackend) SetClock 

func (b *InMemoryBackend) SetClock(c Clock)

SetClock replaces the time source; nil restores the wall clock.

func (*InMemoryBackend) SetIamPolicy 

func (b *InMemoryBackend) SetIamPolicy(in *iampb.SetIamPolicyRequest) (*iampb.Policy, error)

SetIamPolicy replaces the policy of a service or job; a non-empty etag must match the stored policy.

func (*InMemoryBackend) SetIdleTimeout 

func (b *InMemoryBackend) SetIdleTimeout(d time.Duration)

SetIdleTimeout sets how long an idle instance above the revision's minimum is kept before it scales to zero.

func (*InMemoryBackend) SetIngressPort 

func (b *InMemoryBackend) SetIngressPort(p int)

SetIngressPort records the bound ingress port used to build service URIs.

func (*InMemoryBackend) SetLogSink 

func (b *InMemoryBackend) SetLogSink(sink gcpserve.LogSink)

SetLogSink wires Cloud Logging: container output and ingress requests are written to sink; nil disables it.

func (*InMemoryBackend) SetOnClose 

func (b *InMemoryBackend) SetOnClose(fn func())

SetOnClose registers a hook run by Close after every container is stopped.

func (*InMemoryBackend) SetPortPool 

func (b *InMemoryBackend) SetPortPool(p PortPool)

SetPortPool wires the host port source for published service containers.

func (*InMemoryBackend) SetProber 

func (b *InMemoryBackend) SetProber(p Prober)

SetProber replaces the probe executor (tests inject one); nil restores the network prober.

func (*InMemoryBackend) SetRunContext 

func (b *InMemoryBackend) SetRunContext(ctx context.Context)

SetRunContext sets the context workloads run under; cancel it to abort them.

func (*InMemoryBackend) SetRuntime 

func (b *InMemoryBackend) SetRuntime(fn func() (Runner, error))

SetRuntime wires the container runtime source; nil disables workloads.

func (*InMemoryBackend) SetSecretResolver 

func (b *InMemoryBackend) SetSecretResolver(fn SecretResolver)

SetSecretResolver wires Secret Manager for secret environment variables and secret volumes.

func (*InMemoryBackend) SetStartupTimeout 

func (b *InMemoryBackend) SetStartupTimeout(d time.Duration)

SetStartupTimeout bounds how long a revision may take to accept connections.

func (*InMemoryBackend) Snapshot 

func (b *InMemoryBackend) Snapshot(ctx context.Context) []byte

Snapshot serialises all resources; containers and in-flight work are not part of it.

func (*InMemoryBackend) TestIamPermissions 

func (b *InMemoryBackend) TestIamPermissions(
	in *iampb.TestIamPermissionsRequest,
) (*iampb.TestIamPermissionsResponse, error)

TestIamPermissions reports the requested permissions that apply to the resource type as granted: the emulator performs no authorization.

func (*InMemoryBackend) UpdateJob 

func (b *InMemoryBackend) UpdateJob(in *runpb.UpdateJobRequest) (*longrunningpb.Operation, error)

UpdateJob applies the masked fields and bumps the job's generation.

func (*InMemoryBackend) UpdateService 

func (b *InMemoryBackend) UpdateService(in *runpb.UpdateServiceRequest) (*longrunningpb.Operation, error)

UpdateService applies the masked fields; a changed template deploys a new revision.

type PortPool 

type PortPool interface {
	Acquire(label string) (int, error)
	Release(port int) error
}

PortPool hands out host ports for published containers.

type ProbeKind 

type ProbeKind string

ProbeKind selects how a Prober checks a container. 

const (
	ProbeHTTP ProbeKind = "http"
	ProbeTCP  ProbeKind = "tcp"
	ProbeGRPC ProbeKind = "grpc"
)

Probe kinds, matching the Probe.probe_type oneof.

type ProbeTarget 

type ProbeTarget struct {
	Headers       http.Header
	Kind          ProbeKind
	Container     string
	Path          string
	Service       string
	Port          int
	ContainerPort int
	Timeout       time.Duration
}

ProbeTarget describes one probe attempt. Port is the host port that reaches ContainerPort in the instance.

type Prober 

type Prober interface {
	Probe(ctx context.Context, t ProbeTarget) error
}

Prober runs a single probe attempt; a nil error means the probe passed.

type Provider 

type Provider struct{}

Provider implements service.Provider for Google Cloud Run. It serves gRPC on its own listener (see Handler.StartWorker) and never matches on the shared AWS router.

func (*Provider) Init 

func (p *Provider) Init(ctx *service.AppContext) (service.Registerable, error)

Init creates the backend and handler; the ports are bound in StartWorker.

func (*Provider) Name 

func (p *Provider) Name() string

Name returns the service provider name.

type Runner 

type Runner interface {
	CreateAndStart(ctx context.Context, spec container.Spec) (string, error)
	StopAndRemove(ctx context.Context, containerID string) error
}

Runner is the slice of the container runtime that Cloud Run workloads need.

type SecretResolver 

type SecretResolver func(versionName string) ([]byte, error)

SecretResolver returns the payload of a Secret Manager version resource name (projects/{p}/secrets/{s}/versions/{v}).

type Settings 

type Settings struct {
	Engine string `` //nolint:lll // config struct tags are intentionally verbose
	/* 202-byte string literal not displayed */
	Port int `` //nolint:lll // config struct tags are intentionally verbose
	/* 214-byte string literal not displayed */
	IngressPort int `` //nolint:lll // config struct tags are intentionally verbose
	/* 248-byte string literal not displayed */
	StartupTimeout time.Duration `` //nolint:lll // config struct tags are intentionally verbose
	/* 196-byte string literal not displayed */
}

Settings holds service-level configuration, embedded in the root CLI command as CLI.GCPRun.

func DefaultSettings 

func DefaultSettings() Settings

DefaultSettings returns the settings used when no ConfigProvider is available.

type Timer 

type Timer interface {
	C() <-chan time.Time
	Stop() bool
}

Timer is the slice of *time.Timer that scaling and probing use.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.