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

gcpapigateway

package
v1.9.1 Latest Latest
Warning

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

 Go to latest Published: Nov 1, 2026 License: MIT Imports: 53 Imported by: 0

README

API Gateway

Parity grade: B · SDK cloud.google.com/go/apigateway@v1.17.0 · last audited 2026-10-30 (8b70851a3)

Coverage

Metric Value
PARITY entries audited 25 (15 ok, 10 partial)
Feature families 11 (6 ok, 5 partial)
Known gaps 7
Deferred items 0
Resource leaks clean
Known gaps
  • The Cloud Run / Functions gateway-to-backend identity token (Authorization: Bearer ID token, jwt_audience) is not minted: the original Authorization header is moved to X-Forwarded-Authorization and the backend gets none.
  • API keys are not validated against any project or key store (no API Keys or Service Usage emulator); any non-empty key passes, so the 400 invalid-key and 403 API-not-enabled answers cannot occur.
  • gRPC API configs (grpc_services, managed_service_configs), more than one OpenAPI document per config, h2 and WebSocket backends, x-google-allow, x-google-parameter, x-google-model-router, x-google-mcp-tool, AI and MCP blocks, and the 2.0 jwt locations extension are not supported.
  • Whether OpenAPI 2.0 documents without any x-google-backend are rejected at config creation is undocumented (oasv2 page: only address is Required inside the block); the emulator rejects them as it does 3.x. The 3.x docs example gives address without a scheme (myapp.run.app), the emulator requires http(s). The 3.x quota limit unit is undocumented; limits are taken as per project per minute.
  • Data-plane texts not in a primary source: the detail after 429 RESOURCE_EXHAUSTED (from Service Control), 502 for refused destinations (emulator-only), the Gateway-not-found and not-ready answers, and the Envoy JWT messages for header/payload parse failures (jwt_verify_lib has distinct strings; only the three-section case is distinguished).
  • Control-plane error codes and texts (AlreadyExists, FAILED_PRECONDITION for in-use resources, id charset, the global-only rule for APIs and configs, the single CREATING config rule) have no primary text: googleapis apigateway.proto only says ids 'must be unique within scope of the parent resource'.
  • No dashboard page or proxy.

More

Documentation

Index

Constants

View Source 
const DefaultPort = 8146

DefaultPort is the dedicated API Gateway listener's default TCP port: control plane (gRPC and REST) and data plane.

View Source 
const (
	// PathPrefix fronts the path-style data-plane URL: /_apigateway/{project}/{location}/{gateway}/{path}.
	PathPrefix = "/_apigateway/"
)

Variables

View Source 
var ErrDestinationNotPermitted = errors.New(
	"gcpapigateway: destination is outside loopback and external backends are not allowed",
)

ErrDestinationNotPermitted is returned when a backend or JWKS host resolves outside loopback.

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

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

Functions

This section is empty.

Types

type ConfigProvider 

type ConfigProvider interface {
	GetGCPAPIGatewaySettings() Settings
}

ConfigProvider extracts API Gateway configuration from the AppContext Config.

type Handler 

type Handler struct {
	Backend *InMemoryBackend

	Port int
	// contains filtered or unexported fields
}

Handler serves the API Gateway control plane (gRPC and REST) and the gateway data plane on a dedicated listener.

func NewHandler 

func NewHandler(backend *InMemoryBackend) *Handler

NewHandler creates a Handler; callers override Port from Settings.

func (*Handler) API 

func (h *Handler) API() apigatewaypb.ApiGatewayServiceServer

API returns the control-plane server for in-process callers such as the dashboard proxy.

func (*Handler) Addr 

func (h *Handler) Addr() string

Addr returns the bound listener 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 on the dedicated port.

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) OperationsAPI 

func (h *Handler) OperationsAPI() longrunningpb.OperationsServer

OperationsAPI returns the long-running operations server for in-process callers.

func (*Handler) Reset 

func (h *Handler) Reset()

Reset clears all 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: API Gateway runs on its own listener.

func (*Handler) Shutdown 

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

Shutdown stops the listener, forcing a close after a short grace period.

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 the dedicated listener synchronously so a port conflict is returned to the caller.

type InMemoryBackend 

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

InMemoryBackend holds all API Gateway state under one lock.

func NewInMemoryBackend 

func NewInMemoryBackend() *InMemoryBackend

NewInMemoryBackend creates an empty backend on the wall clock.

func (*InMemoryBackend) CancelOperation 

func (b *InMemoryBackend) CancelOperation(name string) (*emptypb.Empty, error)

CancelOperation cancels a running operation: a create is rolled back, a delete is undone and an update keeps its change. Cancelling a finished operation has no effect.

func (*InMemoryBackend) CloseIdleConnections 

func (b *InMemoryBackend) CloseIdleConnections()

CloseIdleConnections releases pooled backend connections.

func (*InMemoryBackend) CreateAPI 

func (b *InMemoryBackend) CreateAPI(in *apigatewaypb.CreateApiRequest) (*longrunningpb.Operation, error)

CreateAPI creates an API in the global location.

func (*InMemoryBackend) CreateAPIConfig 

func (b *InMemoryBackend) CreateAPIConfig(in *apigatewaypb.CreateApiConfigRequest) (*longrunningpb.Operation, error)

CreateAPIConfig creates an API config; an invalid OpenAPI document leaves it FAILED with the operation failed.

func (*InMemoryBackend) CreateGateway 

func (b *InMemoryBackend) CreateGateway(in *apigatewaypb.CreateGatewayRequest) (*longrunningpb.Operation, error)

CreateGateway creates a gateway in a region.

func (*InMemoryBackend) DataPlane 

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

DataPlane serves requests to gateways.

func (*InMemoryBackend) DeleteAPI 

func (b *InMemoryBackend) DeleteAPI(in *apigatewaypb.DeleteApiRequest) (*longrunningpb.Operation, error)

DeleteAPI deletes an API that has no API configs left.

func (*InMemoryBackend) DeleteAPIConfig 

func (b *InMemoryBackend) DeleteAPIConfig(in *apigatewaypb.DeleteApiConfigRequest) (*longrunningpb.Operation, error)

DeleteAPIConfig deletes an API config that no gateway serves.

func (*InMemoryBackend) DeleteGateway 

func (b *InMemoryBackend) DeleteGateway(in *apigatewaypb.DeleteGatewayRequest) (*longrunningpb.Operation, error)

DeleteGateway deletes a gateway.

func (*InMemoryBackend) DeleteOperation 

func (b *InMemoryBackend) DeleteOperation(name string) (*emptypb.Empty, error)

DeleteOperation removes a finished operation.

func (*InMemoryBackend) GetAPI 

func (b *InMemoryBackend) GetAPI(name string) (*apigatewaypb.Api, error)

GetAPI returns one API.

func (*InMemoryBackend) GetAPIConfig 

func (b *InMemoryBackend) GetAPIConfig(in *apigatewaypb.GetApiConfigRequest) (*apigatewaypb.ApiConfig, error)

GetAPIConfig returns one API config; the full view includes the OpenAPI documents.

func (*InMemoryBackend) GetGateway 

func (b *InMemoryBackend) GetGateway(name string) (*apigatewaypb.Gateway, error)

GetGateway returns one gateway.

func (*InMemoryBackend) GetIamPolicy 

func (b *InMemoryBackend) GetIamPolicy(resource string, version int32) (*iampb.Policy, error)

GetIamPolicy returns the policy of a resource at the requested version.

func (*InMemoryBackend) GetLocation 

func (b *InMemoryBackend) GetLocation(name string) (*location.Location, error)

GetLocation returns the global location or a gateway region.

func (*InMemoryBackend) GetOperation 

func (b *InMemoryBackend) GetOperation(name string) (*longrunningpb.Operation, error)

GetOperation returns one operation.

func (*InMemoryBackend) ListAPIConfigs 

func (b *InMemoryBackend) ListAPIConfigs(in *apigatewaypb.ListApiConfigsRequest) (
	*apigatewaypb.ListApiConfigsResponse, error,
)

ListAPIConfigs lists the configs of an API.

func (*InMemoryBackend) ListApis 

func (b *InMemoryBackend) ListApis(in *apigatewaypb.ListApisRequest) (*apigatewaypb.ListApisResponse, error)

ListApis lists the APIs of a project.

func (*InMemoryBackend) ListGateways 

func (b *InMemoryBackend) ListGateways(in *apigatewaypb.ListGatewaysRequest) (
	*apigatewaypb.ListGatewaysResponse, error,
)

ListGateways lists the gateways of a location, or of every location for "-".

func (*InMemoryBackend) ListLocations 

func (b *InMemoryBackend) ListLocations(in *location.ListLocationsRequest) (*location.ListLocationsResponse, error)

ListLocations lists the global location and the gateway regions.

func (*InMemoryBackend) ListOperations 

func (b *InMemoryBackend) ListOperations(in *longrunningpb.ListOperationsRequest) (
	*longrunningpb.ListOperationsResponse, error,
)

ListOperations lists the operations of one location, ordered by name.

func (*InMemoryBackend) MatchesDataPlane 

func (b *InMemoryBackend) MatchesDataPlane(r *http.Request) bool

MatchesDataPlane reports whether a request addresses a gateway, by default hostname or by path prefix.

func (*InMemoryBackend) ProjectIDs 

func (b *InMemoryBackend) ProjectIDs() []string

ProjectIDs lists the projects that own at least one API, config, gateway or operation, sorted.

func (*InMemoryBackend) Reset 

func (b *InMemoryBackend) Reset()

Reset clears all state.

func (*InMemoryBackend) Restore 

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

Restore loads a snapshot, replacing all state.

func (*InMemoryBackend) SetAllowExternal 

func (b *InMemoryBackend) SetAllowExternal(allow bool)

SetAllowExternal lets gateway backends and remote JWKS URIs reach hosts outside loopback.

func (*InMemoryBackend) SetClock 

func (b *InMemoryBackend) SetClock(now func() time.Time)

SetClock replaces the clock lifecycle states, quotas and token validation derive from.

func (*InMemoryBackend) SetIamPolicy 

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

SetIamPolicy replaces a policy; a stale etag aborts the call.

func (*InMemoryBackend) SetTiming 

func (b *InMemoryBackend) SetTiming(t Timing)

SetTiming replaces the operation durations.

func (*InMemoryBackend) Snapshot 

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

Snapshot serialises APIs, API configs, gateways, policies and operations. Quota counters and cached signing keys are not kept.

func (*InMemoryBackend) TestIamPermissions 

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

TestIamPermissions reports the requested API Gateway permissions as granted: the emulator authorises all callers.

func (*InMemoryBackend) UpdateAPI 

func (b *InMemoryBackend) UpdateAPI(in *apigatewaypb.UpdateApiRequest) (*longrunningpb.Operation, error)

UpdateAPI updates the display name and labels of an API.

func (*InMemoryBackend) UpdateAPIConfig 

func (b *InMemoryBackend) UpdateAPIConfig(in *apigatewaypb.UpdateApiConfigRequest) (*longrunningpb.Operation, error)

UpdateAPIConfig updates the display name and labels of an API config.

func (*InMemoryBackend) UpdateGateway 

func (b *InMemoryBackend) UpdateGateway(in *apigatewaypb.UpdateGatewayRequest) (*longrunningpb.Operation, error)

UpdateGateway updates the display name, labels and API config of a gateway.

func (*InMemoryBackend) WaitOperation 

func (b *InMemoryBackend) WaitOperation(ctx context.Context, in *longrunningpb.WaitOperationRequest) (
	*longrunningpb.Operation, error,
)

WaitOperation returns once the operation is done or the timeout passes, whichever comes first.

type Provider 

type Provider struct{}

Provider implements service.Provider for API Gateway. It serves gRPC, REST and the gateway data plane 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 port is bound in StartWorker.

func (*Provider) Name 

func (p *Provider) Name() string

Name returns the service provider name.

type Settings 

type Settings struct {
	Port int `` //nolint:lll // config struct tags are intentionally verbose
	/* 256-byte string literal not displayed */
	AllowExternalBackend bool `` //nolint:lll // config struct tags are intentionally verbose
	/* 308-byte string literal not displayed */
}

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

func DefaultSettings 

func DefaultSettings() Settings

DefaultSettings returns the settings used when no ConfigProvider is available.

type Timing 

type Timing struct {
	Create time.Duration
	Update time.Duration
	Delete time.Duration
}

Timing controls how long create, update and delete operations take on the backend clock.

func DefaultTiming 

func DefaultTiming() Timing

DefaultTiming returns the operation durations used unless a test overrides them.

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.