https://github.com/hivesolutions/pushi
Simple yet powerful infra-structure for handling of WebSocket connections
https://github.com/hivesolutions/pushi
notifications push pushi realtime websocket
Last synced: 6 months ago
JSON representation
Simple yet powerful infra-structure for handling of WebSocket connections
- Host: GitHub
- URL: https://github.com/hivesolutions/pushi
- Owner: hivesolutions
- Created: 2014-11-28T13:59:47.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2024-01-17T15:44:59.000Z (over 2 years ago)
- Last Synced: 2025-06-18T07:50:05.549Z (about 1 year ago)
- Topics: notifications, push, pushi, realtime, websocket
- Language: Python
- Homepage: http://pushi.hive.pt
- Size: 584 KB
- Stars: 0
- Watchers: 4
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# [](http://pushi.hive.pt)
Simple yet powerful infra-structure for handling of WebSocket connections.
## Objectives
The server itself should be based on a common infra-structure like the one
present in frameworks like node.js that should abstract the socket connection
layer (select layer) on an event driven basis. The infra-structure itself should
be non-blocking and asynchronous for performance and scalability.
The API layer should be provided by a simple WSGI application implemented using
the [Appier Framework](https://github.com/hivesolutions/appier) to keep things
simple and fast.
For persistence the pushi infra-structure uses the MongoDB database infra-structure
to avoid any unwanted complexities and provide fast performance.
## Inspiration
Pushi was heavily inspired by the [Pusher](http://pusher.com) service, and aims
at providing a free alternative to it (for cost reducing).
## Channels
The channel is the base object for communication and there are four types of channels
so that each one has its own objectives.
### Public Channels
Channels that may be subscribed by any connection without any sort of validation.
### Private Channels
Authenticated channels for which the access is constrained to only server side
validated connections. The validation is performed using a REST-JSON based API.
### Presence Channels
Channels that provide extra information on the situation on the channel, for instance
allow the identification of a set of connection using a single `user_id` tag. Using
this approach it's possible to know when a new user connects to a channel and when
one disconnects (no more connections with the same `user_id` are present). These channels
are considered private and so are subject to validation from the server side.
### Personal Channels
This channels provide the capability to aggregate a series of (personal) subscriptions
into a single channel (for simplicity). This way it's easy to aggregate a stream of
notifications that arise from a group of channels. This channel must be used together
with the publish subscribe model. A channel of this type should be named `personal-`.
### Peer Channels
Targeted at chat environment allows for the creation of automatic channels for the
various elements (users) that are subscribed to a peer channel. The activation of the
automatic peer channel configuration is archived using the `peer` flag in the `channel_data`
structure upon the subscription of such channel. This channel type **should not be created directly
but instead should be created through presence channels**.
The management of these kind of channels implies that the `peer` advertisement flag is set
for a channel shared among the peers, from that moment the peer is visible to all the
other peers upon subscription of that shared channel. These kind of channels should
be used together with the presence channels.
The naming of these kind of channels will always follow the structure
`peer-base_channel:user_1&user_2&user_3`.
## Persistence
It's possible to use pushi to store messages in the server side in a publish/subscriber
way so that a `user_id` may subscribe for a certain channel even when it's offline.
### Subscribe
To be able to subscribe for a channel use the `apps//subscribe` route with the
`user_id` and the `event` parameters indicating both the id and the name of the event
that should be subscribed.
### Unsubscribe
To revert the subscribe operation one should call the `apps//unsubscribe` route
with the same `user_id` and the `event` parameters.
### Usage
When a user connects to the channel that it has subscribed the last messages are returned
as part of the `channel_data` structure.
## Running
To be able to run the pushi infra-structure under a normal non encrypted connection
and bind to the complete set of network interfaces in the host the following command:
APP_HOST=0.0.0.0 \
APP_PORT=8080 \
SERVER_HOST=0.0.0.0 \
SERVER_PORT=80 \
python pushi/src/pushi/base/state.py < /dev/null &> ~/pushi.log &
To be able to run in using SSL encryption additional commands must be used, please note
that the SSL port used by the app is not the default one:
APP_SERVER=netius \
APP_HOST=0.0.0.0 \
APP_PORT=9090 \
APP_SSL=1 \
APP_SSL_KEY=/path/to/file.key \
APP_SSL_CER=/path/to/file.cer \
SERVER_HOST=0.0.0.0 \
SERVER_PORT=443 \
SERVER_SSL=1 \
SERVER_SSL_KEY=/path/to/file.key \
SERVER_SSL_CER=/path/to/file.cer \
python pushi/src/pushi/base/state.py < /dev/null &> ~/pushi.log &
## Quick Start
### Client Side
```javascript
var pushi = new Pushi("YOU_APP_KEY");
pushi.bind("message", function(event, data) {
jQuery("body").append("
" + data + "");
});
```
### Server Side
```python
import pushi
proxy = pushi.Pushi(
app_id = "YOU_APP_ID",
app_key = "YOU_APP_KEY",
app_secret = "YOU_APP_SECRET"
)
proxy.trigger_event(
channel = "global",
data = "hello world",
event = "message"
)
```
## License
Pushi System is currently licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/).
## Build Automation
[](https://github.com/hivesolutions/pushi/actions)
[](https://coveralls.io/r/hivesolutions/pushi?branch=master)
[](https://pypi.python.org/pypi/pushi)
[](https://pypi.python.org/pypi/pushi-service)
[](https://www.apache.org/licenses/)