Valve
This tutorial covers aspects of Valve – deepstreamHub’s realtime permission language. You can specify Valve rules in the permission section of the dashboard or upload them via the HTTP API.
What can be permissioned?
Permissions allow you to specify if a user can create, write, read or delete a record, publish or subscribe to events, provide or make RPCs or get notified when other users come online.
How do permissions work?
deepstream uses a proprietary permission syntax called "Valve". Valve rules are simple javascript strings with a reduced feature-set. Each valve rule defines access to a specific action related to a specific concept, e.g. a "write" to a "record".
Here's what they look like:
record:
#an auctioned item
auction/item/$sellerId/$itemId:
#everyone can see the item and its price
read: true
#only users with canBid flag in their authData can bid
#and bids can only be higher than the current price
write: "user.data.canBid && data.price > oldData.price"
#only the seller can delete the item
delete: "user.id == $sellerId"
How to use Valve rules?
Valve rules are created in a YAML structure directly in the permission section of the dashboard or uploaded via the HTTP API
Each Valve spec has three levels of nesting: Type (record, event, rpc, presence)
- Name (record, event or rpc name)
- Action( read, write, delete, publish etc.)
Let's start with a simple example
Let's say we're building a notification system that allows users to send their status as event (a mini Twitter if you like). Every user can subscribe to another user's status, but users can only publish their own status updates.
First, let's define default actions for all events. Our example platform is open, so generally everyone can publish and subscribe. Listening is not part of the platform, so let's just turn it off altogether:
event:
"*":
publish: true
subscribe: true
listen: false
Next, let's define rules for our status events. Our event names will follow the schema user-status/<username>
, e.g. user-status/lisa
:
event:
"*":
publish: true
subscribe: true
listen: false
user-status/$userId:
publish: "user.id === $userId" #users can only share their own status
This example introduced two basic concepts:
-
specificity Valve uses a simple specificity concept to find out which rule to apply: The longest (e.g. most detailed) rule wins.
user-status/$userId
is longer than the general rule"*"
, so for publish operations it will be applied. For subscribe and listen though, the permission will fall back to the general rule"*"
. -
path variables dollar prefixes identify parts of a record, RPC or eventname as variables, e.g.
$userId
inuser-status/$userId
. These variables will be made available within the permission rule. Using e.g. the username as part of the record name for records with access restrictions is a central concept in Valve.
What's next?
This was a quick introduction to what Valve can do, but there are more powerful concepts, such as build-in variables, string-functions or cross-references to explore. To learn about these, let's move on to the advanced permission tutorial