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

gcpfunctions

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: 47 Imported by: 0

README

Cloud Functions

Parity grade: B · SDK cloud.google.com/go/functions@v1.26.0 · last audited 2026-10-19 (8d369e7be)

Coverage

Metric Value
PARITY entries audited 8 (8 ok)
Feature families 10 (4 ok, 5 partial, 1 gap)
Known gaps 8
Deferred items 0
Resource leaks clean
Known gaps
  • Pub/Sub event-triggered deliveries write container output to Cloud Logging but no run.googleapis.com/requests entry; the Docker log stream is covered by a unit test, not a live daemon run.
  • GEN_1 functions (cloudfunctions.v1 API), repo_source/git_uri builds and Cloud Build are not implemented.
  • Event types other than Pub/Sub messagePublished (Cloud Storage, Firestore, audit logs, custom channels) and event_filters are rejected.
  • secret_environment_variables and secret_volumes are rejected; memory, cpu, concurrency, min/max instances, vpc_connector and ingress_settings are stored but not applied.
  • Functions IAM policy RPCs and the Locations service are not served.
  • GetFunction does not support the revision field; ListFunctions rejects filter and order_by; there is no unreachable list.
  • URLs are http .localhost addresses, not https://*.cloudfunctions.net or *.run.app, and the upload bucket is synthetic rather than a GCS bucket.
  • The container build path (npm/pip/go get at start) needs network access and has only been exercised against a fake runtime.

More

Documentation

Index

Constants

View Source
const (
	// DefaultPort is the dedicated gRPC listener's default TCP port.
	DefaultPort = 8128
	// DefaultIngressPort is the default TCP port of the HTTP listener that fronts deployed functions.
	DefaultIngressPort = 8129
	// EngineAuto runs functions in the container runtime when one is reachable.
	EngineAuto = "auto"
	// EngineNone never starts containers: functions deploy but invocations return 503.
	EngineNone = "none"
	// DefaultStartupTimeout bounds how long a function container may take to accept connections.
	DefaultStartupTimeout = 5 * time.Minute
)
View Source
const (
	// EventTypePubSub is the only event type the emulator delivers.
	EventTypePubSub = "google.cloud.pubsub.topic.v1.messagePublished"
)

Variables

View Source
var ErrNilAppContext = errors.New("gcpfunctions: 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 {
	Functions functionspb.FunctionServiceServer
	// contains filtered or unexported fields
}

API exposes the Functions server for in-process callers (dashboard proxy).

func (*API) Invoke

func (a *API) Invoke(ctx context.Context, name string, in InvokeRequest) (*InvokeResult, error)

Invoke calls the function's HTTP endpoint in-process.

func (*API) Upload

func (a *API) Upload(ctx context.Context, uploadURL string, data []byte) error

Upload stores a source archive in the slot issued by GenerateUploadUrl, bypassing the network.

type ConfigProvider

type ConfigProvider interface {
	GetGCPFunctionsSettings() Settings
}

ConfigProvider extracts Cloud Functions configuration from the AppContext Config.

type EventBus

type EventBus interface {
	GetTopic(name string) (*pubsubpb.Topic, error)
	CreateSubscription(in *pubsubpb.Subscription) (*pubsubpb.Subscription, error)
	DeleteSubscription(name string) error
}

EventBus is the Pub/Sub surface event-triggered functions subscribe through.

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 Functions API (v2) on a dedicated gRPC listener and an HTTP ingress for functions.

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 Functions server 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 Functions 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 Functions state under one lock.

func NewInMemoryBackend

func NewInMemoryBackend() *InMemoryBackend

NewInMemoryBackend creates an empty backend with no container runtime.

func (*InMemoryBackend) Close

func (b *InMemoryBackend) Close()

Close stops all containers and releases idle connections.

func (*InMemoryBackend) CreateFunction

CreateFunction stores a function and deploys it in the background.

func (*InMemoryBackend) DeleteFunction

DeleteFunction removes a function, its container and its trigger subscription in the background.

func (*InMemoryBackend) Drain

func (b *InMemoryBackend) Drain()

Drain blocks until every background deployment has finished.

func (*InMemoryBackend) GenerateDownloadURL

GenerateDownloadURL returns a URL serving the deployed source archive of a function.

func (*InMemoryBackend) GenerateUploadURL

GenerateUploadURL issues a one-shot upload slot in the location's source bucket.

func (*InMemoryBackend) GetFunction

func (b *InMemoryBackend) GetFunction(name string) (*functionspb.Function, error)

GetFunction returns a function.

func (*InMemoryBackend) IngressHandler

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

IngressHandler serves <function>-<hash>-<region>.localhost invocations plus the reserved /_gcf/ endpoints (source upload and download, Pub/Sub push delivery).

func (*InMemoryBackend) ListFunctions

ListFunctions lists functions under a location, or every location with "-".

func (*InMemoryBackend) ListRuntimes

ListRuntimes lists the runtimes the emulator can run.

func (*InMemoryBackend) Reset

func (b *InMemoryBackend) Reset()

Reset stops every function and clears all state.

func (*InMemoryBackend) Restore

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

Restore loads a snapshot. Deployments in flight at snapshot time fail, and containers start again on first use.

func (*InMemoryBackend) SetEventBus

func (b *InMemoryBackend) SetEventBus(e EventBus)

SetEventBus wires the Pub/Sub emulator that event triggers subscribe through.

func (*InMemoryBackend) SetIngressPort

func (b *InMemoryBackend) SetIngressPort(p int)

SetIngressPort records the bound ingress port used to build URLs.

func (*InMemoryBackend) SetLogSink

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

SetLogSink wires Cloud Logging: container output and invocations are written to sink; nil disables it. Only the 2nd-gen environment exists here, so entries use the cloud_run_revision resource.

func (*InMemoryBackend) SetObjectReader

func (b *InMemoryBackend) SetObjectReader(o ObjectReader)

SetObjectReader wires the object store that storage_source archives are read from.

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 function containers.

func (*InMemoryBackend) SetRunContext

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

SetRunContext sets the context containers run under; cancel it to abort starts in flight.

func (*InMemoryBackend) SetRuntime

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

SetRuntime wires the container runtime source; nil disables functions.

func (*InMemoryBackend) SetStartupTimeout

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

SetStartupTimeout bounds how long a function container may take to accept connections.

func (*InMemoryBackend) Snapshot

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

Snapshot serialises all functions and sources; containers are not part of it.

func (*InMemoryBackend) UpdateFunction

UpdateFunction applies the masked fields and redeploys in the background.

type InvokeRequest

type InvokeRequest struct {
	Header http.Header
	Method string
	Path   string
	Body   []byte
}

InvokeRequest is an HTTP call made to a function through the ingress.

type InvokeResult

type InvokeResult struct {
	Header http.Header
	Body   []byte
	Status int
}

InvokeResult is the function's HTTP response; Body is capped at 1 MiB.

type ObjectReader

type ObjectReader interface {
	ReadObject(bucket, object string) ([]byte, error)
}

ObjectReader reads source archives from an object store (the GCS emulator).

type PortPool

type PortPool = gcpserve.PortPool

PortPool hands out host ports for published containers.

type Provider

type Provider struct{}

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

func (*Provider) Init

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 = gcpserve.Runner

Runner is the slice of the container runtime that functions need.

type Settings

type Settings struct {
	Engine string `` //nolint:lll // config struct tags are intentionally verbose
	/* 208-byte string literal not displayed */
	Port int `` //nolint:lll // config struct tags are intentionally verbose
	/* 226-byte string literal not displayed */
	IngressPort int `` //nolint:lll // config struct tags are intentionally verbose
	/* 286-byte string literal not displayed */
	StartupTimeout time.Duration `` //nolint:lll // config struct tags are intentionally verbose
	/* 206-byte string literal not displayed */
}

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

func DefaultSettings

func DefaultSettings() Settings

DefaultSettings returns the settings used when no ConfigProvider is available.

Jump to

Keyboard shortcuts

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