comparison

package
v0.10.0 Latest Latest
Warning

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

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

Documentation

Overview

Package comparison is a host that serves ONE set of objects through every source krm-stream offers, from one origin, so a page and a measurement driver can compare them under identical objects and identical churn:

  • native: the API server's own LIST and WATCH through a credential-holding /k8s proxy, and conditional merge PATCHes back through it;
  • gateway: krm-full/v1 and krm-spec/v1 streams, each unshared and shared, with host save endpoints for projected editing.

It owns one scratch namespace, a fixed set of Widgets (a CRD with a status subresource) and Secrets, a deterministic workload runner, a forced-disconnect switch and low-cardinality counters. It is an example and a measurement harness, not a library API; see examples/comparison/README.md.

Index

Constants

View Source
const (

	// SessionCookie carries the page's session; SessionHeader carries a driver's, or a page panel
	// that deliberately opens a second identity.
	SessionCookie = "krm-compare-session"
	SessionHeader = "X-Compare-Session"
)

The two sessions this host knows. A real host resolves sessions from its own store; these are fixed so a page and a driver can use them without a login system.

View Source
const (
	WorkloadQuiet            = "quiet"
	WorkloadBurst            = "burst"
	WorkloadChurn            = "churn"
	WorkloadForcedDisconnect = "forced-disconnect"
)

The workload names.

View Source
const WidgetGroup = "e2e.krm-stream.configbutler.io"

WidgetGroup is the Widget CRD's API group.

Variables

View Source
var Routes = []Route{
	{Name: "full", Path: "/stream/full", Projection: gateway.ProjectionFull},
	{Name: "spec", Path: "/stream/spec", Projection: gateway.ProjectionSpec},
	{Name: "full-shared", Path: "/stream/full-shared", Projection: gateway.ProjectionFull, Shared: true},
	{Name: "spec-shared", Path: "/stream/spec-shared", Projection: gateway.ProjectionSpec, Shared: true},
}

Routes are the four gateway routes, in display order.

Workloads lists the names Plan accepts.

Functions

func SecretName

func SecretName(i int) string

SecretName names the i-th Secret.

func WidgetName

func WidgetName(i int) string

WidgetName and SecretName name the fixed objects.

Types

type Config

type Config struct {
	// Cluster is the host's own identity. Every upstream request uses it.
	Cluster *rest.Config
	// NamespacePrefix names the scratch namespace, created by New and deleted by Close.
	NamespacePrefix string
	// Widgets and Secrets size the fixed object set. Defaults 8 and 3.
	Widgets, Secrets int
	// ViewerToken and RefusedToken are the session values the host accepts. The viewer may use
	// every source; the refused session is authenticated but every source refuses it.
	ViewerToken, RefusedToken string
	// ReauthorizeEvery is the gateway's timed recheck interval. Default 5s: short, so a 20-second
	// workload shows the per-subscriber cost of timed checks between its forced reconnects.
	ReauthorizeEvery time.Duration
	// Dist is the built library directory served at /packages/krm-stream/dist/. Page is
	// examples/comparison, served at /examples/comparison/.
	Dist, Page string
}

Config configures a Host.

type Host

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

Host is the comparison host.

func New

func New(ctx context.Context, cfg Config) (*Host, error)

New creates the scratch namespace and the objects, and builds every route. Call Close to delete the namespace.

func (*Host) Close

func (h *Host) Close(ctx context.Context) error

Close closes every downstream connection and deletes the scratch namespace.

func (*Host) Namespace

func (h *Host) Namespace() string

Namespace is the scratch namespace.

func (*Host) ServeHTTP

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

ServeHTTP serves every route.

type Metrics

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

Metrics is the host's own record of what each source cost. Every key is built from constants, a route name, an event type or an HTTP status: never a UID, a user, a namespace or a resourceVersion, so the set of keys is small and fixed by the code, as a real metrics backend needs it to be.

Counters reset with Reset; gauges (what is open right now) do not, because the connections they count outlive any measurement window.

func NewMetrics

func NewMetrics() *Metrics

NewMetrics starts an empty record.

func (*Metrics) Add

func (m *Metrics) Add(key string, n int64)

Add increments a counter.

func (*Metrics) Gauge

func (m *Metrics) Gauge(key string, delta int64)

Gauge moves a gauge by delta.

func (*Metrics) Reset

func (m *Metrics) Reset()

Reset clears the counters and starts a new window. Gauges are kept.

func (*Metrics) Snapshot

func (m *Metrics) Snapshot() Snapshot

Snapshot copies the current values.

type PageConfig

type PageConfig struct {
	Namespace    string   `json:"namespace"`
	Group        string   `json:"group"`
	Widgets      []string `json:"widgets"`
	Secrets      []string `json:"secrets"`
	Routes       []Route  `json:"routes"`
	RefusedToken string   `json:"refusedSession"`
	Workloads    []string `json:"workloads"`
}

PageConfig is what the page needs to address the objects.

type Plan

type Plan struct {
	Request WorkloadRequest `json:"request"`
	Steps   []Step          `json:"steps"`
}

Plan is a request's complete schedule, sorted by time.

func NewPlan

func NewPlan(req WorkloadRequest, widgetCount, secretCount int) (Plan, error)

NewPlan builds the schedule for a request against widgetCount Widgets and secretCount Secrets.

func (Plan) Counts

func (p Plan) Counts() map[StepKind]int

Counts tallies a plan's steps by kind.

type Route

type Route struct {
	Name       string             `json:"name"`
	Path       string             `json:"path"`
	Projection gateway.Projection `json:"projection"`
	Shared     bool               `json:"shared"`
}

Route describes one gateway stream route.

type Snapshot

type Snapshot struct {
	Since     time.Time        `json:"since"`
	ElapsedMs int64            `json:"elapsedMs"`
	Counters  map[string]int64 `json:"counters"`
	Gauges    map[string]int64 `json:"gauges"`
}

Snapshot is the JSON the metrics endpoint serves.

type StateObject

type StateObject struct {
	Kind            string            `json:"kind"`
	UID             string            `json:"uid"`
	Name            string            `json:"name"`
	ResourceVersion string            `json:"resourceVersion"`
	Labels          map[string]string `json:"labels,omitempty"`
	Spec            any               `json:"spec,omitempty"`
	Status          any               `json:"status,omitempty"`
	Data            map[string]any    `json:"data,omitempty"`
}

StateObject is one object as the cluster holds it, for the measurement's correctness gate.

type Step

type Step struct {
	At     time.Duration `json:"atMs"`
	Kind   StepKind      `json:"kind"`
	Object int           `json:"object"`
	Seq    int           `json:"seq"`
}

Step is one scheduled action.

type StepKind

type StepKind string

StepKind is what one step does.

const (
	StepSpec       StepKind = "spec"       // a spec write to a Widget
	StepStatus     StepKind = "status"     // a status-subresource write to a Widget
	StepSecret     StepKind = "secret"     // a Secret value rotation
	StepDisconnect StepKind = "disconnect" // close downstream connections
)

The step kinds.

type WorkloadRequest

type WorkloadRequest struct {
	Name string `json:"name"`
	// DurationMs is how long the schedule runs. Default 20000.
	DurationMs int `json:"durationMs"`
	// Seed picks which objects each write touches. Default 1.
	Seed uint64 `json:"seed"`
	// Rate is the write rate per second: status writes for churn, mixed writes for
	// forced-disconnect, writes per burst for burst. Defaults 10, 4 and 12.
	Rate float64 `json:"rate"`
	// Reconnects is how many forced downstream disconnects every workload includes, spread evenly.
	// Default 2. forced-disconnect adds one every DisconnectEveryMs on top.
	Reconnects int `json:"reconnects"`
	// DisconnectEveryMs is forced-disconnect's period. Default 4000.
	DisconnectEveryMs int `json:"disconnectEveryMs"`
	// Target is which downstream connections a disconnect closes: native, gateway or all. Default all.
	Target string `json:"target"`
}

WorkloadRequest parameterizes a workload. Zero values take the defaults documented on each field.

type WorkloadResult

type WorkloadResult struct {
	Plan   map[StepKind]int `json:"planned"`
	Done   map[StepKind]int `json:"done"`
	Closed int              `json:"connectionsClosed"`
	Errors []string         `json:"errors,omitempty"`
	// SecretRotations is, per Secret name, the resourceVersion of its last successful rotation. A
	// projected store shows a rotation only as a redaction revision under the same key, so this is
	// the version a subscriber must hold to prove it saw the final one.
	SecretRotations map[string]string `json:"secretRotations,omitempty"`
	MaxLateMs       int64             `json:"maxLateMs"`
	ElapsedMs       int64             `json:"elapsedMs"`
	DurationMs      int               `json:"durationMs"`
	Seed            uint64            `json:"seed"`
	Rate            float64           `json:"rate"`
	Reconnects      int               `json:"reconnects"`
	StartedUnix     int64             `json:"startedUnixMs"`
}

WorkloadResult reports what a run actually did.

Directories

Path Synopsis
cmd
compare command
Command compare serves the comparison host: the native /k8s proxy, four gateway stream routes, the save endpoints, the page and its counters, against the kubeconfig's cluster, in a scratch namespace it deletes on exit.
Command compare serves the comparison host: the native /k8s proxy, four gateway stream routes, the save endpoints, the page and its counters, against the kubeconfig's cluster, in a scratch namespace it deletes on exit.

Jump to

Keyboard shortcuts

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