dsfx/docs/adr/0007-communication-protocols-and-api-design.md

# ADR-0007: Communication Protocols and API Design

## Status

Proposed

## Context

Our system requires a robust communication layer to enable secure and efficient interactions between the client and the self-hosted server/P2P nodes. This includes both data transfers for file operations and control messages for tasks such as replication, manifest management, and access control. The communication protocols must support secure endpoints, transparent operations, and reliable performance even under simulated conditions (see FR-4, NFR-2, and NFR-6).

In order to minimize external vulnerabilities, we strive to avoid third-party dependencies. As such, the client-to-server interactions will be implemented using a standard RESTful API, while inter-node communication will rely on a custom-built binary protocol. This custom solution mitigates supply chain risks by removing reliance on external libraries such as gRPC and maintains full control over our protocol’s security features.

## Decision

We will design the communication layer with two distinct components:

- **RESTful API for Client-Server Interactions:**
  The client application will interact with the server using a RESTful API. This API will handle file uploads/downloads, user commands, and management operations. REST was chosen for its simplicity, ease of use, and wide support while ensuring that sophisticated security measures (e.g., TLS and strong authentication) are applied. This design meets our requirements for transparency and secure user interactions (FR-4, FR-6, NFR-1).

- **Custom Binary Protocol for Inter-Node Communication:**
  For communication between nodes, we will develop a custom binary protocol. This protocol will be designed to:

  - Ensure efficient, low-latency communication suitable for P2P replication and synchronization.
  - Provide built-in security features, including mutual authentication and encrypted payloads, without relying on external dependencies.
  - Integrate with our deterministic simulation framework to simulate network latency, failures, and other adverse conditions, ensuring the protocol meets performance and reliability benchmarks (NFR-2, NFR-6).

- **Secure Communication Practices:**
  Both the RESTful API and the custom binary protocol will enforce TLS for securing communications over the network. All endpoints will require strong authentication to prevent unauthorized access, aligning with our security expectations (NFR-1).

- **Stateless and Versioned API Design:**
  The RESTful API will be designed in a stateless manner to facilitate scalability and ease of load balancing. Additionally, the API will be versioned to support backward compatibility as the system evolves, ensuring stability and maintainability.

## Consequences

- **Advantages:**

  - **Eliminated Third-Party Dependency:** The use of a custom binary protocol removes reliance on external libraries such as gRPC, reducing the risk of a supply chain attack.
  - **Enhanced Security Control:** Developing our own inter-node protocol allows full control over security features tailored to our specific needs, ensuring robust encryption, mutual authentication, and auditability (NFR-1, FR-6).
  - **Performance and Reliability:** With a custom solution targeted for inter-node communication, we can optimize performance for low-latency and high-throughput scenarios. Integration with deterministic simulation ensures adherence to performance and reliability targets under various network conditions (NFR-2, NFR-6).
  - **Simple Client Interaction:** Using a RESTful API for client-server interactions maintains simplicity for the end user, making the system easier to use and maintain.

- **Trade-offs:**
  - **Development Complexity:** Crafting a custom binary protocol introduces additional development effort compared to adopting an existing solution. However, this is outweighed by the increased control over security and reduced external risk.
  - **Maintenance Overhead:** Custom protocols require ongoing maintenance and robust testing to remain secure and performant across various network conditions.
  - **Learning Curve:** Developers will need to familiarize themselves with the custom protocol specifications, even though the RESTful API helps to mitigate user-facing complexity.

## References to Requirements

- **Functional Requirements:**

  - FR-4: Peer-to-Peer Node Interaction – The system’s inter-node communication is essential for secure file sharing and replication.
  - FR-6: User Control and Access Management – Secure communication is critical to ensuring transparent and audit-friendly operations.

- **Non-Functional Requirements:**
  - NFR-1: Security & Privacy – Enforcing TLS and mutual authentication as part of both the RESTful API and custom binary protocol meets our strong security requirements.
  - NFR-2: Performance & Responsiveness – The custom binary protocol is designed to operate efficiently even under simulated network latency.
  - NFR-6: Deployability & Maintainability – A stateless, versioned API paired with a tailored inter-node protocol facilitates straightforward deployment and rigorous deterministic testing.

## Conclusion

By implementing a RESTful API for client-server interactions and a custom binary protocol for inter-node communications, our design not only meets our functional and non-functional requirements but also mitigates external dependencies, reducing supply chain risk. This approach preserves security, performance, and transparency in all communication layers, ensuring a resilient system that remains fully within our control.