// Package boundaryusage tracks workspace boundary usage for telemetry reporting.

// The design intent is to track trends and rough usage patterns.

//

// Each replica does in-memory usage tracking. Boundary usage is inferred at the

// control plane when workspace agents call the ReportBoundaryLogs RPC. Accumulated

// stats are periodically flushed to a database table keyed by replica ID. Telemetry

// aggregates are computed across all replicas when generating snapshots.

//

// Aggregate Precision:

//

// The aggregated stats represent approximate usage over roughly the telemetry

// snapshot interval, not a precise time window. This imprecision arises because:

//

// - Each replica flushes independently, so their data covers slightly different

// time ranges (varying by up to the flush interval)

// - Unflushed in-memory data at snapshot time rolls into the next period

// - The snapshot captures "data flushed since last reset" rather than "usage

// during exactly the last N minutes"

//

// We accept this imprecision to keep the architecture simple. Each replica

// operates independently and flushes to the database on their own schedule.

// This approach also minimizes database load. The table contains at most one

// row per replica, so flushes are just upserts, and resets only delete N

// rows. There's no accumulation of historical data to clean up. The only

// synchronization is a database lock that ensures exactly one replica reports

// telemetry per period.

//

// Known Shortcomings:

//

// - Unique workspace/user counts may be inflated when the same workspace or

// user connects through multiple replicas, as each replica tracks its own

// unique set

// - Ad-hoc boundary usage in a workspace may not be accounted for e.g. if

// the boundary command is invoked directly with the --log-proxy-socket-path

// flag set to something other than the Workspace agent server.

//

// Implementation:

//

// The Tracker maintains sets of unique workspace IDs and user IDs, plus request

// counters. When boundary logs are reported, Track() adds the IDs to the sets

// and increments request counters.

//

// FlushToDB() writes stats to the database only when there's been new activity

// since the last flush. This prevents stale data from being written after a

// telemetry reset when no new usage occurred. Stats accumulate in memory

// throughout the telemetry period.

//

// A new period is detected when the upsert results in an INSERT (meaning

// telemetry deleted the replica's row). At that point, all in-memory stats are

// reset so they only count usage within the new period.

//

// Below is a sequence diagram showing the flow of boundary usage tracking.

//

// ┌───────┐ ┌───────────────┐ ┌──────────┐ ┌────┐ ┌───────────┐

// │ Agent │ │BoundaryLogsAPI│ │ Tracker │ │ DB │ │ Telemetry │

// └───┬───┘ └───────┬───────┘ └────┬─────┘ └──┬─┘ └─────┬─────┘

// │ │ │ │ │

// │ ReportBoundaryLogs│ │ │ │

// ├──────────────────►│ │ │ │

// │ │ Track(...) │ │ │

// │ ├────────────────►│ │ │

// │ : │ │ │ │

// │ : │ │ │ │

// │ ReportBoundaryLogs│ │ │ │

// ├──────────────────►│ │ │ │

// │ │ Track(...) │ │ │

// │ ├────────────────►│ │ │

// │ │ │ │ │

// │ │ │ FlushToDB │ │

// │ │ ├────────────►│ │

// │ │ │ : │ │

// │ │ │ : │ │

// │ │ │ FlushToDB │ │

// │ │ ├────────────►│ │

// │ │ │ │ │

// │ │ │ │ Snapshot │

// │ │ │ │ interval │

// │ │ │ │◄───────────┤

// │ │ │ │ Aggregate │

// │ │ │ │ & Reset │

package boundaryusage