Functions Basics
Function versions
This documentation set focuses on Functions v2 that are accessible for new PubNub Functions users. To learn about the differences between both versions, refer to the Functions v1 vs. v2 comparison.
PubNub provides Functions to capture events that are happening on the PubNub Platform. Functions let you write code or leverage existing integrations to transform, re-route, augment, filter, and even aggregate data.
Watering digital plants, quenching real problems!
Let's consider an example of counting candidate or ballot votes, client or server analytics, or another metric that has to have an accurate count from a distributed set of contributing endpoints. In a traditional database, you would have to:
- Get the current count value from the database.
- Lock that record.
- Increment the count.
- Write the incremented value back to the database - and repeat that for every instance.
With Functions, all you need to do is to use incrcounter() which does all this asynchronously and accurately, without overwriting other vote increments.
Functions Hosting
Functions doesn't require you to spin up your servers or incur increased latency through call-outs to external server/serverless technology. The code you write or leverage runs within PubNub's operational environment, giving you the scale and speed that you need for your applications.
Functions modules and API
For more information about the Functions modules and API, check out the Functions modules and REST API documentation.
Performance and Limitations
Functions have several performance tiers, which differ by the maximum requests per second (RPS) a Function can make.
For our Free and Starter plan users, the typical achievable performance is 15 RPS (one standard XHR call, Webhook, Log, etc.). It's important to note that RPS is not a simple measure of requests. Instead, it's our internal adaptation of RPS, which can vary across different types of Functions.
Functions run on the Starter plan can scale up to 10 times in less than 20 seconds, which significantly increases the computing power for your Functions should their load increase. Functions run on the Free plan do not scale, so if your Functions load exceeds the RPS limit, they will either time out or take a long time to execute.
You may consider increasing the computing power if your Function has performance issues or requires more RPS. The hardware Functions run on comes in various tiers. If you are interested in increasing the computing power for your Functions, contact sales.
Functions v1 vs. v2
PubNub offers Functions in two versions that differ in terms of scope, terminology, UI flow on the Admin Portal, and library or REST API access. This table collects the most important differences.
| Aspect | Function v1 | Functions v2 |
|---|---|---|
| Availability | Existing PubNub Functions users | New PubNub Functions users |
| Terminology | A collection of Functions is called a Module. | A collection of Functions is called a Package. |
| Scope | A Module collects Functions running on a given keyset. | A Package collects Functions running on a higher account level that you can associate with various keysets. |
| Version control | There is no mechanism for tracking changes in Modules. This means you can only have one version of a given Function. | You can have multiple Revisions (versions/snapshots) of a single Package, allowing for updates, rollbacks, and tracking changes in multiple Functions. |
| Deployment model | You can deploy a Module only on a single keyset. | You can deploy a Package on different keysets, allowing control over which version of the Package is running in different environments. |
| Management | Module lets you start/stop a set of Functions under a keyset. Deploying it on other keysets involves additional actions. | Convenient bulk operations across different keysets. A Package lets you start/stop/update a Revision (with a set of Functions) on multiple keysets at once. |
| Public API | Not available | Available |
| Key-Value storage | Available only as a module in a Function's toolbox. | Additional REST API for secrets, values, and counters. |
| Built-in modules |
For details on how to create, deploy, and manage Functions, follow these links:
Event Types
There are numerous event types a Function can be triggered by:
-
Before Publish or Fire: operates on a message before the message is distributed to subscribers/users (synchronous)
-
After Publish or Fire: operates on a copy of a message simultaneously with the original message being distributed to subscribers/users, and doesn't return a timetoken (asynchronous)
-
Before Publish File: operates on a message before files are distributed to subscribers/users (synchronous)
-
After Publish File: operates on a copy of a message simultaneously with files being distributed to subscribers/users, and doesn't return a timetoken (asynchronous)
-
Before Signal: operates on a message before signals are distributed to subscribers/users (synchronous)
-
After Signal: operates on a copy of a message simultaneously with the signal being distributed to subscribers/users, and doesn't return a timetoken (asynchronous)
-
After Presence: code logic runs after presence events (join, leave) (asynchronous)
-
On Request: code logic runs upon URI request, such as from curl or a Web application (synchronous)
-
On Interval: code logic runs every time interval, specified in
milliseconds(asynchronous) -
Subscribe with On Interval: a combination of Functions that allows users to subscribe to channels with an ability to react to these subscribes in intervals.
What Function Type to Use
Synchronous (blocking) event types, such as Before Publish or Fire, operate on the original message, before it's delivered. The logic of the Function must complete before the message is released to continue its trip to the subscribers, which introduces a delivery delay (from microseconds for simple arithmetic, to potentially hundreds or thousands of milliseconds if interacting with a third-party system).
Asynchronous (non-blocking) event types, such as After Publish or Fire, operate on a copy of the message that includes any processing by synchronous Functions, and don't increase latency. Asynchronous Functions can't change the original message, the message received by the client is always identical to the message that triggered the Function.
Use a synchronous Function if you need to do any of the following:
- Block a message
- Alter a message or its payload
- Alter a message's meta information
- Re-route a message to a different channel
For most other operations, you can use an asynchronous Function.
You can also use both function types on a given channel. For example, if you want to change messages (synchronous), and also want to send data to an external system about them (asynchronous), split the logic between two Functions, and keep the network I/O operations out of the synchronous Function. This will keep the synchronous Function's latency as low as possible, for the best user experience.
The following sections describe these Function types in greater detail.
Before Publish or Fire Functions
These Functions are synchronous.
Use a Before Publish or Fire Function if you want to change a message in-flight (add a new attribute or modify an existing attribute). Some applications of Before Publish or Fire include:
- Translating a message from one language to another
- Conversion of values from Imperial to Metric
- Detecting (and censoring) profanity
- Detecting (and normalization) of missing or illegal values
After Publish or Fire Functions
These Functions are asynchronous.
Use an After Publish or Fire Function if you want to pass the original message through the PubNub Platform intact, and also use it as a trigger to execute other logic (such as logging and message teeing). Some applications of After Publish or Fire include:
- Asynchronous third-party message logging (such as ElasticSearch)
- Mentions, keywords, and other string triggers
- Message teeing and forwarding
Before Publish File
These Functions are synchronous.
Use a Before Publish File Function if you want to trigger code before the file message is published to a channel. Some applications of Before Publish File include:
- Evaluating file contents via a third party AI/ML capabilities.
- Routing the message to a moderator channel if the service marks the file as inappropriate.
- Checking the file for copyright infringements via a third party service and possibly deleting the file from Message Persistence.
After Publish File
These Functions are asynchronous.
Use an After Publish File Function if you want to trigger code after the file message is published to a channel. Some applications of After Publish File include:
- Asynchronous file message logging
- File message auditing
- Business metrics gathering
Before Signal Functions
These Functions are synchronous.
Use a Before Signal Function if you want to change signal data (a small message sent using the Signal API) in-flight, either by adding a new attribute or modifying an existing attribute. Some applications of Before Signal include:
- Custom logic based on user typing; for example, when a customer starts typing after many minutes in a call center chat, send an urgent message to the agent letting them know the customer has re-engaged
- Pass letters as they're being typed into a phrase dictionary for automatic suggestion/completion functionality
- Integrate geographic data into the overall chat application experience
After Signal Functions
These Functions are asynchronous.
Use an After Signal Function if you want to pass the original signal data through the PubNub Platform intact, and also use it as a trigger to execute other logic, such as integration with logging services. Some applications of After Signal include:
- Asynchronous third-party message logging (such as ElasticSearch)
- Saving typing state into user real-time profile
- Saving location data into user profile
After Presence Functions
These Functions are asynchronous and trigger on subscriber (user) presence events, not messages. Presence events occur as users connect and disconnect from the real-time application. For example, when a user enters a chat room, a join event is triggered, and when they leave the chat room, a leave event occurs. The following Presence events are available:
| Event | Description |
|---|---|
join | A user subscribes to a channel. |
leave | A user unsubscribes from a channel. |
timeout | A timeout event is fired when a connection to a channel is severed and the subscriber hasn't been seen in 320 seconds (just over 5 minutes). This timeout interval can be customized using the heartbeat and heartbeat interval settings (SDK v3.6 or later). |
state-change | A state-change event will be fired anytime the state is changed using the state API (Function signature varies by SDK). |
interval | An occupancy count is sent every 10 seconds (the default setting for the Presence Interval property, which is also configurable in the Presence add-on panel in your account admin portal). |
This presence events are also available as Callbacks, webhooks that can be called directly from the Presence service when these events occurred. Configured in your account admin portal, the HTTP callback URI must be publicly accessible. The callback logic could be managed by yourself, in your own environment in a non-PubNub service, or it could be pointing to an On Request Function (see below).
Use an After Presence event type if you want to pass a presence event through the PubNub Platform intact, and also use it as a trigger to execute other logic (such as logging and message teeing). Some applications of After Presence include:
- Sending an SMS to an offline user when a member of their priority buddy-list comes online
- Updating an on-hold wait time KV store as JOIN and LEAVE events occur
- Monitor a user's online/offline time card as they JOIN and LEAVE an app
On Request Functions
These Functions are synchronous.
On Request Functions let you create publicly accessible REST API methods. In addition to providing a lightweight approach to publicly accessing your PubNub code, you can also use on-request Functions in your other Functions as a replacement for pubnub.fire(). This offers several advantages, such as:
- Breaking your main Function into smaller components for ease of maintainability
- Defining a utility Function that you'll call from many other Functions
- Returning data to the calling Function for any number of reasons
On Interval Functions
These Functions are asynchronous.
On Interval Functions let you create functionality that will execute automatically at the specified time interval. This functionality makes it easy to add logic that would otherwise be located in other systems and servers, whether non-PubNub cloud or on-premises. The execution environment provides easy access to PubNub functionality and data. Some applications of On Interval include:
- Periodically updating KV store cache data based on message data stored in history
- Periodically sending packaged-up message data for use in an external service
- Periodically updating User ID metadata based on message activity
User ID / UUID
User ID is also referred to as UUID/uuid in some APIs and server responses but holds the value of the userId parameter you set during initialization.
Subscribe with On Interval Functions
These Functions are asynchronous.
Limited availability
This Function type is not available to all users. If you'd like to use it, contact support.
Subscribe with On Interval Function lets you create custom functionality that allows you to subscribe to the traffic and execute additional code in intervals as a reaction to these subscribes. This lets you implement complex logic that involves periodic reactions to the subscribe traffic.
Some applications of the Subscribe with On Interval include:
- Throttling the messages with rerouting to a different channel which can be listened to in Events & Actions to be stored for later analysis.
- Aggregation of message reactions to be periodically displayed on screen.