shitflow/shitflow.h

// acetone, 2024
// I hate copyright of any kind. This is a public domain.
// Original source: https://notabug.org/acetone/shitflow

/**********************************************************************************

*** MINI INLINE DOCUMENTATION ***

 Dialog protocol: request-response.
 If there is no response to the request, the connection is closed by timeout.

 A fatal error message is transmitted outside of the sequential dialog.
 After sending, the sender closes the connection.

 If the message could not be read correctly, it is not a fatal error.
 The message_validation_error_no_action response is used so that the sender
 repeats the sending.

 In protocol terminology, the one who provides access to download files
 is the "publisher". The other party receiving is the "consumer".
 It is assumed that the implementation allows multiple consumers to connect.
 The transfer payload (file) is called the "point".

 The v0 protocol uses the following types of messaging objects:
 - message:
     - request:
         - handshake,
         - get_point_declaration_list,
         - get_chunk,
         - close_connection_on_success
     - response:
         - handshake,
         - point_does_not_exists,
         - chunk_does_not_exists,
         - message_validation_error_no_action,
         - point_declaration_list,
         - chunk
     - fatal_error:
         - reading_timeout,
         - other

 The v0 protocol uses the following types of data structures:
 - handshake
 - point_declaration
 - chunk

 Data structures have versions.
 This provides the potential for extending the protocol without major changes.

***  Message scheme:
 +------------------------+
 | DESCRIPTION CRC32      | 4 bytes
 +------------------------+
 | DESCRIPTION SIZE       | 2 bytes
 +------------------------+
 | DESCRIPTION            | variable
 +------------------------+
 | PAYLOAD CRC32          | 4 bytes
 +------------------------+
 | PAYLOAD                | variable
 +------------------------+

 The payload may contain a nested similar message.

 Description validation logic via CRC32 allows you to
 validate an incoming message without fully receiving it.
 If the description part are corrupted, further
 processing is interrupted.

 Description contains Message type and other base info.
 Any payload of variable and significant size is not included
 in the description. This is to ensure that the initial validation
 of the input data does not require the acquisition
 of a large amount of data.

*** Handshake

 The consumer makes a request specifying the protocol version
 and all supported stucture versions to be used.
 The publisher responds with the protocol version and only one version
 for each structure it supports, as reported by the consumer.
 The most recent version that both parties support should be used.
 If an incompatibility occurs, the publisher sends a handshake message
 with an incompatibility flag.

* Handshake request structure:
 +-------------------------------+
 | PROTOCOL VERSION              | 1 byte
 +===============================+
 | SUPPORTED HANDSHAKE VER COUNT | 1 byte
 +-------------------------------+
 | SUPPORTED VERSIONS ARRAY      | 1*count byte
 +===============================+
 | S. POINT DECLARATION V. COUNT | 1 byte
 +-------------------------------+
 | SUPPORTED VERSIONS ARRAY      | 1*count byte
 +===============================+
 | SUPPORTED CHUNK VER COUNT     | 1 byte
 +-------------------------------+
 | SUPPORTED VERSIONS ARRAY      | 1*count byte
 +-------------------------------+

* Handshake response structure:
 +-------------------------------+
 | INCOMPATIBILITY FLAG          | 1 byte
 +-------------------------------+
 | PROTOCOL VERSION              | 1 byte
 +-------------------------------+
 | HANDSHAKE VERSION             | 1 byte
 +-------------------------------+
 | POINT DECLARATION VERSION     | 1 byte
 +-------------------------------+
 | CHUNK VERSION                 | 1 byte
 +-------------------------------+

**********************************************************************************/

#pragma once

namespace ShitFlow {

} // namespace ShitFlow