wip adr

docs/architecture/adr/0024-microservice-grpc-networking.md

@@ -0,0 +1,85 @@
+---
+adr: "0024"
+status: Proposed
+date: 2024-11-20
+tags: [server, architecture, communication]
+---
+
+# 0024 - Adopting gRPC for Inter-Service Communication
+
+<AdrTable frontMatter={frontMatter}></AdrTable>
+
+## Context and Problem Statement
+
+As Bitwarden's microservices architecture continues to evolve, the need for efficient, reliable, and
+performant inter-service communication becomes increasingly critical. Our current REST-based API
+communication model, while functional, may not be optimal for all types of service-to-service
+interactions, especially as we scale and introduce more complex, high-throughput operations.
+
+We need to evaluate whether adopting gRPC for inter-service communication could provide benefits in
+terms of performance, type safety, and developer productivity.
+
+## Considered Options
+
+- **Maintain current REST-based communication** - Continue using REST APIs for all inter-service
+  communication.
+- **Adopt gRPC for all inter-service communication** - Completely replace REST with gRPC for all
+  service-to-service interactions.
+- **Hybrid approach** - Implement gRPC for all new services while maintaining existing solutions.
+- **Evaluate alternative RPC frameworks** - Consider other RPC frameworks like Apache Thrift or
+  Apache Avro.
+
+## Decision Outcome
+
+Chosen option: **Hybrid approach - Implement gRPC for all new services while maintaining REST for
+existing ones**.
+
+This approach allows us to leverage the benefits of gRPC for future development without the need to
+immediately refactor existing services, providing a gradual transition path.
+
+### Positive Consequences
+
+- Improved performance and efficiency for all new services due to gRPC's binary serialization and
+  HTTP/2 support.
+- Enhanced type safety and contract-first development with Protocol Buffers for new services.
+- Better support for bi-directional streaming in new services, enabling more real-time features.
+- Gradual adoption allows for learning and adjustment without disrupting existing systems.
+- Improved developer productivity with auto-generated client and server code for new services.
+
+### Negative Consequences
+
+- Increased complexity in the system architecture with two communication protocols.
+- Learning curve for developers to become proficient with gRPC and Protocol Buffers.
+- Potential challenges in debugging and monitoring gRPC traffic compared to REST.
+- Additional tooling and infrastructure required to support both gRPC and REST.
+- Inconsistency in communication protocols across the architecture during the transition period.
+
+### Plan
+
+1. Establish guidelines and best practices for implementing gRPC in new services.
+2. Develop a proof-of-concept implementation for the next planned service.
+3. Create comprehensive documentation and training materials for the development team on gRPC and
+   Protocol Buffers.
+4. Implement gRPC for all new services moving forward.
+5. Develop strategies for efficient communication between gRPC and REST services during the
+   transition period.
+6. Implement monitoring and observability solutions that support both gRPC and REST traffic.
+7. Evaluate the impact and benefits after implementing several new services with gRPC.
+8. Consider a long-term plan for gradually migrating existing REST services to gRPC based on the
+   success of new implementations.
+
+## Additional Considerations
+
+- Ensure compatibility with our current C# server-side codebase and tooling for both REST and gRPC
+  implementations.
+- Adapt our CI/CD pipelines and testing strategies to accommodate both REST and gRPC services.
+- Evaluate the implications for our SDK written in Rust and plan for potential updates to support
+  gRPC.
+- Assess the impact on our self-hosted instances and ensure they can support both communication
+  protocols.
+- Consider the implications for external integrations and develop strategies to support both REST
+  and gRPC interfaces as needed.
+
+This decision allows for a gradual adoption of gRPC while maintaining stability in existing
+services. We will continuously evaluate the effectiveness of this approach and adjust our strategy
+as necessary.