Documentation
¶
Index ¶
- Constants
- func GroupNamespace(groupID string) string
- func LogReportFailure(log logr.Logger) func(error)
- func ParseAccessKey(data []byte) (ed25519.PublicKey, bool)
- func PolicyAllows(rules []laboratoryv1alpha1.LabGroupAccessRule, client, lab string) bool
- func ReportName(instance string) string
- func UseGroupReader(r client.Reader)
- type Attribution
- type Authorizer
- type BackendResolver
- type GroupTenant
- type Handler
- func (h *Handler) CheckLive() int
- func (h *Handler) RunLiveCheck(ctx context.Context, interval time.Duration)
- func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (h *Handler) WithAccounting(meter *Meter, attribute Attribution) *Handler
- func (h *Handler) WithAuthRateLimit(rate float64, burst int) *Handler
- func (h *Handler) WithAuthorizer(authorize Authorizer) *Handler
- func (h *Handler) WithGroupTenant(g GroupTenant) *Handler
- func (h *Handler) WithLimits(handoffMax, sessionIdle, sessionRenew, sessionMax time.Duration) *Handler
- func (h *Handler) WithLiveCaps(c LiveCaps) *Handler
- func (h *Handler) WithLiveMaxLifetime(d time.Duration) *Handler
- type KeyLookup
- type LiveCaps
- type Meter
- type ReportWriter
- type Touch
Constants ¶
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).
const ( // MaxMeterKeys bounds distinct (user, lab) rows per proxy replica. MaxMeterKeys = 50_000 // MaxReportRows bounds one namespace's ledger so the custom resource stays small. MaxReportRows = 512 )
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.
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.
const DefaultLiveMaxLifetime = 12 * time.Hour
DefaultLiveMaxLifetime caps how long one request or upgraded (WebSocket) connection may stay open.
const HandoffAudience = "laboratory-proxy"
HandoffAudience is the aud a handoff token must carry.
Variables ¶
This section is empty.
Functions ¶
func GroupNamespace ¶
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 ¶
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 ¶
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 ¶
ReportName is the LabTrafficReport of one proxy replica.
func UseGroupReader ¶
UseGroupReader makes GroupNamespace read the LabGroup (from the proxy's cache) to find its namespace.
Types ¶
type Attribution ¶
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 ¶
Authorizer decides whether a LabGroupClient of a group may reach a lab. It is
type BackendResolver ¶
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 ¶
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 ¶
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 ¶
RunLiveCheck calls CheckLive every interval until ctx ends.
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 ¶
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 ¶
WithLiveCaps sets how many requests may be in flight in all, per group and per client of a group.
type KeyLookup ¶
KeyLookup finds the access public key a tenant registered under a key id.
func SecretKeys ¶
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 ¶
Meter counts requests per (namespace, user, lab). It keeps counts and times only: no path, query, header, address or user agent ever reaches it.
func (*Meter) Ledger ¶
Ledger returns the rows of one namespace, at most MaxReportRows (the busiest first when it has to cut), and whether anything was dropped.
func (*Meter) Record ¶
func (m *Meter) Record(namespace, client, lab string, start time.Time, responded bool, bytesIn, bytesOut int64)
Record adds one finished request. start is when the request began; responded is set when the lab itself answered (any status), not when the proxy failed to reach it. bytesIn is lab to client, bytesOut client to lab.
type ReportWriter ¶
type ReportWriter struct {
Reader client.Reader
Writer client.Client
Meter *Meter
Instance string
Namespaces func(ctx context.Context) []string
}
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) PublishAll ¶
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.
type Touch ¶
type Touch struct {
Subject, Lab string
Attempts, BytesIn, BytesOut int64
FirstSeenMs, LastSeenMs, RespondedMs int64
}
Touch is one cumulative row: what one LabGroupClient did against one lab device since the proxy replica started. Subject holds the client name, the same value the VPN reports.