why deepstreamHub? compare us getting started feature roadmap faq
use cases pricing
products
developers
company
blog contact

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.

Valve Permission Section on deepstreamHub dashboard

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 in user-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