package mauve.proto;

// An alert is a notification of an event in your business, project or
// enterprise for which someone might want to stop what they're doing and
// attend to.
//
// Alerts
//
message Alert {
  // Every separate alert must have a unique Id attached.  When sending a 
  // repeated or altered alert, using the same alert id will overwrite
  // the previous settings.  
  //
  required string id = 1;
  
  // The UNIX time at which this alert was or will be raised.  If set to zero it
  // means 'this alert is assumed to be raised already'.
  //
  optional uint64 raise_time = 2;
    
  // The UNIX time at which this alert was or will be cleared.  If set to zero
  // it means 'do not clear automatically'.  Messages with clear times set before 
  // alert times are not valid, and will be ignored.
  //
  optional uint64 clear_time = 3;
  
  // The subject is the name of the server/device/entity that is being alerted
  // about.  If not supplied, assumed to be the same as source.
  //
  optional string subject = 4;
  
  // The summary is a summary of an alert (100 characters or less) that
  // can be fitted into a pager or SMS message, along with the source & subject.
  //
  optional string summary = 5;
  
  // The detail can be an arbitrary HTML fragment for display on suitable
  // devices giving fuller information about the alert.
  //
  optional string detail = 6;
  
  // The importance of this alert (relative to others from this source).  Zero
  // is 'unspecified importance' which will use the server's default.
  //
  optional uint32 importance = 7;

}

// The AlertUpdate is the unit of communication from an alerting source;
// it consists of one or more alerts, which can either replace, or supplement
// the alert data for that source.
//
message AlertUpdate {  
  // Random number with each transmission, so that destinations can easily
  // identify and discard duplicate transmissions that are inherent to the
  // protocol.
  //
  required uint64 transmission_id = 1;

  // The source of an alert represents the sender - each possible sender
  // should set this consistently (e.g. the name of the monitoring system
  // that is generating a particular class of alerts).
  //
  required string source = 2;
  
  // When set to true,  signals that this update should completely replace
  // all current data for this source (so unlisted previous alerts are deemed
  // to be cleared).
  //
  required bool replace = 3 [ default = false ];
  
  // Alert data follows
  //
  repeated Alert alert = 4;

  // Signature to authenticate this data - no scheme defined currently, maybe
  // SHA1(alert.raw + password) ?
  //
  optional bytes signature = 5;
  
  // The UNIX time at which the packet was sent by the server.
  //
  optional uint64 transmission_time = 8;
}