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
This commit is contained in:
Egon Elbre 2023-02-23 16:19:55 +02:00
parent e4914e9b7a
commit cf324c5b6e
2 changed files with 79 additions and 26 deletions

View File

@ -10,21 +10,21 @@ type Type int
const ( const (
// Online indicates that the node has come back online. // Online indicates that the node has come back online.
Online Type = iota Online Type = 0
// Offline indicates that the node is offline. // Offline indicates that the node is offline.
Offline Offline Type = 1
// Disqualified indicates that the node is disqualified. // Disqualified indicates that the node is disqualified.
Disqualified Disqualified Type = 2
// UnknownAuditSuspended indicates that the node is suspended for unknown audit errors. // 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 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 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 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 indicates that the node's software is below the minimum version.
BelowMinVersion BelowMinVersion Type = 7
onlineName = "online" onlineName = "online"
offlineName = "offline" offlineName = "offline"

View File

@ -1,5 +1,4 @@
//--- node db ---// // node table contains information about storagenodes.
model node ( model node (
key id key id
@ -36,58 +35,100 @@ model node (
where node.release = true where node.release = true
) )
// id is the storj.NodeID of the storagenode.
field id blob field id blob
// address is how to contact the node, this can be a hostname or IP and it contains the port // 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 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 ) 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 ) 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 ) 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 ) 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 ) field type int ( updatable, default 0 )
// email is the storage node operators contact email.
field email text ( updatable ) 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 "" ) 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 ) 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 ) field piece_count int64 ( autoinsert, updatable, default 0 )
// major is the version major release.
field major int64 ( updatable, default 0 ) field major int64 ( updatable, default 0 )
// minor is the version minor release.
field minor int64 ( updatable, default 0 ) field minor int64 ( updatable, default 0 )
// patch is the version patch release.
field patch int64 ( updatable, default 0 ) field patch int64 ( updatable, default 0 )
// hash is the hash of the release.
field hash text ( updatable, default "" ) 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" ) 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 ) 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 ) 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 ) 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 ) 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 ) 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" ) 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" ) 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 ) 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 ) 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 ) 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 ) 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 ) 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 ) 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 ) 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 ) field exit_finished_at timestamp ( updatable, nullable )
// exit_success is whether the graceful exit ended successfully.
field exit_success bool ( updatable, default false ) 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 ) 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 ) 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 ) 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 ) 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 ) field noise_public_key blob ( updatable, nullable )
) )
@ -123,15 +164,19 @@ read all (
where node.piece_count != 0 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 ( model node_api_version (
key id key id
// id is the storj.NodeID of the storagenode.
field id blob field id blob
// api_version refers to the satellite/nodeapiversion.Version value.
field api_version int ( updatable ) field api_version int ( updatable )
// created_at is the time the version was first added.
field created_at timestamp ( autoinsert ) field created_at timestamp ( autoinsert )
// updated_at is the time the version was last updated.
field updated_at timestamp ( autoinsert, autoupdate ) field updated_at timestamp ( autoinsert, autoupdate )
) )
@ -152,7 +197,8 @@ update node_api_version (
noreturn 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 ( model node_event (
key id key id
@ -162,13 +208,20 @@ model node_event (
where node_event.email_sent = null 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 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() create node_event()