l7

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Index

Constants

View Source
const (
	DefaultSessionIdleTTL     = 24 * time.Hour
	DefaultSessionRenewBefore = time.Hour
	DefaultSessionMaxTTL      = 168 * time.Hour
)

The proxy's own session is sliding: the cookie expires DefaultSessionIdleTTL after the last request, it is re-issued only when less than DefaultSessionRenewBefore of it remains (so an active user costs about one Set-Cookie per hour), and it never lives past DefaultSessionMaxTTL from the handoff or past the link's sess. Mirror the chart (proxy.l7.sessionIdleTTL, sessionRenewBefore, sessionMaxTTL).

View Source
const (
	// MaxMeterKeys bounds distinct (namespace, user, lab) rows per replica.
	MaxMeterKeys  = 50_000
	MaxReportRows = 512
)
View Source
const AuthPath = "/_auth"

AuthPath is the path of the handoff link the platform gives the participant: https://<device>-<code>.<base>/_auth?t=<jwt>. The proxy consumes it and never forwards it to a lab.

View Source
const DefaultHandoffLifetime = 60 * time.Second

DefaultHandoffLifetime bounds exp - iat of a handoff token: it is a one-click link, never a session. Mirrors the chart (proxy.l7.accessTokenMaxTTL): a link is replayable for its lifetime, so it is short.

View Source
const DefaultLiveMaxLifetime = 12 * time.Hour

DefaultLiveMaxLifetime caps how long one request or upgraded (WebSocket) connection may stay open.

View Source
const HandoffAudience = "laboratory-proxy"

HandoffAudience is the aud a handoff token must carry.

Variables

This section is empty.

Functions

func CompactCacheObject added in v1.1.0

func CompactCacheObject(in any) (any, error)

CompactCacheObject preserves only what proxy authorization/routing uses. It owns its copy; objects supplied by informer transforms remain untouched.

func GroupNamespace

func GroupNamespace(groupID string) string

GroupNamespace is the namespace of a LabGroup the platform calls groupID: the group's custom resource is named after the id (encoded when the id is not a valid name). The namespace is the one in the group's status (a group created before the namespace prefix keeps its old one), else the name a new group gets.

func LogReportFailure

func LogReportFailure(log logr.Logger) func(error)

LogReportFailure is the onError of Run: a refusal (Forbidden) or NotFound is how a group namespace looks that the operator has not bound the proxy's role in yet, or that is being deleted. Both pass by themselves, so they are only traced (debug), never an error in the journal.

func ParseAccessKey

func ParseAccessKey(data []byte) (ed25519.PublicKey, bool)

ParseAccessKey reads a PKIX PEM Ed25519 public key.

func PolicyAllows

func PolicyAllows(rules []laboratoryv1alpha1.LabGroupAccessRule, client, lab string) bool

PolicyAllows evaluates the group access policy for one client and lab the way the VPN does: a matching deny wins; without a matching allow the pair is denied by default.

func ReportName

func ReportName(instance string) string

ReportName is the LabTrafficReport of one proxy replica.

func RunLifecycle added in v1.1.0

func RunLifecycle(ctx context.Context, server *http.Server, handler *Handler, reports *ReportWriter, reportEvery, checkEvery time.Duration, serve func() error, onError func(error)) error

RunLifecycle owns report and access workers as well as server shutdown. No final cumulative report is published while request defers can still add data.

func UseGroupReader

func UseGroupReader(r client.Reader)

UseGroupReader makes GroupNamespace read the LabGroup (from the proxy's cache) to find its namespace.

Types

type AccessGroup added in v1.1.0

type AccessGroup struct{ Namespace, Tenant string }

type AccessReader added in v1.1.0

type AccessReader struct{ Reader client.Reader }

AccessReader uses the proxy's compact informer cache, without a permission TTL. A request reads its group once and its route Service once.

func (*AccessReader) Allowed added in v1.1.0

func (a *AccessReader) Allowed(ctx context.Context, namespace, member, labName string) bool

func (*AccessReader) Group added in v1.1.0

func (a *AccessReader) Group(ctx context.Context, id string) (AccessGroup, error)

func (*AccessReader) Route added in v1.1.0

func (a *AccessReader) Route(ctx context.Context, task, namespace string) (AccessRoute, error)

func (*AccessReader) Tenant added in v1.1.0

func (a *AccessReader) Tenant(id string) (string, bool)

type AccessRoute added in v1.1.0

type AccessRoute struct{ URL, Lab string }

type Attribution

type Attribution func(task, groupID string) (lab string, ok bool)

Attribution maps (task, groupID) to the lab a request reaches. It fails when the group does not own that lab.

func ServiceAttribution

func ServiceAttribution(reader client.Reader) Attribution

ServiceAttribution attributes a request to a lab through the web Service the operator creates per exposed device. The host label is the Service name; the Service is read (from the cache) in the namespace of the token's own group, so a token only reaches labs its group owns, and its lab label names the lab. Nothing is decoded from the host itself.

type Authorizer

type Authorizer func(groupID, client, lab string) bool

Authorizer decides whether a LabGroupClient of a group may reach a lab. It is

type BackendResolver

type BackendResolver func(task, groupID string) (string, error)

BackendResolver maps (task, groupID) to a backend URL string.

func ServiceResolver

func ServiceResolver(getServiceProtocol func(task, namespace string) (string, error)) BackendResolver

ServiceResolver builds a BackendResolver that determines backend URL from Service named port. getServiceProtocol(task, namespace) returns the Service's first port name ("http" or "https").

type GroupTenant

type GroupTenant func(groupID string) (tenant string, ok bool)

GroupTenant says which tenant a LabGroup (by the id the platform gave it) belongs to.

func LabGroupTenant

func LabGroupTenant(r client.Reader) GroupTenant

LabGroupTenant tells the tenant of a LabGroup from its tenant label: the group's custom resource is named after the platform's id (encoded when needed). A group created before tenancy has no label and belongs to the default tenant.

type Handler

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

func NewHandler

func NewHandler(keys KeyLookup, secret []byte, baseDomain, cookieName string, resolver BackendResolver) *Handler

func (*Handler) CheckLive

func (h *Handler) CheckLive() int

CheckLive closes every request in flight that must not go on: its deadline passed, the group no longer belongs to the tenant that issued the session, or the group policy no longer lets the client reach the lab. It uses the same checks as a new request, so a lock takes effect on open sessions as soon as the proxy's own copy of the policy does. It returns how many it closed.

func (*Handler) RunLiveCheck

func (h *Handler) RunLiveCheck(ctx context.Context, interval time.Duration)

RunLiveCheck calls CheckLive every interval until ctx ends.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*Handler) Shutdown added in v1.1.0

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

Shutdown stops admissions, cancels HTTP and upgraded connections, and waits for handler defers to settle their meters before the caller publishes.

func (*Handler) WithAccessReader added in v1.1.0

func (h *Handler) WithAccessReader(a *AccessReader) *Handler

func (*Handler) WithAccounting

func (h *Handler) WithAccounting(meter *Meter, attribute Attribution) *Handler

WithAccounting counts requests of a client per lab device. attribute maps the task host to the lab and device; without it nothing is counted.

func (*Handler) WithAuthRateLimit

func (h *Handler) WithAuthRateLimit(rate float64, burst int) *Handler

WithAuthRateLimit limits the handoff path (/_auth), which verifies a signature and may issue a session: per peer address (rate per second and burst), and all peers together at twenty times that. Over it the answer is 429.

func (*Handler) WithAuthorizer

func (h *Handler) WithAuthorizer(authorize Authorizer) *Handler

WithAuthorizer restricts clients to the labs the group policy allows.

func (*Handler) WithGroupTenant

func (h *Handler) WithGroupTenant(g GroupTenant) *Handler

WithGroupTenant tells the owner of a group. A handoff whose issuer is not the tenant of its group is refused, and so is a session cookie whose tenant no longer owns the group. Without it no handoff is accepted.

func (*Handler) WithLimits

func (h *Handler) WithLimits(handoffMax, sessionIdle, sessionRenew, sessionMax time.Duration) *Handler

WithLimits sets the longest accepted handoff token (exp - iat) and the sliding session: its idle lifetime, the remaining time under which the cookie is renewed, and the absolute maximum.

func (*Handler) WithLiveCaps

func (h *Handler) WithLiveCaps(c LiveCaps) *Handler

WithLiveCaps sets how many requests may be in flight in all, per group and per client of a group.

func (*Handler) WithLiveMaxLifetime

func (h *Handler) WithLiveMaxLifetime(d time.Duration) *Handler

WithLiveMaxLifetime sets the longest a request or upgraded connection may last (zero: the default).

func (*Handler) WithReportPreparation added in v1.1.0

func (h *Handler) WithReportPreparation(prepare func(context.Context, string) error) *Handler

type KeyLookup

type KeyLookup func(tenant, keyID string) (ed25519.PublicKey, bool)

KeyLookup finds the access public key a tenant registered under a key id.

func SecretKeys

func SecretKeys(r client.Reader) KeyLookup

SecretKeys looks the access public key of a tenant up in the Secret tenant-<name>-access-keys of the tenants namespace (one entry per key id, the PEM public key). The reader is a cache that watches that namespace, so a key added by the agent works at once and a removed one stops.

type LiveCaps

type LiveCaps struct {
	PerClient, PerGroup, Total int
}

LiveCaps bound the requests in flight: an upgraded (WebSocket) connection or a long download holds a goroutine and buffers for up to LiveMaxLifetime, and one authenticated session could otherwise hold thousands of them. Zero = unlimited.

type Meter

type Meter struct {
	BootID  string
	Started time.Time
	// contains filtered or unexported fields
}

Meter holds only cumulative counters and times. Each namespace has its own index, so publishing one group never scans the traffic of other groups.

func NewMeter

func NewMeter(bootID string, started time.Time) *Meter

func (*Meter) Begin added in v1.1.0

func (m *Meter) Begin(namespace, client, lab string, start time.Time) *RequestMeter

func (*Meter) Ledger

func (m *Meter) Ledger(namespace string) ([]Touch, bool)

func (*Meter) MarkPartial added in v1.1.0

func (m *Meter) MarkPartial()

MarkPartial records an interrupted observation/final drain for every known group.

func (*Meter) Record

func (m *Meter) Record(namespace, client, lab string, start time.Time, responded bool, bytesIn, bytesOut int64)

Record preserves the finished-request API while HTTP wrappers migrate to Begin.

func (*Meter) Restore added in v1.1.0

func (m *Meter) Restore(namespace string, rows []Touch, truncated, partial bool) error

Restore folds a successfully loaded durable baseline once. Traffic counted before the API became available remains additive, never replaced by old rows.

func (*Meter) RetireNamespaces added in v1.1.0

func (m *Meter) RetireNamespaces(active map[string]bool)

RetireNamespaces reclaims disappeared groups only after their live requests finish; these rows cannot be needed by the final publication of active groups.

func (*Meter) Snapshot added in v1.1.0

func (m *Meter) Snapshot(namespace string) (rows []Touch, truncated, partial bool)

type ReportWriter

type ReportWriter struct {
	Reader     client.Reader
	Writer     client.Client
	Meter      *Meter
	Instance   string
	Namespaces func(ctx context.Context) []string
	// contains filtered or unexported fields
}

ReportWriter publishes what the Meter counted, one LabTrafficReport per proxy replica in every group namespace, every interval. The covered span advances on each write even when the group saw no request, which is how an idle team proves it was being watched. The agent relays the reports to the platform.

func (*ReportWriter) Prepare added in v1.1.0

func (w *ReportWriter) Prepare(ctx context.Context, namespace string) error

Prepare restores the previous report before a namespace can admit traffic. Successful preparation is a cheap map lookup; failures remain retryable and cannot publish smaller counters over the durable baseline.

func (*ReportWriter) PrepareAll added in v1.1.0

func (w *ReportWriter) PrepareAll(ctx context.Context) error

func (*ReportWriter) Publish

func (w *ReportWriter) Publish(ctx context.Context, namespace string, now time.Time) error

func (*ReportWriter) PublishAll

func (w *ReportWriter) PublishAll(ctx context.Context, now time.Time, onError func(error))

PublishAll writes the report of every group namespace; a failure of one namespace (for example one that is being deleted) does not stop the others.

func (*ReportWriter) Run

func (w *ReportWriter) Run(ctx context.Context, every time.Duration, onError func(error))

Run publishes periodically. The server lifecycle owns the final write after requests settle.

type RequestMeter added in v1.1.0

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

RequestMeter makes a permitted request observable while it is still active. All updates and End share the Meter lock; duplicate completion is harmless.

func (*RequestMeter) AddIn added in v1.1.0

func (r *RequestMeter) AddIn(n int64)

func (*RequestMeter) AddOut added in v1.1.0

func (r *RequestMeter) AddOut(n int64)

func (*RequestMeter) End added in v1.1.0

func (r *RequestMeter) End()

func (*RequestMeter) Incomplete added in v1.1.0

func (r *RequestMeter) Incomplete()

func (*RequestMeter) Responded added in v1.1.0

func (r *RequestMeter) Responded(now time.Time)

type Touch

type Touch struct {
	Subject, Lab                         string
	Attempts, BytesIn, BytesOut          int64
	FirstSeenMs, LastSeenMs, RespondedMs int64
}

Jump to

Keyboard shortcuts

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