From a14764baa4554a6ab2ba6c6a7018449f624626e0 Mon Sep 17 00:00:00 2001 From: Salma Elsoly Date: Thu, 12 Dec 2024 14:33:40 +0200 Subject: [PATCH 1/2] document registrar pkg --- pkg/registrar/README.md | 89 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 pkg/registrar/README.md diff --git a/pkg/registrar/README.md b/pkg/registrar/README.md new file mode 100644 index 000000000..f184c26bb --- /dev/null +++ b/pkg/registrar/README.md @@ -0,0 +1,89 @@ +# Registrar package + +The `registrar` pkg is used to handle node registration on ThreeFold Grid. + +The registration process includes: + +1. Collecting node information +2. Creating/Ensuring a twinID exists for the node +3. Registering the node on the blockchain + +## Error Handling + +`ErrInProgress` - Error raised if the node registration is still in progress. +`ErrFailed` - Error raised if the node registration fails. + +## Constants + +### Node registration state constants + +`Failed` - Node registration failed +`InProgress` - Node registration is in progress +`Done` - Node registration is completed + +## Structs + +### State Struct + +used to store the state of the node registration. + +#### Fields + +`NodeID` - The ID of the node. +`TwinID` - The twin ID of the node. +`State` - The state of the node registration. +`Msg` - The message associated with the node registration state. + +### RegistrationInfo Struct + +used to store the capacity, location, and other information of the node. + +#### Fields + +`Capacity` - The capacity of the node. +`Location` - The location of the node. +`SecureBoot` - The secure boot status of the node. +`Virtualized` - The virtualized status of the node. +`SerialNumber` - The serial number of the node. +`GPUs` - The GPUs of the node. + +#### Methods + +`WithCapacity` - Set the capacity of the node, taking a `gridtypes.Capacity` as input. +`WithLocation` - Set the location of the node, taking a `geoip.Location` as input. +`WithSecureBoot` - Set the secure boot status of the node, taking a boolean as input. +`WithVirtualized` - Set the virtualized status of the node, taking a boolean as input. +`WithSerialNumber` - Set the serial number of the node, taking a string as input. +`WithGPUs` - Set the GPUs of the node, taking a string as input. + +### Registrar Struct + +The registrar is used to register nodes on the ThreeFold Grid. + +#### Fields + +`state` - The state of the registrar. +`mutex` - A mutex for synchronizing access to the registrar. + +#### Methods + +`NodeID` - Returns the node ID if the registrar is in the done state, otherwise returns an error. +`TwinID` - Returns the twin ID if the registrar is in the done state, otherwise returns an error. + +## Functions + +### `FailedState(err error) State` + +Returns a failed state with the given error. + +### `InProgressState() State` + +Returns an in progress state. + +### `DoneState(nodeID , twinID uint32) State` + +Returns a done state with the given node ID and twin ID. + +### `NewRegistrar(ctx context.Context, cl Zbus.Client, env environment.Environment, info RegistrationInfo) *Registrar` + +Creates a new registrar with the given context, client, environment, and registration information, starts the registration process and returns the registrar. From d021e21fc05108a15b19b5c03f00b23a5629090b Mon Sep 17 00:00:00 2001 From: Salma Elsoly <67603984+SalmaElsoly@users.noreply.github.com> Date: Tue, 17 Dec 2024 15:25:03 +0200 Subject: [PATCH 2/2] doc: adjust format + more info --- pkg/registrar/README.md | 78 ++++++++++++++++++++++++++--------------- 1 file changed, 50 insertions(+), 28 deletions(-) diff --git a/pkg/registrar/README.md b/pkg/registrar/README.md index f184c26bb..8571240bc 100644 --- a/pkg/registrar/README.md +++ b/pkg/registrar/README.md @@ -1,6 +1,8 @@ # Registrar package -The `registrar` pkg is used to handle node registration on ThreeFold Grid. +The `registrar` pkg is used to handle node registration on ThreeFold Grid. It is used by the `noded` module, which triggers the registration process by first collecting node capacity information, creating a Redis client, and then adding the `registrar` to the intercommunication process using `zbus` for remote procedure calls (RPC). +re-registration occurs automatically every 24 hours or immediately after an IP address change, ensuring the node's information stays up-to-date. +registration process can fail due to various reasons, such as RPC calls failure. The registration process includes: @@ -10,16 +12,19 @@ The registration process includes: ## Error Handling -`ErrInProgress` - Error raised if the node registration is still in progress. -`ErrFailed` - Error raised if the node registration fails. +`ErrInProgress`: Error raised if the node registration is still in progress. + +`ErrFailed`: Error raised if the node registration fails. ## Constants ### Node registration state constants -`Failed` - Node registration failed -`InProgress` - Node registration is in progress -`Done` - Node registration is completed +`Failed`: Node registration failed + +`InProgress`: Node registration is in progress + +`Done`: Node registration is completed ## Structs @@ -29,10 +34,13 @@ used to store the state of the node registration. #### Fields -`NodeID` - The ID of the node. -`TwinID` - The twin ID of the node. -`State` - The state of the node registration. -`Msg` - The message associated with the node registration state. +`NodeID`: The ID of the node. + +`TwinID`: The twin ID of the node. + +`State`: The state of the node registration. + +`Msg`: The message associated with the node registration state. ### RegistrationInfo Struct @@ -40,21 +48,31 @@ used to store the capacity, location, and other information of the node. #### Fields -`Capacity` - The capacity of the node. -`Location` - The location of the node. -`SecureBoot` - The secure boot status of the node. -`Virtualized` - The virtualized status of the node. -`SerialNumber` - The serial number of the node. -`GPUs` - The GPUs of the node. +`Capacity`: The capacity of the node. + +`Location`: The location of the node. + +`SecureBoot`: State whether the node is booted via efi or not. + +`Virtualized`: State whether the node has hypervisor on it or not. + +`SerialNumber`: The serial number of the node. + +`GPUs`: The GPUs of the node. #### Methods -`WithCapacity` - Set the capacity of the node, taking a `gridtypes.Capacity` as input. -`WithLocation` - Set the location of the node, taking a `geoip.Location` as input. -`WithSecureBoot` - Set the secure boot status of the node, taking a boolean as input. -`WithVirtualized` - Set the virtualized status of the node, taking a boolean as input. -`WithSerialNumber` - Set the serial number of the node, taking a string as input. -`WithGPUs` - Set the GPUs of the node, taking a string as input. +`WithCapacity`: Set the capacity of the node, taking a `gridtypes.Capacity` as input. + +`WithLocation`: Set the location of the node, taking a `geoip.Location` as input. + +`WithSecureBoot`: Set the secure boot status of the node, taking a boolean as input. + +`WithVirtualized`: Set the virtualized status of the node, taking a boolean as input. + +`WithSerialNumber`: Set the serial number of the node, taking a string as input. + +`WithGPUs`: Set the GPUs of the node, taking a string as input. ### Registrar Struct @@ -62,16 +80,22 @@ The registrar is used to register nodes on the ThreeFold Grid. #### Fields -`state` - The state of the registrar. -`mutex` - A mutex for synchronizing access to the registrar. +`state`: The state of the registrar. + +`mutex`: A mutex for synchronizing access to the registrar. #### Methods -`NodeID` - Returns the node ID if the registrar is in the done state, otherwise returns an error. -`TwinID` - Returns the twin ID if the registrar is in the done state, otherwise returns an error. +`NodeID`: Returns the node ID if the registrar is in the done state, otherwise returns an error. + +`TwinID`: Returns the twin ID if the registrar is in the done state, otherwise returns an error. ## Functions +### `NewRegistrar(ctx context.Context, cl Zbus.Client, env environment.Environment, info RegistrationInfo) *Registrar` + +Creates a new registrar with the given context, client, environment, and registration information, starts the registration process and returns the registrar. + ### `FailedState(err error) State` Returns a failed state with the given error. @@ -84,6 +108,4 @@ Returns an in progress state. Returns a done state with the given node ID and twin ID. -### `NewRegistrar(ctx context.Context, cl Zbus.Client, env environment.Environment, info RegistrationInfo) *Registrar` -Creates a new registrar with the given context, client, environment, and registration information, starts the registration process and returns the registrar.