added junie guidelines

Author: jell-o-fishi

.junie/guidelines.md

@@ -0,0 +1,88 @@
+
+# RSocket-py Project Analysis
+
+## Overview
+RSocket-py is a Python implementation of the [RSocket](http://rsocket.io) protocol, which is a binary protocol for use on byte stream transports such as TCP, WebSockets, and Aeron. The project provides a comprehensive implementation of the RSocket protocol with support for various transports, extensions, and integrations.
+
+## Key Components
+
+### Core Architecture
+- **RSocketBase**: The foundational class implementing the RSocket protocol, handling frame processing, stream management, and connection lifecycle.
+- **Transport Layer**: Supports multiple transports including TCP, WebSocket (via aiohttp, fastapi, quart, websockets), and QUIC.
+- **Request Handlers**: Implements the different interaction models (request-response, fire-and-forget, request-stream, request-channel).
+- **ReactiveX Integration**: Provides integration with ReactiveX (both v3 and v4) for reactive programming support.
+
+### Interaction Models
+- **Request-Response**: Simple request with a single response.
+- **Fire-and-Forget**: One-way message with no response.
+- **Request-Stream**: Request that receives a stream of responses.
+- **Request-Channel**: Bi-directional stream of messages.
+- **Metadata Push**: Metadata-only message with no response.
+
+### Extensions
+- **Composite Metadata**: Support for multiple metadata entries in a single payload.
+- **Routing**: Request routing capabilities similar to HTTP routing.
+- **Authentication**: Built-in authentication mechanisms.
+- **Fragmentation**: Support for breaking large messages into fragments.
+
+### Reactive Streams
+- **Backpressure Support**: Implements the Reactive Streams specification for handling backpressure.
+- **Publisher/Subscriber Pattern**: Uses the publisher/subscriber pattern for stream handling.
+
+## Project Structure
+
+### Main Package (`rsocket/`)
+- **Core Protocol Implementation**: Base classes, frame handling, error codes.
+- **Handlers**: Implementation of different interaction models.
+- **Extensions**: Protocol extensions like routing, authentication.
+- **Transports**: Different transport implementations (TCP, WebSocket, QUIC).
+- **ReactiveX Integration**: Adapters for ReactiveX observables.
+
+### Examples (`examples/`)
+- **Basic Examples**: Simple client-server interactions.
+- **Tutorial**: Step-by-step guide to using the library.
+- **Advanced Use Cases**: Streaming, routing, reconnection, etc.
+- **Bug Reproductions**: Examples demonstrating specific issues.
+
+### Tests (`tests/`)
+- **Unit Tests**: Tests for individual components.
+- **Integration Tests**: Tests for component interactions.
+- **ReactiveX Tests**: Tests for ReactiveX integration.
+
+## Streaming File Example Analysis
+
+The streaming file example demonstrates how to stream a file from server to client using RSocket's request-stream interaction model:
+
+### Server Side
+1. **File Reading**: Uses `aiofiles` to asynchronously read a file in chunks.
+2. **Stream Handler**: Implements a request-stream handler that reads file chunks and sends them to the client.
+3. **Backpressure Handling**: Uses ReactiveX's backpressure mechanisms to control the flow of data.
+4. **Routing**: Uses RSocket's routing capabilities to expose the stream endpoint.
+
+### Client Side
+1. **Stream Request**: Initiates a request-stream interaction with the server.
+2. **Data Processing**: Processes the incoming stream of file chunks.
+3. **ReactiveX Integration**: Uses ReactiveX operators to transform and collect the stream data.
+
+## Key Features and Capabilities
+
+- **Async/Await Support**: Built on Python's asyncio for asynchronous programming.
+- **Backpressure Control**: Implements proper backpressure handling for stream processing.
+- **Extensibility**: Modular design allows for easy extension and customization.
+- **Multiple Transport Support**: Works with various transport protocols.
+- **Reactive Programming**: Integration with ReactiveX for reactive programming patterns.
+- **Routing**: Request routing similar to HTTP frameworks.
+- **Fragmentation**: Support for large messages through fragmentation.
+- **Command Line Interface**: Includes CLI tools for testing and debugging.
+
+## Integration Options
+
+The project supports integration with various Python libraries and frameworks:
+- **ReactiveX**: For reactive programming.
+- **aiohttp/fastapi/quart**: For WebSocket transport.
+- **CloudEvents**: For event-driven architectures.
+- **GraphQL**: For GraphQL API implementation.
+
+## Conclusion
+
+RSocket-py provides a comprehensive implementation of the RSocket protocol in Python, with support for all interaction models, various transports, and extensions. It's designed for building reactive, resilient, and efficient communication between services, particularly in microservice architectures. The project's modular design and extensive examples make it accessible for developers looking to implement RSocket-based communication in their Python applications.