aos/starter/starter.fbs

include "aos/util/process_info.fbs";

namespace aos.starter;

enum State : short {
  // Process has recently stopped and is waiting to restart.
  WAITING,

  // Process has forked, waiting to move to RUNNING after verifying it started
  // successfully.
  STARTING,

  // Process is running. pid, id, and last_start_time represent the current
  // running process.
  RUNNING,

  // Process has been sent SIGTERM to nicely stop and starter is waiting for it
  // to exit.
  STOPPING,

  // Process is stopped and will not automatically restart unless sent a command
  STOPPED
}

enum LastStopReason : uint {
  // Application received stop command message
  STOP_REQUESTED,

  // Application received restart command message
  RESTART_REQUESTED,

  // Application terminated - only occurs when starter is shutting down
  TERMINATE,

  // System failed to fork and create a new process
  FORK_ERR,

  // Failed to set parent death handler on child
  SET_PRCTL_ERR,

  // Failed to change to the requested user
  SET_USR_ERR,

  // Failed to execute application - likely due to a missing executable or
  // invalid permissions. This is not reported if an application dies for
  // another reason after it is already running.
  EXECV_ERR,

  // Failed to change to the requested group
  SET_GRP_ERR
}

// Used to indicate the current state of the file being executed, so that we
// can track which executables may need to be restarted.
enum FileState : short {
  // We are not currently in the RUNNING state, so we don't have anything to
  // say. This will be set when the process is STARTING and STOPPING as well,
  // because it may be in a transient state and we don't want to accidentally
  // send out false positives regarding file changes.
  NOT_RUNNING,

  // The currently executing file is the one on disk.
  NO_CHANGE,

  // The file changed at some point between the fork() call and when we
  // entered the RUNNING state, and we aren't currently set up to determine
  // if the executed file is the one currently on disk.
  CHANGED_DURING_STARTUP,

  // The file has changed since it started RUNNING.
  CHANGED,
}

table Status {
  statuses: [ApplicationStatus] (id: 0);
}

table ApplicationStatus {
  name: string (id: 0);

  state: State (id: 1);

  // Last exit code of the process. Has a value of 0 if not started.
  last_exit_code: ubyte (id: 2);

  // Last pid of the process. Could be associated with a different process
  // unless status == RUNNING. Not present if the process has not started.
  pid: uint (id: 3);

  // Unique id of this application and process
  id: uint64 (id: 4);

  // Start time in nanoseconds relative to monotonic clock
  last_start_time: int64 (id: 5);

  // Indicates the reason the application is not running. Only valid if
  // application is STOPPED.
  last_stop_reason: LastStopReason (id: 6);

  // Debug information providing the approximate CPU usage and memory footprint of the process.
  // Populated whenever the process is running (i.e., state != STOPPED). While STOPPING could
  // refer to another process if another process has somehow claimed the application's PID between
  // actually stopping and the parent process receiving the signal indicating that the application
  // finished stopping.
  process_info: util.ProcessInfo (id: 7);

  // Indicates whether we have observed a recent AOS timing report from
  // the application. Staleness is calculated based on the timing report period
  // specified for the starterd application (defaults to 1 Hz, can be overridden
  // by --timing_report_ms).
  has_active_timing_report: bool (id: 8);

  // Current state of the running executable. This can be used to detect if
  // a process should be restarted because the file has changed on disk.
  file_state: FileState (id: 9);
}

root_type Status;