Status | DECIDED |
---|---|
Stakeholders | |
Outcome |
|
Due date | |
Owner |
Background
Iroha Users need information about "system" aspects which are not available via Iroha Queries to World State View, for example:
Peer's Health Check (Naming of states inspired by Prometheus)
Peer's Management - start, stopResources Monitoring - CPU, Memory and Disk consumption
- Logging Configuration
Business Measurements of Iroha
Transactions per second amount
Blocks Storage size
- Submitted transactions statuses changes
- Blocks statuses changes
Problem
For some clients and for Iroha administrators it is important to have more information than can be provided by Iroha Data Model.
One of such a cases were described by the following requirements:
- Client should receive status changes of all transactions submitted by this client.
- Iroha Peer should guarantee that changes submitted to the client goes over synchronous protocol and messages received by client if peer and client are connected.
- If peer, client or network goes down - Client should use another API to check current status of entities needed.
- Iroha Peer will not store information about status changes and they may be lost.
- iroha Peer will provide information available for this peer only.
- The same functionality should be provided to monitor blocks statuses.
Because transactions states changes are not stored on the Blockchain and can't be presented in World State View `Maintenance Endpoint` is a good place to add this functionality to.
Solution
As a result we can create additional client-facing Iroha API which described in the table below:
API | URI | Protocol | Comments |
---|---|---|---|
Configuration | `/config` | HTTP | REST API for managing Iroha Peer's configuration:
|
Monitoring | `/health` | HTTP | Aligned with Prometheus Peer's Health Check information |
`/metrics` | HTTP | Metrics ready to be scraped by Prometheus | |
Events | `/event` | WebSocket | Human friendly WS API for Cloud Events consumers |
TCP/IP | Low-level API with binary messages for Cloud Events consumers |
Each API responsible for subset of maintenance features. Events API available in two variants - WebSocket for mobile clients, web applications and other human oriented technologies, while TCP/IP option for those clients which resources are limited.
Decisions
- Use HTTP for configuration and monitoring APIs (message format can be json or text based on Prometheus specification)
- Events API implemented as WebSocket and proprietary TCP/IP variants
- Additional port should be used by Maintenance Endpoint
Alternatives
- We can stay with TCP approach but we will need to change DevOps processes and tools, Substrate Off-chain workers also will not be able to deal with TCP
- We can use HTTP for Events API but it's not effective way to handle active sessions between Iroha Peers and Substrate Off-chain workers
Assumptions
Different system events will be aligned with CNCF CloudEvents Specification and may be used in non-maintenance endpoints later.
Concerns
To prevent secured information losses `subscribers` should receive only information they had permissions to have. The "CanAnything" permission will provide information about the entire system and most of maintenance endpoints will require accounts with it. If account has no "CanAnything" permission, it's signature should be presented in transactions to receive information about their states changes.
Risks
- Substrate off-chain workers integration will require additional parties (no direct communication with Iroha) `[9;4]`
- Support of two variants for Events API will require additional maintenance resources `[7;2]`
13 Comments
Iurii Vinogradov
Nikita Puzankov
Iurii Vinogradov yes - 1.b is exactly the main concern here. We have permissions model for both - Instructions and Queries so maybe Makoto Takemiya has an opinion on what we should provide for blocks API?
Makoto Takemiya
If someone doesn't have permission to view something, they shouldn't get it. For proving that their tx is in a block, you just need hashes of merkle subtree (not even tx hashes at the root, except maybe the sibling of your tx).
Iurii Vinogradov
According to Makoto's message we can filter block data returned to the User according to his permissions.
Nikita Puzankov
Yes, as I wrote in "Security aspect" we will filter transactions that were sent by another clients.
Nikita Puzankov
Draft - changes transmitted through Iroha to connected and alive listener. Each listeners keeps TcpStream connection with client and submits changes. Iroha Client's API converts TcpStream into Stream<Change>.
Each change submitted via TcpStream should be confirmed by the client in a timely manner, if not - listener will be deleted.
Vladislav Markushin
That's good IMO. I think we also need a protocol for packing this data.
Nikita Puzankov
Egor Ivkov made a comment about the receipt - should it contain some hash of the event?
Egor Ivkov
I have some security concerns about the endpoints that we have:
Nikita Puzankov
Hi Egor Ivkov,
Egor Ivkov
Yes, sure. That's what I am getting at. Should we have a special RFC for this? Or is this out of the scope of MVP?
Nikita Puzankov
You can add decision to protect endpoints to this RFC.
Vadim Reutskiy
Maintenance endpoint requires protection, for sure. You are absolutely correct in your warnings.
We can take an existing approach for such protection.
Bulat Saifullin Andrei Lebedev can you share your vision how it can be done to satisfy the protection and convenience?