simulator

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

type CompareOptions struct {
	// Oracle is the path of the oracle.json a run wrote.
	Oracle string
	// Export is the directory tally-engine export --format csv --out wrote.
	Export string
	// Pricing is the path of the pricing model file the run rated with. The
	// model is read from the file rather than from the export, because a CSV
	// export carries no model: it says which quantity was billed and at which
	// amount, and not which dimensions the resource types were held against.
	Pricing string
}

type Config struct {
	// LogLevel is the slog threshold, one of DEBUG, INFO, WARN, or ERROR. Both
	// subcommands read it.
	LogLevel string `env:"TALLY_LOG_LEVEL" envDefault:"INFO"`
	// HTTPAddr is the address the control endpoint binds. It defaults to loopback
	// because the endpoint carries no credential and PUT /clock changes the pace
	// of a run: a simulator on a host beside a control plane would otherwise
	// answer everybody on the management network. A deployment that means to
	// publish the port sets 0.0.0.0, which is what the compose stack does.
	HTTPAddr string `env:"TALLY_SIM_HTTP_ADDR" envDefault:"127.0.0.1"`
	// HTTPPort is the port the control endpoint listens on. It is served only
	// while the simulator publishes, because there is nothing to control once the
	// month is over.
	HTTPPort int `env:"TALLY_SIM_HTTP_PORT" envDefault:"8080"`
	// AMQPURL is the broker the notifications are published to. It carries the
	// broker password, so it supports the *_FILE convention. Empty puts run in
	// file mode, where the month is written out instead of published.
	AMQPURL string `env:"TALLY_SIM_AMQP_URL"`
	// Cloud is read by run alone: it is the salt of every generated identifier
	// and the cloud of events.jsonl. It has no default because a guessed cloud
	// silently books usage to the wrong one.
	Cloud string `env:"TALLY_SIM_CLOUD"`
	// ReportingURL is the Reporting API the projects are registered with. run
	// reads it when --register-projects is on and ignores it otherwise. It must
	// be an absolute https URL, because the api token travels on it;
	// ReportingInsecure is what allows a plaintext one.
	ReportingURL string `env:"TALLY_SIM_REPORTING_URL"`
	// ReportingInsecure allows an http Reporting API. It exists for a simulator
	// and an API on the same machine, and for development; anywhere else it puts
	// an api token of role admin on the wire in cleartext.
	ReportingInsecure bool `env:"TALLY_SIM_REPORTING_INSECURE" envDefault:"false"`
	// APIToken is an api token of role admin, which POST /api/v1/projects and
	// POST /api/v1/projects/{id}/relations demand. It supports the *_FILE
	// convention.
	APIToken string `env:"TALLY_SIM_API_TOKEN"`
	// GardenCloud is the cloud the two Gardener projects are registered under.
	// It has no default, for the reason Cloud has none.
	GardenCloud string `env:"TALLY_SIM_GARDEN_CLOUD"`
	// OTLPURL is the OTLP/HTTP endpoint the traffic and inventory series of a run
	// are pushed to. Empty is a run without a push. It has to be absolute and
	// carry a host, and to be https unless OTLPInsecure allows a plaintext one,
	// because the Basic password travels on it. run reads it alone.
	OTLPURL string `env:"TALLY_SIM_OTLP_URL"`
	// OTLPUser is the Basic user of the push. The endpoint in front of the
	// collector takes Basic auth, so a URL without a user reaches nothing.
	OTLPUser string `env:"TALLY_SIM_OTLP_USER"`
	// OTLPPassword is the Basic password of the push. It supports the *_FILE
	// convention.
	OTLPPassword string `env:"TALLY_SIM_OTLP_PASSWORD"`
	// OTLPInsecure allows an http endpoint. It exists for a simulator and a
	// collector on the same machine, and for development; anywhere else it puts
	// the Basic password on the wire in cleartext.
	OTLPInsecure bool `env:"TALLY_SIM_OTLP_INSECURE" envDefault:"false"`
	// MetricsEnabled serves the inventory on GET /metrics of the control listener
	// while a run publishes, where it stands in for the OpenStack database
	// exporter a deployment scrapes. False registers no route, and the fake
	// OpenStack API then answers that path with its own 404. A Config that never
	// went through Load carries false, which is why a test that needs the
	// endpoint sets it. The variable has no SIM infix because roadmap section 8
	// lists it among the common variables every service reads.
	MetricsEnabled bool `env:"TALLY_METRICS_ENABLED" envDefault:"true"`
}

type Difference struct {
	ResourceType string
	ResourceID   string
	Detail       string
	More         int
	// Faults holds the fault switches that touched the oracle's resource. A
	// difference beside its switches is one the drill's write-up explains in a
	// line, and one without them is a finding about the engine. A resource the
	// export books that the oracle does not hold carries none.
	Faults []string
}

type Faults struct {
	PreExisting, MissingCreate, Duplicates, Reordering, RefusedShapes, HeldBack bool
}

type GardenerProject struct {
	// Name is alpha or beta, the external id of the gardener row.
	Name string
	// TenantID is the ID of the Tenant the shoots run on.
	TenantID string
	// Shoots holds the shoot names, in the order newGardenerProjects lists them.
	Shoots []string
}

type Line struct {
	// Exchange is the exchange the notification belongs on, one of nova,
	// openstack, neutron, glance, octavia, keystone, designate, and barbican.
	// Cinder publishes on openstack.
	Exchange string `json:"exchange"`
	// RoutingKey is the topic the notification was published under.
	RoutingKey string `json:"routing_key"`
	// Body is the oslo envelope as Render produced it, kept as raw JSON so a
	// replay republishes the very bytes the run generated rather than a
	// re-encoding of them.
	Body json.RawMessage `json:"body"`
}

type Month struct {
	// Schedule is what the simulated cloud did: every transition once, sorted by
	// its instant. It is what the oracle and WriteEvents are read from.
	Schedule Schedule
	// Stream is the notifications in publication order, which is what
	// notifications.jsonl holds and what the bus carries. The switches of
	// faults.go move, repeat, and add to it. With every switch off it is the
	// schedule.
	Stream Schedule
	// Held holds the transitions the held-back switch keeps off the bus until a
	// run releases them, in instant order. It is empty unless that switch is on.
	Held Schedule
	// Tenants is every keystone project of the month, the classic tenants first
	// in index order, then the CI tenant, then the Gardener tenants in project
	// order. It is built from the world alone: nothing on the bus carries a
	// tenant's name, and no stream is consulted, so a month with the registry
	// switch off renders exactly the files it rendered before.
	Tenants []Tenant
	// GardenerProjects is the two Gardener projects and the tenant each runs
	// on, in the order newGardenerProjects lists them.
	GardenerProjects []GardenerProject
	Oracle           Oracle
}

type Oracle struct {
	Format     int              `json:"format"`
	Cloud      string           `json:"cloud"`
	Seed       uint64           `json:"seed"`
	PeriodFrom time.Time        `json:"period_from"`
	PeriodTo   time.Time        `json:"period_to"`
	Resources  []OracleResource `json:"resources"`
	Counts     []OracleCount    `json:"counts"`
	// Faults holds the fault switches the month ran with, in FaultNames order.
	// A month nobody passed --faults to states an empty list.
	Faults []string `json:"faults"`
	// Traffic holds one row per instance and per interval of that instance,
	// ordered by resource id and then by From. Run fills it from the metric
	// samples once the month is generated, so buildOracle states an empty list.
	//
	// The rows lie outside OracleInterval on purpose: foldFacts merges two
	// adjacent facts that repeat the state, project and size, and a traffic
	// figure inside the interval would make two mergeable intervals compare
	// unequal and split that fold.
	Traffic []OracleTraffic `json:"traffic"`
}

type OracleCount struct {
	ProjectID string `json:"project_id"`
	EventType string `json:"event_type"`
	Count     int    `json:"count"`
}

type OracleInterval struct {
	From      time.Time      `json:"from"`
	To        time.Time      `json:"to"`
	State     string         `json:"state"`
	ProjectID string         `json:"project_id"`
	Size      map[string]any `json:"size"`
}

type OracleResource struct {
	ResourceType string           `json:"resource_type"`
	ResourceID   string           `json:"resource_id"`
	Workload     string           `json:"workload"`
	Intervals    []OracleInterval `json:"intervals"`
	// Faults holds the fault switches that touched this resource, in FaultNames
	// order. A resource none of them touched states an empty list.
	Faults []string `json:"faults"`
}

type OracleTraffic struct {
	ResourceID   string    `json:"resource_id"`
	From         time.Time `json:"from"`
	To           time.Time `json:"to"`
	EgressBytes  int64     `json:"egress_bytes"`
	IngressBytes int64     `json:"ingress_bytes"`
}

type Progress struct {
	// From and To bound the simulated month, the period the virtual clock runs
	// through.
	From time.Time
	To   time.Time
	// Published is how many notifications the run has published so far, of Total
	// in the whole month.
	Published int
	Total     int
	// Held is how many notifications the held-back switch still keeps off the
	// bus. It is 0 for a run without the switch, and 0 once a release let them
	// out.
	Held int
	// Holding is whether the run waits for a release: true from the moment the
	// last regular notification is on the bus until a release lets the held share
	// out. It is the one signal a caller may poll before releasing, because it is
	// the very state a release acts on, while the counts reach their hold values
	// a moment before the run enters the hold.
	Holding bool
}

type ProjectKey struct{ Cloud, ExternalID string }

type ProjectRegistration struct {
	Platform string
	Key      ProjectKey
	Name     string
	Metadata map[string]any
}

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

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

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

type RegistrationReport struct {
	ProjectsCreated, ProjectsExisting, RelationsCreated, RelationsExisting int
}

type Registrations struct {
	Projects  []ProjectRegistration
	Relations []RelationRegistration
}

type RelationRegistration struct {
	Source, Target ProjectKey
	RelationType   string
	Metadata       map[string]any
	ValidFrom      time.Time
}

type ReplayOptions struct {
	// In is the notifications.jsonl a run wrote.
	In string
	// Factor is how many virtual seconds pass per wall second. Zero is
	// unbounded.
	Factor float64
	// WaitForCollector is how long to wait for a consumer on the collector's
	// queue before the first notification goes out. Zero disables the wait.
	WaitForCollector time.Duration
}

type Report struct {
	// Compared counts every resource examined: the oracle's resources of a
	// priced type whose size a notification states, and the resources the
	// export books that the oracle does not hold.
	Compared int
	// Unpriced counts the oracle's resources per type the model does not price,
	// sorted by type.
	Unpriced []UnpricedType
	// Reconciled counts the oracle's load balancers when the model prices
	// them. They are counted rather than compared: the oracle states the size
	// the cloud holds, the engine bills what the create and the syncs booked,
	// and the two part ways at instants a drill does not control.
	Reconciled int
	// Skipped counts the rated records of another cloud or another platform,
	// which an export of a deployment that bills more than the simulated cloud
	// carries beside the ones this oracle is about.
	Skipped int
	// Differences holds one entry per differing resource, sorted by resource
	// type and then by id.
	Differences []Difference
	// PricingVersion is the version of the model the comparison read, so that a
	// report says which prices the unpriced types were unpriced by.
	PricingVersion string
	// Faults holds the fault switches the month ran with, as its oracle states
	// them.
	Faults []string
}

type RunOptions struct {
	// Period is the billing month to generate, as YYYY-MM.
	Period string
	// Seed decides the shape of the simulated cloud.
	Seed uint64
	// Factor is how many virtual seconds pass per wall second. Zero is
	// unbounded: the month goes out as fast as the broker takes it.
	Factor float64
	// Out is the directory notifications.jsonl, events.jsonl and oracle.json are
	// written to, and held-back.jsonl beside them when a switch holds something
	// back. Empty writes nothing.
	Out string
	// WaitForCollector is how long to wait for a consumer on the collector's
	// queue before the first notification goes out. Zero disables the wait.
	WaitForCollector time.Duration
	// Faults are the switch names of --faults, which ParseFaults reads. Empty is
	// every switch off.
	Faults []string
	// RegisterProjects registers the month's tenants, its Gardener projects, and
	// the infrastructure_tenant relation between each project and its tenant
	// with the Reporting API before the first file is written or the first
	// notification published. What it needs is the environment, which Config
	// checks through ValidateRegistration.
	RegisterProjects bool
	// MetricsInterval is the grid the traffic counters and the inventory are
	// sampled on, counted from the period's start. It is a whole number of
	// seconds, at least 30s and at most 24h; the flag defaults to Ceilometer's
	// polling interval of 300s.
	MetricsInterval time.Duration
}

type Sample struct {
	Name   string
	Labels map[string]string
	Value  int64
	At     time.Time
	Kind   SampleKind
}

type SampleKind int

type Schedule []Transition

type Tenant struct {
	// ID is the keystone project id, the external id of the registry row.
	ID string
	// Name is what the registry row is called; nothing on the bus carries it.
	Name string
	// Workload is workloadClassic, workloadGardener, or workloadCI.
	Workload string
}

type Transition struct {
	// At is the virtual instant the notification is published at. It lies
	// inside the generated month.
	At time.Time
	// EventType is the type the emitting service would use, such as
	// "compute.instance.create.end".
	EventType string
	// Exchange is the notification exchange the type belongs on. A month uses
	// eight: nova, openstack, neutron, glance, octavia, keystone, designate, and
	// barbican. The second is oslo's default, which cinder publishes on because
	// it sets no control_exchange of its own. The collector's default binds
	// nova, neutron, openstack, and glance, and a deployment lists the other
	// four itself.
	Exchange string
	// Billable reports whether the collector's mapping records an event for this
	// notification. It is false on the image.create that precedes an upload,
	// which carries no size yet and is skipped on purpose, and on every
	// transition of the noise catalogue (noise.go).
	Billable bool

	// Workload names which of the three workloads emitted the transition, one of
	// the workload constants. Nothing on the wire carries it: it is what a test
	// and the later reconciliation oracle tell the workloads of one month apart
	// by, since the tenants of a month are otherwise ids alone.
	Workload string
	// MessageID is the oslo message id, which the Reporting API deduplicates on.
	// It is drawn after the month is sorted, so the ids run in the order the
	// notifications are published.
	MessageID string
	// PublisherID names the service instance that emitted the notification.
	PublisherID string
	// ProjectID is the project the request ran in. It becomes both
	// _context_project_id and _context_tenant_id, since services differ in which
	// of the two they set and the collector reads either.
	ProjectID string
	// UserID is the user the request ran as, which becomes _context_user_id.
	UserID string
	// ResourceID is the resource the transition is about. The rendered payload
	// carries it under whatever member the emitting service names it in, so this
	// field is what a test holds the mapping's result against.
	ResourceID string
	// Payload is the service's description of the resource, ready to be
	// marshalled as the notification's payload.
	Payload map[string]any
	// contains filtered or unexported fields
}

type UnpricedType struct {
	ResourceType string
	Resources    int
}