Skip to main content

Functions Quickstart

PhotonIQ Functions provides a real-time method for enterprises to create and interact with their services using the Functions CLI or Functions API .

In this quickstart guide, you'll learn how to begin with PhotonIQ Functions using your preffered language by:

  • Creating a function
  • Testing the function locally
  • Deploying the function to remote PhotonIQ Functions server

Prerequisite

Using the PhotonIQ Functions locally requires the CLI tool installed. Follow these steps to install or update the CLI tool:

  1. Install the Rust compiler and WebAssembly libraries required for creating Rust functions with:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32-wasi
  1. Install the NPM package for the CLI tool with this command:
npm i -g  @macrometa/faas
  1. Launch the CLI with the faas help command.
tip

For more information on available commands, refer to the Functions CLI commands guide.

Choose your preferred language or framework from the tabs below to begin working with PhotonIQ Functions. The implementation process varies depending on your selection.

Create a function

  1. To scaffold a new Next.js project with the Functions CLI, run the following command:
faas new <projectName> --lang nextjs

If successful, it returns a response similar to this:

Template function has been created in path: functions/projectName
Configuration can be modified in the file: functions/projectName/photoniq.toml

This command creates a functions and photoniq-faas-sdk directory. The functions directory contains the template function Next.js app created.

  1. Navigate to the /src/app/api directory in the template function Next.js app. By default, some template routes are defined in pingjs/route.js and pingts/route.ts. Below is an example of pingjs/route.js:
route.js
export function GET(req) {
return new Response('[GET] PhotonIQ FaaS function is working.', {
status: 200,
headers: { 'Content-Type': 'text/plain' },
});
}

export function POST(req) {
return new Response('[POST] PhotonIQ FaaS function is working.', {
status: 200,
headers: { 'Content-Type': 'text/plain' },
});
}

For this example guide, use the default route provided. You can create other routes based on your requirements.

  1. Modify the GET function in pingjs/route.js to the following code, which will display [GET] PhotonIQ FaaS function is working. Hello, PhotonIQ NextJS Functions is working when the route is accessed.
route.js
export function GET(req) {
return new Response('[GET] PhotonIQ FaaS function is working. Hello, PhotonIQ Next.js Functions is working', {
status: 200,
headers: { 'Content-Type': 'text/plain' },
});
}

Test the function locally

  1. Use the faas build command to install the required dependencies and build the Next.js app with the function:
faas build 
tip

Be sure to run this command in the functions/<projectName> directory.

  1. After the build is successful, start the local development server using the faas run command:
faas run  

It is served on http://localhost:8080 by default. Open http://localhost:8080 in your browser and test the routes you created in the function.

To test the route in this example guide, go to http://localhost:8080/api/pingjs. It displays the following message: [GET] PhotonIQ FaaS function is working. Hello, PhotonIQ Next.js Functions is working.

Now, you can create other routes based on your requirements and test them locally. For these functions to be globally accessible, visit Deploying the function remotely.

Deploying the function to remote PhotonIQ Functions server

Running functions locally limits their usage to your local server. To make your functions globally available, PhotonIQ Functions uses geo-distributed GDN servers, ensuring high availability and faster performance by processing at the closest point of presence to the user. Furthermore, the highly distributed nature of the GDN means every function is georeplicated in all regions in the fabric.

Before you proceed, contact your Macrometa personnel to provide these authentication credentials for accessing the PhotonIQ Functions remote server:

  • API_KEY
  • API_URL

The faas remote command will request these credentials on your first attempt.

  1. Use the faas remote deploy command to deploy the function:
faas remote deploy <projectName>
  1. To check the status of the deployment, run this command:
faas remote status <projectName>

If successful, the response is similar to this:

version: 0.0.1
url: <function_url>
status: success
name: <projectName>
lastUpdated: 2024-08-04 16:52:35

Use the <function_url> to access your function on the browser.

  1. Once deployed, execute the remote function with this command:
faas remote execute <projectName>
  1. To delete the function from the remote server, use:
faas remote delete <projectName>

Next steps