Piper Push Cache Documentation Download Samples Contact  

Model

Piper is a cache with a WebSocket view. The structure of the cache is flat. A record identifier uniquely defines each JSON cached. Every WebSocket command begins with a verb and is followed by zero or more arguments according the the verb.

Records in the cache are JSON documents. Data delivered as a result of a command or susequent subscription are the same JSON documents found in the cache. The record identfiers are strings and must be unique within the cache.

The model extends to cache updates as well as to subscriptions. A separate port is used for updating the cache to allow separation of cache management from viewing the cache. A REST API is provided where the path to a cached record is used to set and delete cache records. A PUT is used to set a record. A DELETE is used to remove a record. To add or replace and record identified by the name 'John' in the cache a PUT to /John would be sent.

Individual attributes or elements in a cached JSON document can be modified individually using a PUT request where just the value or a portion of the JSON document is replaced. In this respect, the REST call is on the element as if it were a separate entity. A PUT to /John/email would be used to set or add the email attribute of the John JSON document.

There are two ports used by Piper, a HTTP viewing port and a modification port which is also HTTP. On the HTTP or viewing port only GET methods are supported unless the 'view.ADMIN_OK' option is set to true. Those connections can be upgraded to a WebSocket connection and then text requests can be sent to view elements of the cache. The request are a commands consisting of a verb and arguments. Verbs are case insensitive. Identifiers are not. Commands are:

GET <rec-id>

This command will return either the JSON for the record identified or a not-found error. The rec-id can also be '*' indicating all records will be sent.

SUBSCRIBE <rec-id>
SUBSCRIBE <filter> <name>
SUBSCRIBE <filter> [<key1> <key2>] <name>

See help topic 'subscriptions'.

UNSUBSCRIBE <rec-id>
UNSUBSCRIBE <name>
UNSUBSCRIBE <filter>

The unsubscribe command removes or cancels a previously made subscription.

PUT <rec-id>

If the view.ADMIN_OK option is true this command can be used to update the cache. It exists so that the cache can be updated from a web page using Javascript. If the contents is an null then the record identified by the rec-id is deleted, otherwize the JSON in the contents is used to updated the record identified by the rec-id in the cache.

On the cache port GET, PUT, DELETE, and optionally POST are supported but no WebSocket upgrades are supported.

In addition to the HTTP modification port NATS messages can be used to modify the cache. More on that topic in the nats help topic.