satellite/satellitedb/dbx: document node tables

Also, fix nodevents iota usage. Type is directly used in the database
hence we should avoid iota, because it's easy to mess-up the constant
values.

Change-Id: I32bf6d0502fbf3d18660dab5b1dd0b5627b444df

satellite/nodeevents/types.go

@@ -10,21 +10,21 @@ type Type int
 
 const (
 	// Online indicates that the node has come back online.
-	Online Type = iota
+	Online Type = 0
 	// Offline indicates that the node is offline.
-	Offline
+	Offline Type = 1
 	// Disqualified indicates that the node is disqualified.
-	Disqualified
+	Disqualified Type = 2
 	// UnknownAuditSuspended indicates that the node is suspended for unknown audit errors.
-	UnknownAuditSuspended
+	UnknownAuditSuspended Type = 3
 	// UnknownAuditUnsuspended indicates that the node is no longer suspended for unknown audit errors.
-	UnknownAuditUnsuspended
+	UnknownAuditUnsuspended Type = 4
 	// OfflineSuspended indicates that the node is suspended for being offline.
-	OfflineSuspended
+	OfflineSuspended Type = 5
 	// OfflineUnsuspended indicates that the node is no longer suspended for being offline.
-	OfflineUnsuspended
+	OfflineUnsuspended Type = 6
 	// BelowMinVersion indicates that the node's software is below the minimum version.
-	BelowMinVersion
+	BelowMinVersion Type = 7
 
 	onlineName                  = "online"
 	offlineName                 = "offline"

satellite/satellitedb/dbx/node.dbx

@@ -1,5 +1,4 @@
-//--- node db ---//
+// node table contains information about storagenodes.
-
 model node (
     key id
 
@@ -36,58 +35,100 @@ model node (
         where node.release = true
     )
 
+    // id is the storj.NodeID of the storagenode.
     field id              blob
     // address is how to contact the node, this can be a hostname or IP and it contains the port
     field address         text  ( updatable, default "" ) // TODO: use compressed format
-    // last_net is the /24 subnet of the IP
+    // last_net is the /24 of IPv4 or /64 subnet of IPv4. e.g for an IP of 1.2.3.4 it is going to be 1.2.3.
     field last_net        text  ( updatable )
+    // last_ip_port is the IP and port of the storagenode, as it was last resolved.
+    // This is used as a shortcut to avoid overloading DNS.
+    // Connections will fall back to using 'address' if a connection here fails.
     field last_ip_port    text  ( updatable, nullable )
+    // country_code is the ISO 3166 2-letter country code indicating where the node is located, according to geoip lookup.
+    // It is updated anytime we update last_ip_port.
     field country_code    text  ( updatable, nullable )
+    // protocol refers to pb.NodeTransport. TCP+TLS = 0, QUIC+RPC = 1, TCP+NOISE+RPC = 2.
+    // This field seems unused at the moment.
     field protocol        int   ( updatable, default 0 )
+    // type refers to pb.NodeType. It is deprecated, because the table only contains storage nodes.
     field type            int   ( updatable, default 0 )
+    // email is the storage node operators contact email.
     field email           text  ( updatable )
-    field wallet          text  ( updatable ) // TODO: use compressed format
+    // wallet is the text version of the Ethereum (or other) wallet address.
+    field wallet          text  ( updatable )
+    // wallet_features is the comma delimited list of wallet features.
     field wallet_features text  ( updatable, default "" )
+    // free_disk is the amount of free space that the storagenode has reported.
     field free_disk       int64 ( updatable, default -1 )
+    // piece_count is an estimate on the number of pieces the storagenode stores.
     field piece_count     int64 ( autoinsert, updatable, default 0 )
 
+    // major is the version major release.
     field major             int64 ( updatable, default 0 )
+    // minor is the version minor release.
     field minor             int64 ( updatable, default 0 )
+    // patch is the version patch release.
     field patch             int64 ( updatable, default 0 )
+    // hash is the hash of the release.
     field hash              text ( updatable, default "" )
+    // timestamp is the timestamp the release was built.
     field timestamp         timestamp ( updatable, default "0001-01-01 00:00:00+00" )
+    // release indicates whether the storagenode is running a release version.
     field release           bool ( updatable, default false )
 
+    // latency_90 is the 90 percentile estimate of latency.
+    // This column is unused.
     field latency_90           int64   ( updatable, default 0 )
+    // vetted_at is the time the storagenode gained sufficient reputation to be trusted with more data.
     field vetted_at            timestamp ( updatable, nullable )
 
+    // created_at is the time the storagenode first made a successful contact.
     field created_at           timestamp ( autoinsert, default current_timestamp )
+    // updated_at is the time the details have been last updated.
     field updated_at           timestamp ( autoinsert, autoupdate, default current_timestamp )
+    // last_contact_success is the most recent time the storagenode was successfully contacted.
     field last_contact_success timestamp ( updatable, default "epoch" )
+    // last_contact_failure is the most recent time the storagenode checked in, but the satellite wasn't able to ping it back.
     field last_contact_failure timestamp ( updatable, default "epoch" )
 
-    // node is disqualified when it fails too many audits or is offline for too long
+    // disqualified is set when the node fails too many audits or is offline for too long.
+    // Reputation table has a cached value of this field.
     field disqualified            timestamp ( updatable, nullable )
+    // disqualification_reason contains information about why the node was disqualified.
+    // This corresponds to overlay.DisqualificationReason.
+    // 0=unknown, 1=audit failures, 2=suspended for too long, 3=offline for too long.
+    // Reputation table has a cached value of this field.
     field disqualification_reason int       ( updatable, nullable )
-    // node is placed under inspection when it has too many unknown-error audits
+    // unknown_audit_suspended is set when the node is placed under inspection.
-    // renamed column from suspended
+    // This happens when it has too many unknown-error audits.
     field unknown_audit_suspended timestamp ( updatable, nullable )
-    // node is considered unhealthy if it is offline for too many audits
+    // offline_suspended is set when the node is offline for too many audits.
     field offline_suspended timestamp ( updatable, nullable )
-    // once a node becomes offline_suspended, mark it as under review so we check it again later
+    // under_review is set when the node is marked for offline, this marks the node for review
+    // so it can be checked later.
     field under_review timestamp ( updatable, nullable )
 
+    // exit_initiated_at indicates whether and when the storagenode has started an graceful exit.
     field exit_initiated_at         timestamp ( updatable, nullable )
+    // exit_loop_completed_at indicates when the satellite has collected all the pieces that need to be transferred.
     field exit_loop_completed_at    timestamp ( updatable, nullable )
+    // exit_finished_at indicates when the storagenode finished the graceful exit.
     field exit_finished_at          timestamp ( updatable, nullable )
+    // exit_success is whether the graceful exit ended successfully.
     field exit_success              bool ( updatable, default false )
 
+    // contained indicates when and whether the storagenode has been placed into containment mode.
     field contained                 timestamp ( updatable, nullable )
 
+    // last_offline_email indicates when the last offline email was sent to the storagenode operator.
     field last_offline_email         timestamp ( updatable, nullable )
+    // last_software_update_email indicates when the last software update email was sent to the storagenode operator.
     field last_software_update_email timestamp ( updatable, nullable )
 
+    // noise_proto is the noise protocol version that the storagenode has implemented.
     field noise_proto int ( updatable, nullable )
+    // noise_public_key is the last known public key for the storagenode.
     field noise_public_key blob ( updatable, nullable )
 )
 
@@ -123,15 +164,19 @@ read all (
     where node.piece_count != 0
 )
 
-// -- node api version -- //
+// node_api_version is a table for storing the supported API.
-
+// This information is updated during order settlement.
 model node_api_version (
     key id
 
+    // id is the storj.NodeID of the storagenode.
     field id          blob
+    // api_version refers to the satellite/nodeapiversion.Version value.
     field api_version int  ( updatable )
 
+    // created_at is the time the version was first added.
     field created_at timestamp ( autoinsert )
+    // updated_at is the time the version was last updated.
     field updated_at timestamp ( autoinsert, autoupdate )
 )
 
@@ -152,7 +197,8 @@ update node_api_version (
     noreturn
 )
 
-//-- Node Events --//
+// node_event table contains information that the storagenode should be updated about.
+// This information is collected to avoid sending too many messages to node operators.
 model node_event (
     key id
 
@@ -162,13 +208,20 @@ model node_event (
         where node_event.email_sent = null
     )
 
-    field id blob
+    // id is a UUID for this event.
-    field email text
+    field id             blob
-    field node_id blob
+    // emails is the storagenode operators contact address.
-    field event int
+    field email          text
-    field created_at timestamp ( default current_timestamp )
+    // node_id is the storagenode storj.NodeID.
+    field node_id        blob
+    // event is the event kind, which refers to satellite/nodeevents.Type.
+    field event          int
+    // created_at is when this event was added.
+    field created_at     timestamp ( default current_timestamp )
+    // last_attempted is when nodeevents chore last tried to send the email.
     field last_attempted timestamp ( nullable, updatable )
-    field email_sent timestamp ( nullable, updatable )
+    // email_sent when the email sending succeeded.
+    field email_sent     timestamp ( nullable, updatable )
 )
 
 create node_event()