diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 273 |
1 files changed, 273 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..4e9b0b1 --- /dev/null +++ b/README.md @@ -0,0 +1,273 @@ +# JCHAT - JMAP-based Chat Protocol and Implementation + +JCHAT is a chat protocol built on top of JMAP (JSON Meta Application Protocol) [RFC8620], providing real-time messaging capabilities with efficient synchronization and push notifications. + +## Project Structure + +``` +jchat/ +├── draft-jchat-00.txt # RFC draft specification +├── rfc8620.txt # Base JMAP RFC for reference +├── server/ # Erlang/OTP server implementation +│ ├── src/ # Server source code +│ ├── test/ # Comprehensive test suite +│ ├── config/ # Configuration files +│ ├── rebar.config # Build configuration +│ └── Makefile # Build automation +└── client/ # HTML/JavaScript web client + ├── index.html # Main client interface + ├── jmap-client.js # JMAP client library + ├── app.js # Application logic + └── package.json # Project metadata +``` + +## Features + +### Protocol Features (JCHAT RFC) +- **Conversations**: Group messaging with metadata and participant management +- **Messages**: Rich text messages with attachments, replies, and reactions +- **Participants**: User roles, permissions, and presence management +- **Real-time Updates**: Push notifications and efficient delta synchronization +- **Standards Compliant**: Built on proven JMAP foundation + +### Server Implementation +- **Erlang/OTP**: Fault-tolerant, concurrent server architecture +- **Mnesia Database**: Built-in distributed database for persistence +- **HTTP API**: RESTful JMAP endpoints with JSON serialization +- **Push Notifications**: Server-Sent Events for real-time updates +- **Comprehensive Testing**: Unit, property-based, and performance tests + +### Web Client +- **Modern UI**: Responsive design with conversation list and chat interface +- **Real-time Messaging**: Live message updates and typing indicators +- **Cross-platform**: Works in any modern web browser +- **JMAP Integration**: Native support for JMAP protocol features + +## Quick Start + +### Prerequisites +- Erlang/OTP 24+ (for server) +- Any HTTP server for client (shttpd, Python, nginx, etc.) +- rebar3 (Erlang build tool) + +### Running the Server + +```bash +cd server +make compile +make run +``` + +The server will start on http://localhost:8080 with the following endpoints: +- `GET /jmap/session` - JMAP session information +- `POST /jmap/api` - JMAP method calls +- `GET /jmap/eventsource` - Server-Sent Events for push notifications + +### Running the Client + +The client is a dependency-free web application built with vanilla HTML, CSS, and JavaScript. + +#### Quick Start (no installation required) + +Using shttpd (recommended): +```bash +cd client +shttpd . --port 3000 +``` + +Using Python: +```bash +cd client +python3 -m http.server 3000 +``` + +Using any web server: +```bash +cd client +# Point nginx, Apache, or any HTTP server to this directory +``` + +The client will be available at http://localhost:3000 + +## Testing + +### Server Tests +```bash +cd server +make test # Run all tests +make test-unit # Unit tests only +make test-prop # Property-based tests +make test-perf # Performance tests +``` + +### Manual Testing +1. Start the server: `cd server && make run` +2. Start the client: `cd client && shttpd . --port 3000` +3. Open http://localhost:3000 in your browser +4. The client will automatically connect to the server + +## API Examples + +### Create a Conversation +```javascript +const conversation = await jmapClient.createConversation({ + title: "Project Discussion", + participantIds: ["user1", "user2", "user3"] +}); +``` + +### Send a Message +```javascript +const message = await jmapClient.sendMessage( + conversationId, + "Hello, everyone!", + "text/plain" +); +``` + +### Query Messages +```javascript +const messages = await jmapClient.queryMessages({ + inConversation: conversationId, + after: "2025-08-15T10:00:00Z" +}); +``` + +## Architecture + +### JMAP Foundation +JCHAT extends JMAP with chat-specific object types: +- **Conversation**: Container for messages and participants +- **Message**: Individual chat messages with rich metadata +- **Participant**: User membership in conversations +- **Presence**: User availability and status information + +### Server Architecture +``` +┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ +│ HTTP Layer │────│ JMAP Methods │────│ Data Layer │ +│ (Cowboy) │ │ (Conversations, │ │ (Mnesia) │ +│ │ │ Messages, etc) │ │ │ +└─────────────────┘ └──────────────────┘ └─────────────────┘ + │ │ │ + │ ┌────────────────┐ │ + └──────────────│ Push Manager │───────────────┘ + │ (Server-Sent │ + │ Events) │ + └────────────────┘ +``` + +### Client Architecture +``` +┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ +│ UI Layer │────│ Application │────│ JMAP Client │ +│ (HTML/CSS) │ │ Logic │ │ Library │ +│ │ │ (JChatApp) │ │ (JMAPClient) │ +└─────────────────┘ └──────────────────┘ └─────────────────┘ + │ │ + │ ┌────────────────┐ + └──────────────│ Server API │ + │ (HTTP/JSON) │ + └────────────────┘ +``` + +## Protocol Details + +### JMAP Capability +``` +"urn:ietf:params:jmap:chat" +``` + +### Core Methods +- `Conversation/get`, `Conversation/set`, `Conversation/query`, `Conversation/changes` +- `Message/get`, `Message/set`, `Message/query`, `Message/changes` +- `Participant/get`, `Participant/set`, `Participant/changes` +- `Presence/get`, `Presence/set` + +### Example JMAP Request +```json +{ + "using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:chat"], + "methodCalls": [ + ["Conversation/query", { + "accountId": "primary", + "sort": [{"property": "lastMessageAt", "isAscending": false}] + }, "c1"], + ["Message/query", { + "accountId": "primary", + "filter": {"inConversation": "#c1/ids/0"}, + "sort": [{"property": "sentAt", "isAscending": true}] + }, "c2"] + ] +} +``` + +## Development + +### Server Development +- Add new JMAP methods in `src/jchat_methods.erl` +- Extend data models in `src/jchat.hrl` +- Database operations in `src/jchat_db.erl` +- Add tests in `test/` directory + +### Client Development +- UI components in `index.html` and CSS +- JMAP protocol handling in `jmap-client.js` +- Application logic in `app.js` +- Build with any modern JavaScript toolchain + +### Testing Strategy +1. **Unit Tests**: Individual function testing +2. **Integration Tests**: Full JMAP request/response cycles +3. **Property Tests**: Randomized testing with PropEr +4. **Performance Tests**: Load testing and benchmarks +5. **Manual Tests**: End-to-end user scenarios + +## Deployment + +### Production Server +```bash +cd server +make release +_build/prod/rel/jchat/bin/jchat start +``` + +### Docker Deployment +```bash +# Build server image +cd server +docker build -t jchat-server . + +# Build client image +cd client +docker build -t jchat-client . + +# Run with docker-compose +docker-compose up +``` + +## Contributing + +1. Read the JCHAT RFC draft (`draft-jchat-00.txt`) +2. Follow Erlang/OTP conventions for server code +3. Use modern JavaScript practices for client code +4. Add tests for all new features +5. Update documentation as needed + +## Standards Compliance + +- **RFC 8620**: JSON Meta Application Protocol (JMAP) +- **RFC 8259**: JSON Data Interchange Format +- **RFC 3339**: Date and Time on the Internet +- **RFC 7231**: HTTP/1.1 Semantics and Content + +## License + +This project is licensed under the MIT License - see the LICENSE file for details. + +## References + +- [RFC 8620 - JMAP](https://tools.ietf.org/html/rfc8620) +- [JMAP Specifications](https://jmap.io/spec.html) +- [Erlang/OTP Documentation](https://erlang.org/doc/) +- [Modern Web Standards](https://developer.mozilla.org/) |