Metadata-Version: 2.2
Name: bounce_ws
Version: 0.9.9
Summary: A simple framework for websocket event-based messaging using flask websockets under the hood
Home-page: https://github.com/Allorak/bounce-ws
Author: Mike Moiseev
Author-email: mvmoiseev@miem.hse.ru
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Natural Language :: English
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: uvicorn[standard]
Requires-Dist: fastapi
Requires-Dist: loguru
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Bounce-WS

## Overview

This project is a WebSocket-based framework built with FastAPI and Uvicorn, designed to facilitate real-time communication between the frontend and backend.

## Features

- Real-time WebSocket communication.
- Multi-threaded server for efficient handling of connections.
- Scalable and modular design for easy integration.
- Prebuilt logic for messages

## Installation

To install the project, clone the repository and install the required dependencies:

```bash
git clone https://github.com/Allorak/bounce-ws
cd websocket-api
pip install -r requirements.txt
```

Alternatively you can use pip to install:

```bash
pip install https://github.com/Allorak/bounce-ws
```

Or install from PyPI index:
```bash
pip install bounce-ws
```

## Core ideas

The main idea is that client and server use websockets for message exchange with specified message structure:
```json
{
  "event": "<event name>",
  "data": "<message payload>",
  "timestamp": "<iso formated send time timestamp without offset>"
}
```

For interacting with the server clients firstly have to subscribe to the needed events sending following message:
```json
{
  "event": "subscribe",
  "data": {
    "events": [<list of event names to subscribe to>]
  },
  "timestamp": "<iso formated send time timestamp without offset>"
}
```
You may specify `"*"` in `"events"` key to subscribe to all events, provided by the server

In a similar way client may unsubscribe from the specified events:
```json
{
  "event": "unsubscribe",
  "data": {
    "events": [<list of event names to unsubscribe from>]
  },
  "timestamp": "<iso formated send time timestamp without offset>"
}
```

Framework provides following options for message exchange:
- Clients can subscribe to the needed events and unsubscribe from them
- Send message using AbstractSender calling "send" method manually
- Send message using TimedAbstractSender calling "send" method repeatedly
- Handle incoming messages with AbstractHandler, discarding messages of the same event with timestamp larger than last handled

## Example

Usage examples can be found in `examples/` folder
