gatewayx

type AuthnMode ¶ added in v0.1.16

type AuthnMode string

AuthnMode describes how the gateway treats authentication at the edge. Resource-level authorization can be declared with accessx.AccessRule and executed by Gateway AccessX or delegated to the downstream IAM AuthzService.

const (
	AuthnModeNone       AuthnMode = "none"
	AuthnModePassive    AuthnMode = "passive"
	AuthnModeVerifyJWT  AuthnMode = "verify_jwt"
	AuthnModeIntrospect AuthnMode = "introspect"
)

type BindFunc ¶ added in v0.1.16

type BindFunc[Req any] func(DispatchRequest, RouteMatch) (Req, error)

BindFunc converts a matched Gateway request into a strongly typed upstream request. Generated code should own this binding so business handlers do not parse HTTP paths, query strings or bodies by hand.

type DispatchOption ¶ added in v0.2.4

type DispatchOption func(*Dispatcher)

DispatchOption configures Dispatcher without forcing all existing callers to understand Gateway authentication internals.

func WithAuthenticator(a authn.Authenticator) DispatchOption

func WithInternalServiceToken(cfg authn.InternalServiceTokenConfig) DispatchOption

type DispatchRequest ¶ added in v0.1.16

type DispatchRequest struct {
	Method  string
	Path    string
	Headers map[string]string
	Body    any
}

DispatchRequest is a transport-neutral request used by validation tests and future Gateway proxy implementations. Real HTTP handlers should adapt to this shape after route matching.

type DispatchResponse ¶ added in v0.1.16

type DispatchResponse struct {
	Status  int
	Headers map[string]string
	Body    any
}

DispatchResponse is a transport-neutral response from an upstream service.

type Dispatcher ¶ added in v0.1.16

type Dispatcher struct {
	Registry      RouteRegistry
	Hosts         StaticHosts
	Invoker       UpstreamInvoker
	Authenticator authn.Authenticator
	InternalToken authn.InternalServiceTokenConfig
}

Dispatcher combines route registry, matcher snapshot, boundary authn policy and upstream invocation.

func NewDispatcher(registry RouteRegistry, hosts StaticHosts, invoker UpstreamInvoker, opts ...DispatchOption) Dispatcher

func (d Dispatcher) Dispatch(ctx context.Context, req DispatchRequest) (DispatchResponse, error)

type EtcdRegistry ¶ added in v0.1.16

type EtcdRegistry struct {
	Store  KVStore
	Prefix string
}

EtcdRegistry stores manifests in an etcd-shaped KV store. The type does not import clientv3 directly so offline builds and unit tests stay lightweight.

func NewEtcdRegistry(store KVStore, prefix string) *EtcdRegistry

func (r *EtcdRegistry) ListRoutes() []GatewayRoute

func (r *EtcdRegistry) RegisterManifest(manifest Manifest) error

type GatewayAPIObjectSink ¶ added in v0.2.4

type GatewayAPIObjectSink interface {
	ApplyGatewayAPIObjects(ctx context.Context, objects []KubernetesObject) error
}

type GatewayAPIOptions ¶ added in v0.2.4

type GatewayAPIOptions struct {
	Namespace   string
	GatewayName string
	Hostnames   []string
}

type GatewayAPIPublisher ¶ added in v0.2.4

type GatewayAPIPublisher struct {
	Sink    GatewayAPIObjectSink
	Options GatewayAPIOptions
}

func NewGatewayAPIPublisher(sink GatewayAPIObjectSink, opts GatewayAPIOptions) GatewayAPIPublisher

func (p GatewayAPIPublisher) PublishManifest(ctx context.Context, manifest Manifest) error

type GatewayPolicy ¶ added in v0.1.16

type GatewayPolicy struct {
	Exposure             accessv1.Exposure
	AuthnMode            AuthnMode
	ForwardAuthorization bool
	Timeout              time.Duration

	// Profiles is an optional publication profile list such as public, internal,
	// or ops. Empty means deployment-time filters derive behavior from Exposure.
	Profiles []string

	// Tags are optional governance labels such as skill, admin, debug, dtm.
	Tags []string
}

GatewayPolicy is the boundary-governance slice of a route policy. Business resource authorization is declared separately on GatewayRoute.Access using accessx.AccessRule so the gateway can remain provider-neutral.

func (p GatewayPolicy) EffectiveAuthnMode() AuthnMode

type GatewayRoute ¶ added in v0.1.16

type GatewayRoute struct {
	ID       string
	Method   string
	Path     string
	Upstream UpstreamRef
	Gateway  GatewayPolicy

	// Access is the optional provider-neutral authn/authz/audit declaration for
	// this route. Gateways may execute it directly through accessx.Guard or
	// forward it to IAM AuthzService depending on deployment mode.
	Access accessx.AccessRule
}

GatewayRoute is generated from google.api.http + aisphere.access.v1.policy.

type HandlerFunc ¶

type HandlerFunc = httpx.HandlerFunc

HandlerFunc is the Kernel HTTP business handler.

type InternalClaims ¶

type InternalClaims struct {
	Issuer          string          `json:"iss"`
	Audience        string          `json:"aud"`
	Subject         string          `json:"sub"`
	Actor           authn.Principal `json:"actor"`
	RequestID       string          `json:"request_id,omitempty"`
	AuthzDecisionID string          `json:"authz_decision_id,omitempty"`
	IssuedAt        int64           `json:"iat"`
	ExpiresAt       int64           `json:"exp"`
	JWTID           string          `json:"jti"`
}

InternalClaims is the signed Gateway-to-service identity envelope.

type InternalJWT ¶

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

InternalJWT signs and verifies compact HS256 JWTs without adding a new public dependency. It is meant for Gateway -> internal service calls; external OIDC tokens should still be verified by the IdP/OIDC adapter.

func NewInternalJWT(issuer string, secret []byte, ttl time.Duration) *InternalJWT

func (j *InternalJWT) Sign(audience string, actor authn.Principal, requestID, decisionID string, now time.Time) (string, error)

func (j *InternalJWT) Verify(token, audience string, now time.Time) (InternalClaims, error)

type InvokerRegistry ¶ added in v0.1.16

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

InvokerRegistry routes matched Gateway operations to generated operation invokers. It implements UpstreamInvoker so Dispatcher can use it directly.

func NewInvokerRegistry() *InvokerRegistry

func (r *InvokerRegistry) Invoke(ctx context.Context, match RouteMatch, req DispatchRequest, target string) (DispatchResponse, error)

func (r *InvokerRegistry) Register(operation string, invoker OperationInvoker) error

type KVStore ¶ added in v0.1.16

type KVStore interface {
	Put(ctx context.Context, key string, value []byte) error
	DeletePrefix(ctx context.Context, prefix string) error
	ListPrefix(ctx context.Context, prefix string) (map[string][]byte, error)
}

KVStore is the small etcd-like contract Gateway needs. Production should adapt this to clientv3 under gatewayx/etcd or an etcdx.Store; tests can use MemoryKVStore. Kernel business packages must not use raw etcd clients.

type KubernetesObject ¶ added in v0.2.4

type KubernetesObject struct {
	APIVersion string         `json:"apiVersion"`
	Kind       string         `json:"kind"`
	Metadata   ObjectMeta     `json:"metadata"`
	Spec       map[string]any `json:"spec"`
}

func RenderGatewayAPIObjects(manifest Manifest, opts GatewayAPIOptions) ([]KubernetesObject, error)

type Manifest ¶ added in v0.1.16

type Manifest struct {
	Service   string
	Namespace string
	Routes    []GatewayRoute
}

Manifest is the route artifact a service publishes into the route registry.

func FilterManifest(manifest Manifest, filter RouteFilter) Manifest

type ManifestPublisher ¶ added in v0.2.4

type ManifestPublisher interface {
	PublishManifest(ctx context.Context, manifest Manifest) error
}

ManifestPublisher is the provider-neutral route publication boundary.

Implementations may store generated manifests in the legacy RouteRegistry shape, render/apply Kubernetes Gateway API resources, or forward to another control plane. The important boundary is that serverx only publishes generated Gateway manifests; it does not know whether the target is etcd or Kubernetes.

func NewManifestPublisher(cfg PublisherConfig) (ManifestPublisher, error)

type Matcher ¶ added in v0.1.16

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

Matcher resolves HTTP method/path to a GatewayRoute. It intentionally keeps a small surface so an etcd route controller can swap snapshots atomically.

func NewMatcher(routes []GatewayRoute) Matcher

func (m Matcher) Match(method, path string) (RouteMatch, bool)

type MemoryGatewayAPIObjectSink ¶ added in v0.2.4

type MemoryGatewayAPIObjectSink struct {
	Objects []KubernetesObject
}

func (s *MemoryGatewayAPIObjectSink) ApplyGatewayAPIObjects(ctx context.Context, objects []KubernetesObject) error

type MemoryKVStore ¶ added in v0.1.16

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

MemoryKVStore is an in-memory KVStore for tests. It mirrors etcd prefix semantics closely enough for Gateway route registry validation.

func NewMemoryKVStore() *MemoryKVStore

func (s *MemoryKVStore) DeletePrefix(ctx context.Context, prefix string) error

func (s *MemoryKVStore) ListPrefix(ctx context.Context, prefix string) (map[string][]byte, error)

func (s *MemoryKVStore) Put(ctx context.Context, key string, value []byte) error

type MemoryRegistry ¶ added in v0.1.16

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

MemoryRegistry is a local/demo route registry. It mirrors the etcd registry shape without introducing an external dependency into unit tests.

func NewMemoryRegistry() *MemoryRegistry

func (r *MemoryRegistry) ListRoutes() []GatewayRoute

func (r *MemoryRegistry) RegisterManifest(manifest Manifest) error

type MemorySessionStore ¶

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

MemorySessionStore is a development and test session store. Production gateways should implement SessionStore with Redis.

func NewMemorySessionStore() *MemorySessionStore

func (s *MemorySessionStore) Delete(_ context.Context, id string) error

func (s *MemorySessionStore) Get(_ context.Context, id string) (Session, error)

func (s *MemorySessionStore) Set(_ context.Context, session Session) error

type ObjectMeta ¶ added in v0.2.4

type ObjectMeta struct {
	Name      string            `json:"name"`
	Namespace string            `json:"namespace,omitempty"`
	Labels    map[string]string `json:"labels,omitempty"`
}

type OperationInvoker ¶ added in v0.1.16

type OperationInvoker interface {
	InvokeOperation(ctx context.Context, match RouteMatch, req DispatchRequest) (DispatchResponse, error)
}

OperationInvoker invokes one generated upstream operation.

func GRPCUnaryInvoker[Req any, Reply any](bind BindFunc[Req], call UnaryRPC[Req, Reply], opts ...grpc.CallOption) OperationInvoker

func UnaryInvoker[Req any, Reply any](bind BindFunc[Req], call UnaryHandler[Req, Reply]) OperationInvoker

type ProxyConfig ¶

type ProxyConfig struct {
	Target      string
	StripPrefix string
	AddPrefix   string
	Audience    string
	JWT         *InternalJWT
	Timeout     time.Duration
}

ProxyConfig configures a lightweight reverse proxy for Gateway routes that should remain HTTP-to-HTTP instead of BFF logic -> RPC calls.

type PublisherConfig ¶ added in v0.2.4

type PublisherConfig struct {
	Mode                 RoutePublicationMode
	Registry             RouteRegistry
	GatewayAPIObjectSink GatewayAPIObjectSink
	GatewayAPI           GatewayAPIOptions
}

PublisherConfig chooses the route publication backend. It is intentionally small so business services can keep their config stable while deployments pick either the legacy route registry or the Kubernetes Gateway API path.

type Route ¶

type Route struct {
	Method  string
	Path    string
	Handler HandlerFunc
	Filters []httpx.FilterFunc
	Name    string
}

Route describes a single external Gateway/BFF route.

type RouteFilter ¶ added in v0.2.2

type RouteFilter struct {
	IncludeExposures []accessv1.Exposure
	ExcludeExposures []accessv1.Exposure

	IncludeProfiles []string
	ExcludeProfiles []string
	IncludeTags     []string
	ExcludeTags     []string

	IncludeServices  []string
	ExcludeServices  []string
	IncludePathGlobs []string
	ExcludePathGlobs []string
	IncludeIDs       []string
	ExcludeIDs       []string
}

RouteFilter decides which generated routes are published to a concrete gateway profile. It is intentionally applied at registration time, not only at runtime, so public route registries do not leak internal/debug routes.

func InternalRouteFilter() RouteFilter

func OpsRouteFilter() RouteFilter

func PublicRouteFilter() RouteFilter

func (f RouteFilter) Allow(route GatewayRoute) bool

type RouteMatch ¶ added in v0.1.16

type RouteMatch struct {
	Route  GatewayRoute
	Params map[string]string
}

RouteMatch is the result of matching an external request to a generated route.

type RoutePublicationMode ¶ added in v0.2.4

type RoutePublicationMode string

RoutePublicationMode selects the control-plane backend that receives generated Gateway manifests. Services should publish through ManifestPublisher instead of directly depending on etcd, Kubernetes, Envoy Gateway, or any concrete registry implementation.

const (
	RoutePublicationModeUnspecified RoutePublicationMode = ""
	RoutePublicationModeEtcd        RoutePublicationMode = "etcd"
	RoutePublicationModeGatewayAPI  RoutePublicationMode = "gateway_api"
)

type RouteRegistry ¶ added in v0.1.16

type RouteRegistry interface {
	RegisterManifest(manifest Manifest) error
	ListRoutes() []GatewayRoute
}

RouteRegistry is the provider-neutral gateway route registry contract. Production implementation should be etcd-backed; tests and local demos use MemoryRegistry.

type RouteRegistryPublisher ¶ added in v0.2.4

type RouteRegistryPublisher struct {
	Registry RouteRegistry
}

RouteRegistryPublisher adapts the existing RouteRegistry contract to the new ManifestPublisher interface. This keeps the current etcd/memory route registry path working while allowing new publishers such as Gateway API.

func NewRouteRegistryPublisher(registry RouteRegistry) RouteRegistryPublisher

func (p RouteRegistryPublisher) PublishManifest(ctx context.Context, manifest Manifest) error

type Service ¶

type Service struct {
	Name    string
	Prefix  string
	Filters []httpx.FilterFunc
	Routes  []Route
}

Service groups routes under a common prefix and filter chain. It is the runtime shape that a go-zero-like .api generator should target.

type Session ¶

type Session struct {
	ID           string
	Principal    authn.Principal
	AccessToken  string
	RefreshToken string
	IDToken      string
	CSRFToken    string
	CreatedAt    time.Time
	LastSeenAt   time.Time
	ExpiresAt    time.Time
	Attributes   map[string]any
}

Session is a browser/BFF login session. Access and refresh tokens are stored server-side so the browser only receives an opaque HttpOnly cookie.

func (s Session) Expired(now time.Time) bool

type SessionConfig ¶

type SessionConfig struct {
	Store      SessionStore
	CookieName string
	Required   bool
	Touch      bool
}

SessionConfig configures SessionMiddleware.

type SessionStore ¶

type SessionStore interface {
	Get(ctx context.Context, id string) (Session, error)
	Set(ctx context.Context, session Session) error
	Delete(ctx context.Context, id string) error
}

SessionStore persists sessions.

type StaticHosts ¶ added in v0.1.16

type StaticHosts map[string]string

StaticHosts is a validation/local substitute for Kubernetes Service DNS. In production, Gateway should resolve UpstreamRef through Kubernetes Service DNS or EndpointSlice, not through a custom registry.

func (h StaticHosts) Resolve(upstream UpstreamRef) (string, error)

type UnaryHandler ¶ added in v0.1.16

type UnaryHandler[Req any, Reply any] func(context.Context, Req) (Reply, error)

UnaryHandler is the in-process shape used by validation tests and local demos. It mirrors generated gRPC unary clients without requiring a network listener.

type UnaryRPC ¶ added in v0.1.16

type UnaryRPC[Req any, Reply any] func(context.Context, Req, ...grpc.CallOption) (Reply, error)

UnaryRPC is the generated gRPC client method shape, for example SkillServiceClient.GetSkill(ctx, req, opts...).

type UpstreamInvoker ¶ added in v0.1.16

type UpstreamInvoker interface {
	Invoke(ctx context.Context, match RouteMatch, req DispatchRequest, target string) (DispatchResponse, error)
}

UpstreamInvoker invokes the selected upstream. HTTP reverse proxy, gRPC transcoding and in-memory validation dispatchers can all implement it.

type UpstreamRef ¶ added in v0.1.16

type UpstreamRef struct {
	Service   string
	Namespace string
	Port      int
	Protocol  string
	Operation string
}

UpstreamRef points to a Kubernetes Service in production. Validation tests can resolve it through StaticHosts, mirroring /etc/hosts or local docker-compose.

func (u UpstreamRef) Key() string