Introduce `auxilliary request result` detail #8

New issue

Open

opened 2023-02-09 12:38:40 +00:00 by fyrchik · 0 comments

fyrchik commented

2023-02-09 12:38:40 +00:00

(Migrated from github.com)

For GET operation we return a single status value. Currently most of the time ObjectNotFound is returned. While it is inevitable (we cannot be sure in anything in a distributed system), it may confuse CLI users and, especially, gateways where a response can be a single number (e.g. HTTP status).

I have 3 goals in mind:

The solution should be suitable for automatic processing by high-level applications.
Deliver useful information to user.
Be generic enough to be applied to all operations, not only GET (incomplete object PUT is another good option).

Non-goals:

Replace status mechanism.

The proposal is to introduce well-known detail "auxilliary request result". It's payload contains 4 fields:

Multiaddress of a node where a request was sent. Based on (3) gateway can avoid querying this node or, on the opposite, retry request from directly from this node. CLI client may in turn use this info to check if the node is healthy.
Operation type. Generated requests can be different (like for DELETE we collect complex object children with HEAD).
Response code. We need some well-known set of failures (many network failures do not have a specific status, but may be interpreted differently: consider "context deadline exceeded" vs "cannot resolve DNS name" vs "node is under maintenance"). A precise list of details is to be discussed.
Response string. This is mostly for user and all errors which are not well-known.

For GET we can return ObjectNotFound together with all details then. In CLI each of them can be printed, but higher level applications can also use (3) to make a request to another node or convert it to a more suitable response.

All fields except (2) are must have IMO, but we can start with implementing at least 1 and 4.

For GET operation we return a single status value. Currently most of the time `ObjectNotFound` is returned. While it is inevitable (we cannot be sure in anything in a distributed system), it may confuse CLI users and, especially, gateways where a response can be a single number (e.g. HTTP status). I have 3 goals in mind: 1. The solution should be suitable for automatic processing by high-level applications. 2. Deliver useful information to user. 3. Be generic enough to be applied to all operations, not only GET (incomplete object PUT is another good option). Non-goals: 1. Replace status mechanism. The proposal is to introduce well-known detail "auxilliary request result". It's payload contains 4 fields: 1. Multiaddress of a node where a request was sent. Based on (3) gateway can avoid querying this node or, on the opposite, retry request from directly from this node. CLI client may in turn use this info to check if the node is healthy. 5. Operation type. Generated requests can be different (like for DELETE we collect complex object children with HEAD). 6. Response code. We need some well-known set of failures (many network failures do not have a specific status, but may be interpreted differently: consider "context deadline exceeded" vs "cannot resolve DNS name" vs "node is under maintenance"). A precise list of details is to be discussed. 7. Response string. This is mostly for user and all errors which are not well-known. For GET we can return `ObjectNotFound` together with all details then. In CLI each of them can be printed, but higher level applications can also use (3) to make a request to another node or convert it to a more suitable response. All fields except (2) are must have IMO, but we can start with implementing at least 1 and 4.