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

ociapigateway

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

README

OCI API Gateway

Parity grade: B · SDK github.com/oracle/oci-go-sdk/v65@v65.126.2 · last audited 2026-10-29 (3b8d909be)

Coverage

Metric Value
PARITY entries audited 22 (19 ok, 3 partial)
Feature families 13 (6 ok, 7 partial)
Known gaps 10
Deferred items 0
Resource leaks unknown
Known gaps
  • Not routed: AddGatewayLock/RemoveGatewayLock (and deployment/certificate equivalents), CancelWorkRequest, the APIs, SDKs, subscribers and usage-plans resource families. Locks supplied at create are stored and echoed but never enforced.
  • Gateways report no ipAddresses and the IPv4/IPv6 address configuration objects are ignored; the subnet is only checked for existence (public gateways are not required to sit in a public subnet).
  • Unverified, chosen by the emulator: route precedence between overlapping paths, trailing-slash handling, 405 with Allow for a method mismatch, the 200 status of CORS preflight answers, the data plane error body shape, Retry-After on 429, default HTTP backend timeouts (60 s connect, 10 s read, 10 s send, applied as one overall deadline), the order filter then rename then set for transformations, isRequired defaulting to true for verifyClaims, JWT tokenHeader defaulting to Authorization with scheme Bearer, a missing optional claim passing.
  • Unverified, from memory: the CUSTOM_AUTHENTICATION function request/response contract (TOKEN and USER_DEFINED payloads, active/scope/wwwAuthenticate fields), 502 for a failing function, and that tokenHeader values are passed to the authorizer without the scheme.
  • CORS allowedOrigins match '*' or the exact origin string; Oracle's wildcard hostnames in origins are not expanded. Routes of one deployment share the deployment CORS policy unless they carry their own.
  • The data plane is plain HTTP on the emulator listener: gateway certificates are validated and stored but no TLS is terminated, deployment endpoints use the https:// form that does not resolve locally, and PRIVATE gateways are served exactly like PUBLIC ones.
  • Mutual TLS, usage plans, dynamic authentication, request validations, response caching, OAuth2 backends and token introspection (REMOTE_DISCOVERY) are rejected with 400; access and execution log policies are stored but nothing is written to OCI Logging.
  • No separate connect/send timeout enforcement, no retries, no streaming flush; request bodies are buffered up to 10 MiB.
  • opc-retry-token idempotency, IAM policy checks, resource principals and instance principals are not applied; only API-key signatures are verified. Tag values are stored verbatim and systemTags are never set.
  • The dashboard has no OCI API Gateway page.

More

Documentation

Index

Constants

View Source 
const DefaultPort = 8163

DefaultPort is the dedicated listener's default TCP port.

View Source 
const (
	// Region is the fixed region baked into emulated OCIDs and gateway hostnames.
	Region = "us-ashburn-1"
)

Variables

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

ErrDestinationNotPermitted is returned when a backend resolves outside the permitted network range.

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

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

View Source 
var ErrSnapshotNull = errors.New("ociapigateway: null entry in snapshot")

ErrSnapshotNull is returned when a snapshot contains a null entry.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	Code    string
	Message string
	Status  int
}

APIError is an OCI error response: HTTP status plus the `code` and `message` body fields.

func (*APIError) Error 

func (e *APIError) Error() string

type Certificate 

type Certificate struct {
	TimeCreated       time.Time       `json:"timeCreated"`
	TimeUpdated       time.Time       `json:"timeUpdated"`
	TimeNotValidAfter time.Time       `json:"timeNotValidAfter"`
	Tags              Tags            `json:"tags"`
	TransitionAt      *time.Time      `json:"transitionAt,omitempty"`
	Locks             json.RawMessage `json:"locks,omitempty"`
	ID                string          `json:"id"`
	CompartmentID     string          `json:"compartmentId"`
	DisplayName       string          `json:"displayName"`
	CertPEM           string          `json:"certificate"`
	Intermediate      string          `json:"intermediateCertificates,omitempty"`
	State             string          `json:"state"`
	Etag              string          `json:"etag"`
	SubjectNames      []string        `json:"subjectNames"`
}

Certificate is a TLS certificate usable by a gateway.

type CertificateWire 

type CertificateWire struct {
	TimeCreated       time.Time                 `json:"timeCreated"`
	TimeUpdated       time.Time                 `json:"timeUpdated"`
	TimeNotValidAfter time.Time                 `json:"timeNotValidAfter"`
	DefinedTags       map[string]map[string]any `json:"definedTags,omitempty"`
	FreeformTags      map[string]string         `json:"freeformTags,omitempty"`
	Locks             json.RawMessage           `json:"locks,omitempty"`
	ID                string                    `json:"id"`
	CompartmentID     string                    `json:"compartmentId"`
	DisplayName       string                    `json:"displayName"`
	Certificate       string                    `json:"certificate,omitempty"`
	Intermediate      string                    `json:"intermediateCertificates,omitempty"`
	LifecycleState    string                    `json:"lifecycleState"`
	SubjectNames      []string                  `json:"subjectNames"`
}

CertificateWire is the wire form of a certificate.

type ConfigProvider 

type ConfigProvider interface {
	GetOCIAPIGatewaySettings() Settings
}

ConfigProvider extracts OCI API Gateway configuration from the AppContext Config.

type Deployment 

type Deployment struct {
	TimeCreated   time.Time       `json:"timeCreated"`
	TimeUpdated   time.Time       `json:"timeUpdated"`
	Tags          Tags            `json:"tags"`
	TransitionAt  *time.Time      `json:"transitionAt,omitempty"`
	ID            string          `json:"id"`
	GatewayID     string          `json:"gatewayId"`
	CompartmentID string          `json:"compartmentId"`
	PathPrefix    string          `json:"pathPrefix"`
	DisplayName   string          `json:"displayName"`
	State         string          `json:"state"`
	Etag          string          `json:"etag"`
	Locks         json.RawMessage `json:"locks,omitempty"`
	Spec          json.RawMessage `json:"specification"`
}

Deployment is an API deployment on a gateway.

type DeploymentWire 

type DeploymentWire struct {
	TimeCreated    time.Time                 `json:"timeCreated"`
	TimeUpdated    time.Time                 `json:"timeUpdated"`
	DefinedTags    map[string]map[string]any `json:"definedTags,omitempty"`
	FreeformTags   map[string]string         `json:"freeformTags,omitempty"`
	ID             string                    `json:"id"`
	GatewayID      string                    `json:"gatewayId"`
	CompartmentID  string                    `json:"compartmentId"`
	PathPrefix     string                    `json:"pathPrefix"`
	Endpoint       string                    `json:"endpoint"`
	DisplayName    string                    `json:"displayName"`
	LifecycleState string                    `json:"lifecycleState"`
	Locks          json.RawMessage           `json:"locks,omitempty"`
	Specification  json.RawMessage           `json:"specification,omitempty"`
}

DeploymentWire is the wire form of a deployment.

type FunctionInvoker 

type FunctionInvoker interface {
	InvokeFunction(ctx context.Context, functionID string, in FunctionRequest) (FunctionResponse, error)
}

FunctionInvoker invokes an OCI function synchronously; wired to OCI Functions in internal/app.

type FunctionRequest 

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

FunctionRequest is the request an API gateway hands to OCI Functions.

type FunctionResponse 

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

FunctionResponse is the function's reply.

type Gateway 

type Gateway struct {
	TimeCreated   time.Time       `json:"timeCreated"`
	TimeUpdated   time.Time       `json:"timeUpdated"`
	Tags          Tags            `json:"tags"`
	TransitionAt  *time.Time      `json:"transitionAt,omitempty"`
	Locks         json.RawMessage `json:"locks,omitempty"`
	CaBundles     json.RawMessage `json:"caBundles,omitempty"`
	ResponseCache json.RawMessage `json:"responseCache,omitempty"`
	ID            string          `json:"id"`
	CompartmentID string          `json:"compartmentId"`
	EndpointType  string          `json:"endpointType"`
	DisplayName   string          `json:"displayName"`
	SubnetID      string          `json:"subnetId"`
	Hostname      string          `json:"hostname"`
	CertificateID string          `json:"certificateId,omitempty"`
	IPMode        string          `json:"ipMode,omitempty"`
	State         string          `json:"state"`
	Etag          string          `json:"etag"`
	NSGs          []string        `json:"networkSecurityGroupIds,omitempty"`
}

Gateway is an API gateway.

type GatewayWire 

type GatewayWire struct {
	TimeCreated    time.Time                 `json:"timeCreated"`
	TimeUpdated    time.Time                 `json:"timeUpdated"`
	DefinedTags    map[string]map[string]any `json:"definedTags,omitempty"`
	FreeformTags   map[string]string         `json:"freeformTags,omitempty"`
	Locks          json.RawMessage           `json:"locks,omitempty"`
	CaBundles      json.RawMessage           `json:"caBundles,omitempty"`
	ResponseCache  json.RawMessage           `json:"responseCacheDetails,omitempty"`
	ID             string                    `json:"id"`
	CompartmentID  string                    `json:"compartmentId"`
	EndpointType   string                    `json:"endpointType"`
	DisplayName    string                    `json:"displayName"`
	SubnetID       string                    `json:"subnetId"`
	Hostname       string                    `json:"hostname"`
	CertificateID  string                    `json:"certificateId,omitempty"`
	IPMode         string                    `json:"ipMode,omitempty"`
	LifecycleState string                    `json:"lifecycleState"`
	NSGs           []string                  `json:"networkSecurityGroupIds,omitempty"`
}

GatewayWire is the wire form of a gateway.

type Handler 

type Handler struct {
	Backend *InMemoryBackend

	Port        int
	EnforceAuth bool
	// contains filtered or unexported fields
}

Handler serves OCI API Gateway: gateways, deployments, certificates, work requests and the deployed-API data plane.

func NewHandler 

func NewHandler(backend *InMemoryBackend) *Handler

NewHandler creates a Handler; callers override Port and EnforceAuth from Settings.

func (*Handler) ExtractOperation 

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

ExtractOperation returns the operation name for metrics.

func (*Handler) ExtractResource 

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

ExtractResource returns the addressed resource id for metrics.

func (*Handler) GetSupportedOperations 

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

GetSupportedOperations lists the supported operations.

func (*Handler) Handler 

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

Handler returns the Echo handler for all OCIAPIGateway requests.

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: OCIAPIGateway runs on its own listener.

func (*Handler) Shutdown 

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

Shutdown stops the listener and the sweeper.

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.

func (*Handler) Trusted 

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

Trusted returns a handler that skips request-signature verification, for the in-process dashboard proxy.

type InMemoryBackend 

type InMemoryBackend struct {
	Auth *ociauth.Registry
	// contains filtered or unexported fields
}

InMemoryBackend holds every gateway, deployment, certificate and work request under one lock.

func NewInMemoryBackend 

func NewInMemoryBackend() *InMemoryBackend

NewInMemoryBackend creates an empty backend.

func (*InMemoryBackend) ChangeCertificateCompartment 

func (b *InMemoryBackend) ChangeCertificateCompartment(id, ifMatch string, in changeCompartmentIn) (string, error)

ChangeCertificateCompartment moves a certificate.

func (*InMemoryBackend) ChangeDeploymentCompartment 

func (b *InMemoryBackend) ChangeDeploymentCompartment(id, ifMatch string, in changeCompartmentIn) (string, error)

ChangeDeploymentCompartment moves a deployment.

func (*InMemoryBackend) ChangeGatewayCompartment 

func (b *InMemoryBackend) ChangeGatewayCompartment(id, ifMatch string, in changeCompartmentIn) (string, error)

ChangeGatewayCompartment moves a gateway.

func (*InMemoryBackend) Compartments 

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

Compartments lists the distinct compartments that hold gateways, deployments or certificates.

func (*InMemoryBackend) CreateCertificate 

func (b *InMemoryBackend) CreateCertificate(in createCertificateIn) (CertificateWire, string, string, error)

CreateCertificate stores a certificate after validating the PEM material.

func (*InMemoryBackend) CreateDeployment 

func (b *InMemoryBackend) CreateDeployment(in createDeploymentIn) (DeploymentWire, string, string, error)

CreateDeployment creates a deployment in CREATING state.

func (*InMemoryBackend) CreateGateway 

func (b *InMemoryBackend) CreateGateway(in createGatewayIn) (GatewayWire, string, string, error)

CreateGateway creates a gateway in CREATING state and returns it with its work request id.

func (*InMemoryBackend) DeleteCertificate 

func (b *InMemoryBackend) DeleteCertificate(id, ifMatch string) (string, error)

DeleteCertificate starts deleting a certificate that no gateway uses.

func (*InMemoryBackend) DeleteDeployment 

func (b *InMemoryBackend) DeleteDeployment(id, ifMatch string) (string, error)

DeleteDeployment starts deleting a deployment.

func (*InMemoryBackend) DeleteGateway 

func (b *InMemoryBackend) DeleteGateway(id, ifMatch string) (string, error)

DeleteGateway starts deleting a gateway that has no deployments.

func (*InMemoryBackend) GatewayState 

func (b *InMemoryBackend) GatewayState(id string) (string, bool)

GatewayState returns the lifecycle state of a gateway.

func (*InMemoryBackend) GetCertificate 

func (b *InMemoryBackend) GetCertificate(id string) (CertificateWire, string, error)

GetCertificate returns one certificate and its etag.

func (*InMemoryBackend) GetDeployment 

func (b *InMemoryBackend) GetDeployment(id string) (DeploymentWire, string, error)

GetDeployment returns one deployment and its etag.

func (*InMemoryBackend) GetGateway 

func (b *InMemoryBackend) GetGateway(id string) (GatewayWire, string, error)

GetGateway returns one gateway and its etag.

func (*InMemoryBackend) GetWorkRequest 

func (b *InMemoryBackend) GetWorkRequest(id string) (WorkRequestWire, error)

GetWorkRequest returns one work request.

func (*InMemoryBackend) ListCertificates 

func (b *InMemoryBackend) ListCertificates(
	compartment, name, state string, o ListOpts,
) (page.Page[CertificateWire], error)

ListCertificates lists the certificates of a compartment.

func (*InMemoryBackend) ListDeployments 

func (b *InMemoryBackend) ListDeployments(
	compartment, gatewayID, name, state string, o ListOpts,
) (page.Page[DeploymentWire], error)

ListDeployments lists the deployments of a compartment, optionally of one gateway.

func (*InMemoryBackend) ListGateways 

func (b *InMemoryBackend) ListGateways(
	compartment, name, state, certificate string, o ListOpts,
) (page.Page[GatewayWire], error)

ListGateways lists the gateways of a compartment.

func (*InMemoryBackend) ListWorkRequests 

func (b *InMemoryBackend) ListWorkRequests(
	compartment, resourceID string, o ListOpts,
) (page.Page[workRequestSummaryWire], error)

ListWorkRequests lists the work requests of a compartment, optionally for one resource.

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 backend state from a snapshot.

func (*InMemoryBackend) ServeData 

func (b *InMemoryBackend) ServeData(w http.ResponseWriter, r *http.Request)

ServeData serves a request addressed to a deployed API.

func (*InMemoryBackend) SetAllowExternal 

func (b *InMemoryBackend) SetAllowExternal(allow bool)

SetAllowExternal lets HTTP backends and remote JWKS URIs reach non-loopback hosts.

func (*InMemoryBackend) SetClock 

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

SetClock injects the time source used for lifecycle transitions, rate limits and token validation.

func (*InMemoryBackend) SetCompartmentChecker 

func (b *InMemoryBackend) SetCompartmentChecker(fn func(string) bool)

SetCompartmentChecker validates compartmentId arguments against another service (OCI Identity).

func (*InMemoryBackend) SetFunctionInvoker 

func (b *InMemoryBackend) SetFunctionInvoker(fn FunctionInvoker)

SetFunctionInvoker wires OCI Functions for ORACLE_FUNCTIONS_BACKEND and CUSTOM_AUTHENTICATION.

func (*InMemoryBackend) SetSubnetChecker 

func (b *InMemoryBackend) SetSubnetChecker(fn func(string) bool)

SetSubnetChecker validates subnetId arguments against another service (OCI Core).

func (*InMemoryBackend) SetTransition 

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

SetTransition sets how long CREATING, UPDATING and DELETING states last.

func (*InMemoryBackend) Snapshot 

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

Snapshot serialises the backend state, including registered API keys.

func (*InMemoryBackend) Sweep 

func (b *InMemoryBackend) Sweep()

Sweep applies lifecycle transitions against the backend clock.

func (*InMemoryBackend) UpdateCertificate 

func (b *InMemoryBackend) UpdateCertificate(id, ifMatch string, in updateCertificateIn) (string, error)

UpdateCertificate updates the display name and tags.

func (*InMemoryBackend) UpdateDeployment 

func (b *InMemoryBackend) UpdateDeployment(id, ifMatch string, in updateDeploymentIn) (string, error)

UpdateDeployment replaces the specification and/or display name and tags.

func (*InMemoryBackend) UpdateGateway 

func (b *InMemoryBackend) UpdateGateway(id, ifMatch string, in updateGatewayIn) (string, error)

UpdateGateway updates mutable gateway attributes and returns the work request id.

func (*InMemoryBackend) WorkRequestExists 

func (b *InMemoryBackend) WorkRequestExists(id string) error

WorkRequestExists reports whether a work request exists (its error list is always empty).

func (*InMemoryBackend) WorkRequestLogs 

func (b *InMemoryBackend) WorkRequestLogs(id string, o ListOpts) (page.Page[wrLogWire], error)

WorkRequestLogs returns the log entries of a work request.

type ListOpts 

type ListOpts struct {
	SortBy string
	Order  string
	Page   string
	Limit  int
}

ListOpts carries the shared list query parameters.

type Provider 

type Provider struct{}

Provider implements service.Provider for OCI API Gateway. It runs 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
	/* 251-byte string literal not displayed */
	EnforceAuth bool `` //nolint:lll // config struct tags are intentionally verbose
	/* 271-byte string literal not displayed */
	AllowExternalBackend bool `` //nolint:lll // config struct tags are intentionally verbose
	/* 252-byte string literal not displayed */
}

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

func DefaultSettings 

func DefaultSettings() Settings

DefaultSettings returns the settings used when no ConfigProvider is available.

type Tags 

type Tags struct {
	FreeformTags map[string]string         `json:"freeformTags,omitempty"`
	DefinedTags  map[string]map[string]any `json:"definedTags,omitempty"`
}

Tags are the shared freeform and defined tag sets of a resource.

type WorkRequest 

type WorkRequest struct {
	Accepted      time.Time `json:"accepted"`
	FinishAt      time.Time `json:"finishAt"`
	ID            string    `json:"id"`
	Operation     string    `json:"operation"`
	CompartmentID string    `json:"compartmentId"`
	EntityType    string    `json:"entityType"`
	EntityID      string    `json:"entityId"`
	Action        string    `json:"action"`
	Seq           int64     `json:"seq"`
}

WorkRequest records an asynchronous operation.

type WorkRequestWire 

type WorkRequestWire struct {
	TimeAccepted    time.Time        `json:"timeAccepted"`
	TimeStarted     *time.Time       `json:"timeStarted,omitempty"`
	TimeFinished    *time.Time       `json:"timeFinished,omitempty"`
	OperationType   string           `json:"operationType"`
	Status          string           `json:"status"`
	ID              string           `json:"id"`
	CompartmentID   string           `json:"compartmentId"`
	Resources       []wrResourceWire `json:"resources"`
	PercentComplete float32          `json:"percentComplete"`
}

WorkRequestWire is the wire form of a work request.

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.