PubNub FunctionsKey Concepts

PubNub Functions is built upon some key concepts – It's advised to become familiar with them before you start developing and testing with PubNub Functions.

A channel represents a virtual path between publishing and subscribing clients in the PubNub Data Stream Network (DSN). If you're familiar with general message queue concepts, a channel is similar to a topic.

Any message will have exactly one channel associated with it. As an example, in order to receive a message published on the channel BayAreaNews, the client must be subscribed to [at least] the channel BayAreaNews (a subscribing client may be subscribed to more than one channel at a time.)

A channel doesn't need to be declared, defined, or instantiated in any way, they can be considered unlimited and arbitrary in scope. You can choose as many, or as few channels as you'd like to use in your apps – consider the channel as metadata on the message itself.

In PubNub Functions, a specific Function (written in Javascript) can be associated with one or more channels. Every message published on a given channel will be processed by its associated event handler (if defined).

On a given channel, clients can publish messages with tags (also known as metadata). Subscribing clients can filter the messages they receive based on the presence or absence of this metadata. To learn more about metadata and filtering, please see the metadata and filtering SDK docs.

An Endpoint is a URI path you can make an HTTP request to trigger a Function. It's the same concept as an HTTP handler but you don't have to spin up a webserver etc. All Endpoints are by default secure and only accept requests via HTTPS. Endpoints allow you to start a microservice on PubNub's Network in seconds. Functions with Endpoints are On Request types.

The first level of partitioning data between PubNub accounts is via the PubNub API keysets. Keysets are managed by PubNub and created by users from their admin portal. Each Keyset contains a Publish, Subscribe, and Secret Key.

Secret keys are also unique to a keyset, and are used for management functions.

Consider a publish key, subscribe key, and channel name the composite identifier for any message over the PubNub network. In other words, any channel is namespaced by the subscribe and publish keyset used to publish it.

For example, anyone publishing with a PubNub instance defined against keyset1 on channel1 can be received only by subscribers defined against keyset1 on channel1. To make it more clear, consider channel1's real name in this case to be keyset1:channel1… if someone published on a different keyset, but same channel, since the channel is namespaced by the keyset, there would be no collision.

A Function is a block of Javascript code which runs when triggered by a given Function type, against a given keyset and channel(s) or URI path – it is the logic to perform against a message meeting certain criteria or an HTTP request.

Functions can be deployed to the PubNub DSN via the GUI, CLI, or REST APIs.

The way a Function is triggered and executed depends on the type of Function it is. A Function can be 1 of the 4 types below:

  • Before Publish or Fire - Executed in response to publishing a message on a channel and before the message has been forwarded on to awaiting subscribers, these Functions allow you to operate on, or mutate the message.
  • After Publish or Fire - Executed in response to publishing a message on a channel and after the message has been forwarded on to awaiting subscribers, these Functions allow you to act on the message publish event without having to worry about the latency impact of it.
  • After Presence - Executed in response to a Presence event and after it has been forwarded on to awaiting subscribers, these functions allow you to operate on the Presence event.
  • On Request - Executed in response to an HTTP request, these functions allow you to build microservices and webhooks.

Groups of Functions that share a scope are called a Modules.

PubNub Functions provides a rich set of tools, and this documentation does not cover all of the potential situations you may encounter. If you need help with a situation not covered by the documentation, please contact PubNub Support.