From 05249e6c6b8854c5fb38f02cd8315eb6311ef8ed Mon Sep 17 00:00:00 2001 From: Anton Nikiforov Date: Tue, 5 Dec 2023 11:18:25 +0300 Subject: [PATCH] [#841] doc: Describe `epoch` Signed-off-by: Anton Nikiforov --- docs/epoch.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 docs/epoch.md diff --git a/docs/epoch.md b/docs/epoch.md new file mode 100644 index 000000000..2f33dcfd5 --- /dev/null +++ b/docs/epoch.md @@ -0,0 +1,43 @@ +# Epoch + +The main purpose of the `epoch` in `frostfs` environment is to manipulate `netmap`. +Each new epoch, `ir` service trigger revision content of the `netmap` by adding or removing nodes to or from it. +`node` service trigger few internal processes each new epoch - for example, running GC. +Epoch also used in an object lifecycle. + +At the startup, `ir` service initializes an epoch timer which handles new epoch tick. +Epoch timer is a block timer - which means that this timer ticks each block or set of blocks. +The epoch duration stores in the configurable parameter `EpochDuration` in the blockchain. +It is possible to get it via `frostfs-adm`: +```shell +> frostfs-adm morph dump-config -c config.yml -r http://morph-chain.frostfs.devenv:30333 +... +EpochDuration: 240 (int) +... +> +``` +Once epoch timer ticks, `ir` service call method [NewEpoch](https://git.frostfs.info/TrueCloudLab/frostfs-contract/src/commit/a1b61d3949581f4d65b0d32a33d98ba9c193dc2a/netmap/netmap_contract.go#L238) +of the `netmap` contract. Each `ir` instance can do this at the same time, but it is not an issue, +because multiple call of this method with the same set of parameters will give us the same result. + +Utility `frostfs-adm` have a command to trigger new epoch: +```shell +> frostfs-adm morph force-new-epoch -c config.yml -r http://morph-chain.frostfs.devenv:30333 +``` +Command goes directly to the `netmap` contract and call method `NewEpoch`. +Method checks alphabet witness and stores candidates nodes which are not in the `OFFLINE` state as a current netmap. +Then executes method `NewEpoch` in `balance` and `container` contracts. +At the end it produces notification `NewEpoch` which is handled by `node` and `ir` services. + +`ir` handler for `NewEpoch` updates internal state of the netmap, if it is necessary, updates state of the nodes or +marks for exclusion from netmap in the blockchain. + +`node` handler for `NewEpoch` executes method `addPeer` of the `netmap` contract. +This method do nothing, but produces notification which handled by `ir` service. +`ir` in handler for `AddPeer` may update node state in the netmap if it is necessary. + +At the startup, node bootstraps with state `ONLINE`. From the online state, it is possible to move to `MAINTENANCE` or `OFFLINE`. +Node moved to `OFFLINE` state automatically, when there is no bootstrap request from it for a number of epochs. +This number stored in the `ir` config `netmap_cleaner.threshold`. +From `OFFLINE` state node, once it bootstrapped, moves to `ONLINE`. +`MAINTENANCE` state persists even if node rebooted or unavailable for a few epochs.