https://github.com/chromakode/ivy

A minimalistic hierarchical pubsub server with persistent event logs.
https://github.com/chromakode/ivy

Last synced: 23 days ago
JSON representation

A minimalistic hierarchical pubsub server with persistent event logs.

• Host: GitHub
• URL: https://github.com/chromakode/ivy
• Owner: chromakode
• License: bsd-3-clause
• Created: 2014-09-14T06:36:29.000Z (about 10 years ago)
• Default Branch: master
• Last Pushed: 2014-10-16T20:47:48.000Z (about 10 years ago)
• Last Synced: 2024-06-19T11:37:42.708Z (5 months ago)
• Language: Go
• Size: 164 KB
• Stars: 5
• Watchers: 3
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
![ivy](https://raw.githubusercontent.com/chromakode/ivy/master/art/logo.png)

Ivy is a minimalistic hierarchical pubsub server with persistent event logs. It's designed for real time shared spaces such as chat rooms or collaborative creative tools. While a standalone binary is provided, Ivy is more oriented towards embedding in a larger server to provide the core realtime event system.

Ivy is written in Go, and uses [LevelDB](https://code.google.com/p/leveldb/) for persistence. It provides Websocket and HTTP views of event streams.

**Note:** Ivy is not stable or production ready yet, and lacks a thorough test suite. The protocol will change without warning in the future. It is suitable only for experimental or demo use. It also doesn't scale. You really shouldn't use this unless you like hacking on Go programs. It may eat your data, or more likely your time.

---

## structure

In Ivy, *clients* subscribe to *channels*, which exist in a hierarchical tree starting at the root, `/`. Clients send *events* to channels, which bubble up to parent channels, until they reach the root. Ivy is agnostic about event format; event data is treated as a blob of bytes. In practice, JSON is usually most convenient.

Every event in Ivy is persisted to the `logs`, which are accessible via HTTP at:

    http(s)://hostname/log/path/to/channel

Real time events are sent over the WebSocket interface at:

    ws(s)://hostname/ws

## protocol

Ivy uses a simple ASCII protocol that is intended to be mildly human-readable. Commands and events are newline-terminated. In event data, newlines are escaped to `%0A`, and '%' characters to `%25`.

### client commands

#### callbacks / acks

To receive an acknowledge response from the server, prefix a command with:

    #ackkey#

The *ack key* can be any data that is convenient for the client to associate the response with its initial request.

#### subscribe / unsubscribe

    +/path/to/channel

    -/path/to/channel

Subscribe / unsubscribe from a channel. Subsequent events will be sent to the client.

#### sending events

    :/path/to/channel:data

Send an event to a channel with *data*.

#### server timestamp

    @

Request the server timestamp in floating point format (seconds.nanoseconds). Requires an *ack key*.

### receiving events

Events sent to the client (and in logs) take the following format:

    @seconds.nanoseconds:/path/to/channel:data

## client libs

Ivy has a basic [JavaScript client library](https://github.com/chromakode/ivy-client.js).

## future plans

 * authentication

 * channel join/part events

 * channel subscriber rosters

 * "confirmed" events sent with the timestamp of the last received event (for handling collisions)

 * offset log fetching with infinite cache headers (for use behind a pull CDN)

 * multiple host scaling