fleet.md

%fleet specification

%fleet is an Urbit application for monitoring a set of sponsored ships. It is intended to be run on a ship that is providing value-added sponsor services to other running ships. The primary target audience is stars performing planet services, although it should in principle be useful for galaxies performing star services, as well as planets performing moon services.

%fleet initializes by collecting a set of residents on the host ship from Ethereum and Jael. Periodically, it checks to ensure that the set is up to date. Upon each refresh, new residents are added, and former residents are removed from this set. This “refresh” should occur at least once per hour, and even more frequently if performance allows.

%fleet will automatically monitor the uptime of each ship in its set. Similar to ~midden-fabler/ahoy, it will track the amount of time since the last heartbeat from each ship. If the time since last heartbeat exceeds a specified “heartbeat threshold”, %fleet will command %pongo to send a message to a specified set of administrator ships, in order to alert those ships’ users of the downtime. The default heartbeat threshold is ~30m.

User Stories

• I can build %fleet from source using a clearly delineated tutorial page and self-host its distribution desk.
• Installing %fleet provides a Grid icon on my Landscape dashboard which opens into a web interface.
• Upon opening %fleet's web interface, I can see:
  • an alphabetical listing of my sponsored ships as of my latest refresh
  • the date and time of my most recent refresh
  • a text box for each sponsored ship containing a respective @dr value, representing the amount of time to wait for a heartbeat before sending an alert
  • a listing of the administrative ships who are set up to receive alerts when one occurs
  • an ordered log of the last 128 alerts that have been triggered, including:
    • the date and time of the sent alert
    • the full text string of the message in the alert
    • the ships to whom the alert was sent
    • note: the prior log entries to the 128 displayed alerts are still saved in the application’s state, but are not shown on the webpage, unless in a paginated way.
• My set of sponsored ships is automatically kept up to date with my host ship’s latest data from Ethereum and Jael, with a threshold of one hour between refreshes.
• Through the interface, I can modify the following values:
  • My list of sponsored ships and last refresh time (manual refresh)
  • The @dr value associated with a ship’s individual heartbeat threshold
  • The @dr value associated with the global default heartbeat threshold for all ships that have not been manually modified
  • The set of administrative ships to notify in case of an alert (add/remove)
  • A global value representing whether or not to send alerts upon failed heartbeat (an on-off-switch for the alert system)
  • The list of all log entries (prune log to specified size; delete oldest first)
• Upon missed heartbeat threshold, %fleet will command %pongo to send a direct message to each of the ships in my administrative ships list. The message contains the following string:
  • <ship> has not been contacted by <sponsor> in <time>.
  • <ship> represents the resident ship that missed its heartbeat threshold, <sponsor> represents the host ship, and <time> represents the @dr value representing the timer that was set.
• If a ship has missed its heartbeat threshold and returns online, %fleet will command %pongo to send a direct message to each of the ships in my administrative ships list. The message contains the following string:
  • <ship> has contacted <sponsor>. Downtime: <time>
  • Same substitutions as above.
• If an alert is triggered but the global on-off switch indicates not to send an alert, a log entry is still recorded detailing the alerts that would have been sent. The log entry indicates that the alert was not sent to any ships.