api.proto

syntax = "proto3";

package api;
option go_package = "github.com/dhamith93/SyMon/internal/api";

message Void {

}

message Message {
    string body = 1;
}

// agentVersion and arch are sent by agents that can update themselves,
// updateError when their last try failed. tasks is what the host's tasks
// file lists.
message ServerInfo {
    string serverName = 1;
    string timezone = 2;
    string agentVersion = 3;
    string arch = 4;
    string updateError = 5;
    repeated TaskInfo tasks = 6;
}

// An update an admin asked for. The agent downloads the build from
// downloadUrl, the dashboard, and installs it only when it is signed.
message AgentUpdate {
    string version = 1;
    string downloadUrl = 2;
    int64 requestedAt = 3;
}

// body is field 1 like in Message, so agents from before updates still read it
message PingResponse {
    string body = 1;
    AgentUpdate update = 2;
}

message AgentUpdateRequest {
    repeated string hosts = 1;
    string version = 2;
    string downloadUrl = 3;
    string by = 4;
}

message AgentUpdateResult {
    int32 requested = 1;
}

// Host tasks. A host lists the commands it is willing to run in its own
// tasks file. An admin starts one on the dashboard, and the agent runs it
// only when its file still has that name and command.

message TaskInfo {
    string name = 1;
    string description = 2;
    string command = 3;
    int32 timeoutSeconds = 4;
}

message TaskList {
    repeated TaskInfo tasks = 1;
}

// The agent waits in NextTask for a run an admin asked for
message TaskWait {
    string serverName = 1;
}

// id is 0 when nothing was asked for before the wait ran out. command is
// what the admin saw, for the agent to compare with its file.
message TaskAssignment {
    int64 id = 1;
    string task = 2;
    string command = 3;
}

// output is what the run printed since the last report. done ends the run.
message TaskProgress {
    int64 id = 1;
    string serverName = 2;
    string output = 3;
    bool done = 4;
    int32 exitCode = 5;
    bool timedOut = 6;
    // why the run could not start or finish, empty otherwise
    string error = 7;
    // the run printed more than the agent keeps, and the rest was dropped
    bool truncated = 8;
}

message TaskRunRequest {
    string host = 1;
    string task = 2;
    // the user asking
    string by = 3;
}

// status is queued, running, succeeded, failed, timed_out, expired (not
// picked up in time) or lost (the agent went away). Times are 0 until
// they happen.
message TaskRunInfo {
    int64 id = 1;
    string host = 2;
    string task = 3;
    string command = 4;
    string status = 5;
    string requestedBy = 6;
    int64 requestedAt = 7;
    int64 startedAt = 8;
    int64 finishedAt = 9;
    int32 exitCode = 10;
    string error = 11;
    // only set by TaskRun
    string output = 12;
    // the output went over the limit and the rest was dropped
    bool truncated = 13;
}

message TaskRunsRequest {
    string host = 1;
    int32 limit = 2;
}

message TaskRunList {
    repeated TaskRunInfo runs = 1;
}

message TaskRunQuery {
    int64 id = 1;
}

// Notifications. Admins set up channels on the dashboard, and the collector
// sends alerts to them.

// settingsJson has the secrets blanked, and secretsSet names the ones
// that are stored
message ChannelInfo {
    int64 id = 1;
    string name = 2;
    // email, slack, pagerduty or webhook
    string kind = 3;
    string settingsJson = 4;
    repeated string secretsSet = 5;
    bool isDefault = 6;
    bool skipWarnings = 7;
    bool enabled = 8;
    int64 updatedAt = 9;
    string updatedBy = 10;
    // how its newest notification went, empty without one
    string lastStatus = 11;
    int64 lastAt = 12;
    string lastError = 13;
}

message ChannelList {
    repeated ChannelInfo channels = 1;
}

// id 0 creates a channel. A secret left empty keeps the stored one. The
// name and kind of a channel do not change once it exists.
message SaveChannelRequest {
    int64 id = 1;
    string name = 2;
    string kind = 3;
    string settingsJson = 4;
    bool isDefault = 5;
    bool skipWarnings = 6;
    bool enabled = 7;
    string by = 8;
}

message ChannelRequest {
    int64 id = 1;
    string by = 2;
}

// error is empty when the test message went out
message TestResult {
    bool ok = 1;
    string error = 2;
}

message NotificationInfo {
    int64 id = 1;
    int64 alertId = 2;
    string channel = 3;
    string kind = 4;
    // opened, changed or resolved
    string event = 5;
    int32 severity = 6;
    string subject = 7;
    // pending, sent or failed
    string status = 8;
    int32 attempts = 9;
    string lastError = 10;
    int64 createdAt = 11;
    // 0 until it went out
    int64 sentAt = 12;
    string host = 13;
    string rule = 14;
}

message NotificationsRequest {
    int32 limit = 1;
}

message NotificationList {
    repeated NotificationInfo notifications = 1;
}

message MonitorData {
    string monitorData = 1;
}

// A new host trades a single use token for its own agent key
message EnrollRequest {
    string token = 1;
    string hostName = 2;
    string timezone = 3;
}

message EnrollResponse {
    string hostName = 1;
    string agentKey = 2;
}

// Query API. Times are unix seconds.

message HostSummary {
    string name = 1;
    bool up = 2;
    int64 lastSeen = 3;
    int64 time = 4;
    string os = 5;
    double uptimeSeconds = 6;
    double cpuPct = 7;
    double memUsedPct = 8;
    double swapUsedPct = 9;
    double diskUsedPct = 10;
    double rxBps = 11;
    double txBps = 12;
    int32 activeAlerts = 13;
    // highest severity of the open alerts, 0 when there are none
    int32 worstSeverity = 14;
    // running containers at the latest snapshot
    int32 containers = 15;
    // days until the first disk fills up, unset when none is filling up
    optional double diskFullDays = 16;
    // empty from agents older than versions
    string agentVersion = 17;
    // the agent updates itself when asked
    bool canUpdate = 18;
    // an update asked for and not done yet, empty for none
    string updateVersion = 19;
    int64 updateRequestedAt = 20;
    string updateError = 21;
}

message FleetSummary {
    repeated HostSummary hosts = 1;
}

message HostRequest {
    string host = 1;
}

// snapshotJson is the agent's latest MonitorData
message HostSnapshot {
    string host = 1;
    int64 time = 2;
    string snapshotJson = 3;
    int64 lastSeen = 4;
    bool up = 5;
}

message SeriesRequest {
    string host = 1;
    string metric = 2;
    // label keeps one series, for example a mount point or a custom metric
    string label = 3;
    int64 from = 4;
    int64 to = 5;
    int32 maxPoints = 6;
    // max returns the peak of each bucket instead of the average
    bool max = 7;
}

message Point {
    int64 time = 1;
    double value = 2;
}

message Series {
    string label = 1;
    repeated Point points = 2;
}

message SeriesResponse {
    string metric = 1;
    // source is raw, 1m or 1h
    string source = 2;
    int64 stepSeconds = 3;
    repeated Series series = 4;
}

message ProcessesRequest {
    string host = 1;
    // at returns the newest snapshot at or before this time, 0 for latest
    int64 at = 2;
}

// processesJson holds the CPU and Memory top process lists
message ProcessesResponse {
    int64 time = 1;
    string processesJson = 2;
}

message NameList {
    repeated string names = 1;
}

message AlertsRequest {
    // host limits the list to one host, empty means all
    string host = 1;
    bool openOnly = 2;
    int64 from = 3;
    int64 to = 4;
}

message AlertRecord {
    int64 id = 1;
    string host = 2;
    string rule = 3;
    string metric = 4;
    string target = 5;
    // 1 is warning, 2 is critical
    int32 severity = 6;
    double value = 7;
    int64 startedAt = 8;
    int64 updatedAt = 9;
    // 0 while the alert is open
    int64 resolvedAt = 10;
}

message AlertList {
    repeated AlertRecord alerts = 1;
}

// A disk's growth over the last week and when it fills up at that rate
message DiskForecast {
    string device = 1;
    string mount = 2;
    double usedPct = 3;
    double pctPerDay = 4;
    double bytesPerDay = 5;
    // unset when the disk is not filling up, and noForecast then says why:
    // collecting (history under 24 hours), not_growing, not_steady or
    // over_a_year
    optional double daysToFull = 6;
    string noForecast = 7;
    // hours of history behind the forecast
    int32 samples = 8;
}

message DiskForecastList {
    repeated DiskForecast disks = 1;
}

message ProcessUsageRequest {
    string host = 1;
    int64 from = 2;
    int64 to = 3;
}

// One program's share of the range. Processes with the same name are
// added up per snapshot.
message ProcessUsage {
    string name = 1;
    double cpuAvg = 2;
    double cpuPeak = 3;
    double memAvg = 4;
    double memPeak = 5;
    // share of the snapshots the program was in the top lists
    double seenPct = 6;
}

message ProcessUsageList {
    int32 snapshots = 1;
    // time of the first snapshot in the range
    int64 firstTime = 2;
    repeated ProcessUsage processes = 3;
}

// The newest value of one of a host's custom metrics
message CustomValue {
    string host = 1;
    string name = 2;
    string unit = 3;
    double value = 4;
    int64 time = 5;
}

message SnapshotList {
    repeated HostSnapshot hosts = 1;
    // custom metrics sent in the last 2 days
    repeated CustomValue customMetrics = 2;
}

message EndpointsRequest {
    int64 from = 1;
    int64 to = 2;
}

// An endpoint's newest check up to the end of the range, and how it did
// over the range. name is the endpoint rule's name.
message EndpointStatus {
    string name = 1;
    string url = 2;
    string method = 3;
    int64 time = 4;
    bool ok = 5;
    // 0 when there was no response
    int32 statusCode = 6;
    double latencyMs = 7;
    string error = 8;
    int32 checks = 9;
    double uptimePct = 10;
    // over the checks that got a response
    double avgLatencyMs = 11;
    // when the newest certificate seen expires, 0 without one
    int64 certExpires = 12;
}

message EndpointList {
    repeated EndpointStatus endpoints = 1;
}

message EndpointSeriesRequest {
    string name = 1;
    // latency or availability
    string metric = 2;
    int64 from = 3;
    int64 to = 4;
    int32 maxPoints = 5;
}

// Dashboard login. The dashboard calls these with the shared key.

message Credentials {
    string user = 1;
    string password = 2;
}

// token is only set by Login. role is admin or viewer.
message SessionInfo {
    string token = 1;
    string user = 2;
    int64 expires = 3;
    string role = 4;
}

message ChangePasswordRequest {
    string token = 1;
    string current = 2;
    string newPassword = 3;
}

message SessionRequest {
    string token = 1;
}

message UserStatus {
    bool hasUsers = 1;
}

// An alert rule as the dashboard edits it. ruleJson has the same fields as
// an alerts.json entry.
message AlertRuleInfo {
    int64 id = 1;
    bool enabled = 2;
    string ruleJson = 3;
    int64 updatedAt = 4;
    string updatedBy = 5;
}

message AlertRuleList {
    repeated AlertRuleInfo rules = 1;
}

// id 0 creates a rule. by is the user making the change.
message SaveRuleRequest {
    int64 id = 1;
    bool enabled = 2;
    string ruleJson = 3;
    string by = 4;
}

message RuleRequest {
    int64 id = 1;
    string by = 2;
}

service MonitorDataService {
    // agent
    rpc Enroll(EnrollRequest) returns (EnrollResponse) {}
    rpc HandlePing(ServerInfo) returns (PingResponse) {}
    rpc InitAgent(ServerInfo) returns (Message) {}
    rpc HandleMonitorData(MonitorData) returns (Message) {}
    rpc HandleCustomMonitorData(MonitorData) returns (Message) {}

    // query api
    rpc Fleet(Void) returns (FleetSummary) {}
    rpc Snapshot(HostRequest) returns (HostSnapshot) {}
    rpc QuerySeries(SeriesRequest) returns (SeriesResponse) {}
    rpc Processes(ProcessesRequest) returns (ProcessesResponse) {}
    rpc CustomMetricNames(HostRequest) returns (NameList) {}
    rpc Alerts(AlertsRequest) returns (AlertList) {}
    rpc DiskForecasts(HostRequest) returns (DiskForecastList) {}
    rpc ProcessUsage(ProcessUsageRequest) returns (ProcessUsageList) {}
    // every host's latest snapshot, for the metrics endpoint
    rpc Snapshots(Void) returns (SnapshotList) {}
    rpc Endpoints(EndpointsRequest) returns (EndpointList) {}
    rpc EndpointSeries(EndpointSeriesRequest) returns (SeriesResponse) {}
    // the collector's build, in the body
    rpc Version(Void) returns (Message) {}

    // dashboard login
    rpc Login(Credentials) returns (SessionInfo) {}
    rpc CheckSession(SessionRequest) returns (SessionInfo) {}
    rpc Logout(SessionRequest) returns (Message) {}
    // a logged in user changing their own password
    rpc ChangePassword(ChangePasswordRequest) returns (Message) {}
    // for HTTP basic auth, like Prometheus scraping /metrics
    rpc CheckPassword(Credentials) returns (Message) {}
    // the dashboard stays locked until the first user exists
    rpc HasUsers(Void) returns (UserStatus) {}

    // alert rules. The dashboard only lets admins change them.
    rpc AlertRules(Void) returns (AlertRuleList) {}
    rpc SaveRule(SaveRuleRequest) returns (AlertRuleInfo) {}
    rpc DeleteRule(RuleRequest) returns (Message) {}

    // ask agents to update themselves, from the dashboard
    rpc RequestAgentUpdate(AgentUpdateRequest) returns (AgentUpdateResult) {}

    // host tasks. The agent waits in NextTask and reports how the run goes.
    rpc NextTask(TaskWait) returns (TaskAssignment) {}
    rpc ReportTask(TaskProgress) returns (Message) {}
    // for the dashboard
    rpc HostTasks(HostRequest) returns (TaskList) {}
    rpc RequestTaskRun(TaskRunRequest) returns (TaskRunInfo) {}
    // a host's runs, newest first, without output
    rpc TaskRuns(TaskRunsRequest) returns (TaskRunList) {}
    rpc TaskRun(TaskRunQuery) returns (TaskRunInfo) {}

    // notification channels. The dashboard only lets admins change them.
    rpc NotificationChannels(Void) returns (ChannelList) {}
    rpc SaveChannel(SaveChannelRequest) returns (ChannelInfo) {}
    rpc DeleteChannel(ChannelRequest) returns (Message) {}
    // sends a test message to a saved channel
    rpc TestChannel(ChannelRequest) returns (TestResult) {}
    // the newest notifications, for the dashboard
    rpc RecentNotifications(NotificationsRequest) returns (NotificationList) {}
}