Documentation
¶
Overview ¶
Package gatewayx provides Gateway/BFF building blocks on top of Kernel's existing transportx/http package.
The route registry is a small go-zero-inspired target for generated code: a future kernel api generator can emit []Route and []Service values instead of making business services register routes manually in main.go.
Index ¶
- Constants
- func ClearSessionCookie(w http.ResponseWriter, name string, secure bool)
- func InternalJWTHTTPMiddleware(jwt *InternalJWT, audience string) httpx.FilterFunc
- func InternalJWTStreamClientInterceptor(jwt *InternalJWT, audience string) grpc.StreamClientInterceptor
- func InternalJWTStreamServerInterceptor(jwt *InternalJWT, audience string) grpc.StreamServerInterceptor
- func InternalJWTUnaryClientInterceptor(jwt *InternalJWT, audience string) grpc.UnaryClientInterceptor
- func InternalJWTUnaryServerInterceptor(jwt *InternalJWT, audience string) grpc.UnaryServerInterceptor
- func NewReverseProxy(conf ProxyConfig) (http.Handler, error)
- func NewSessionID() (string, error)
- func RegisterRoutes(router *httpx.Router, routes ...Route) error
- func RegisterServices(parent *httpx.Router, services ...Service) error
- func SessionMiddleware(conf SessionConfig) httpx.FilterFunc
- func SetSessionCookie(w http.ResponseWriter, name string, id string, expires time.Time, secure bool)
- type HandlerFunc
- type InternalClaims
- type InternalJWT
- type MemorySessionStore
- type ProxyConfig
- type Route
- type Service
- type Session
- type SessionConfig
- type SessionStore
Constants ¶
const DefaultSessionCookie = "AISP_SESSION"
Variables ¶
This section is empty.
Functions ¶
func ClearSessionCookie ¶
func ClearSessionCookie(w http.ResponseWriter, name string, secure bool)
ClearSessionCookie clears the browser session cookie.
func InternalJWTHTTPMiddleware ¶
func InternalJWTHTTPMiddleware(jwt *InternalJWT, audience string) httpx.FilterFunc
InternalJWTHTTPMiddleware verifies Gateway-signed internal JWTs on internal HTTP endpoints and injects the actor into authn context. It is intended for backend services that accept Gateway -> service HTTP calls during migration.
func InternalJWTStreamClientInterceptor ¶
func InternalJWTStreamClientInterceptor(jwt *InternalJWT, audience string) grpc.StreamClientInterceptor
InternalJWTStreamClientInterceptor is the streaming counterpart of InternalJWTUnaryClientInterceptor.
func InternalJWTStreamServerInterceptor ¶
func InternalJWTStreamServerInterceptor(jwt *InternalJWT, audience string) grpc.StreamServerInterceptor
InternalJWTStreamServerInterceptor verifies Gateway-signed internal JWTs for backend streaming gRPC services.
func InternalJWTUnaryClientInterceptor ¶
func InternalJWTUnaryClientInterceptor(jwt *InternalJWT, audience string) grpc.UnaryClientInterceptor
InternalJWTUnaryClientInterceptor injects a Gateway-signed internal JWT into outgoing gRPC calls. Use it for Gateway/BFF -> internal service calls when the backend service should trust the gateway rather than browser cookies.
func InternalJWTUnaryServerInterceptor ¶
func InternalJWTUnaryServerInterceptor(jwt *InternalJWT, audience string) grpc.UnaryServerInterceptor
InternalJWTUnaryServerInterceptor verifies Gateway-signed internal JWTs for backend gRPC services.
func NewReverseProxy ¶
func NewReverseProxy(conf ProxyConfig) (http.Handler, error)
NewReverseProxy creates an HTTP reverse proxy with optional internal JWT injection. BFF endpoints should usually call RPC clients directly; this is for pass-through routes such as file downloads or legacy migration windows.
func NewSessionID ¶
NewSessionID returns a URL-safe opaque session id.
func RegisterRoutes ¶
RegisterRoutes registers routes on router.
func RegisterServices ¶
RegisterServices registers route groups under parent. It keeps transportx/http untouched while giving services a generated-code-friendly entry point.
func SessionMiddleware ¶
func SessionMiddleware(conf SessionConfig) httpx.FilterFunc
SessionMiddleware loads a server-side session and injects authn.Principal into request context. Set Required=false for routes that can be anonymous.
func SetSessionCookie ¶
func SetSessionCookie(w http.ResponseWriter, name string, id string, expires time.Time, secure bool)
SetSessionCookie writes the browser session cookie.
Types ¶
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 ¶
func NewInternalJWT(issuer string, secret []byte, ttl time.Duration) *InternalJWT
NewInternalJWT creates a signer/verifier.
func (*InternalJWT) Sign ¶
func (j *InternalJWT) Sign(audience string, actor authn.Principal, requestID, decisionID string, now time.Time) (string, error)
Sign signs claims for audience. Subject defaults to issuer when empty.
func (*InternalJWT) Verify ¶
func (j *InternalJWT) Verify(token, audience string, now time.Time) (InternalClaims, error)
Verify verifies a token and expected audience.
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 ¶
func NewMemorySessionStore() *MemorySessionStore
NewMemorySessionStore creates an in-memory store.
func (*MemorySessionStore) Delete ¶
func (s *MemorySessionStore) Delete(_ context.Context, id string) error
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 Route ¶
type Route struct {
Method string
Path string
Handler HandlerFunc
Filters []httpx.FilterFunc
Name string
}
Route describes a single external Gateway/BFF route.
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.
type SessionConfig ¶
type SessionConfig struct {
Store SessionStore
CookieName string
Required bool
Touch bool
}
SessionConfig configures SessionMiddleware.
Source Files