Cron / Scheduler API

The Cron API lets your resource run periodic background tasks. There are two ways to use it:

1. Backend cron — configure cron tasks in createResourceServer(). Timers run as JS setInterval while the backend process is alive.
2. Frontend cron — register timers from the iframe SDK. Rust manages the timers and emits events back to your iframe.

Capability required: cron:register

Backend (Node.js)

import { createResourceServer } from "@rightplace/sdk/server";

const server = createResourceServer({
  cron: {
    syncData: {
      interval: "15m",
      handler: async ({ rp }) => {
        const data = await rp.http.request("https://api.example.com/data");
        await rp.storage.set("latestData", data.body);
        rp.log("info", "Data synced successfully");
      },
    },

    cleanupCache: {
      interval: "1h",
      handler: async ({ rp }) => {
        const keys = await rp.storage.list("cache:");
        for (const key of keys) {
          await rp.storage.delete(key);
        }
      },
    },
  },

  methods: {
    getLatestData: async (_params, { rp }) => {
      const raw = await rp.storage.get("latestData");
      return raw ? JSON.parse(raw) : null;
    },
  },
});

server.start();

The backend can also register/unregister timers dynamically:

// Inside a method handler
async startPolling(_params, { rp }) {
  await rp.cron.register("pollApi", "30s");
},

async stopPolling(_params, { rp }) {
  await rp.cron.unregister("pollApi");
},

Frontend (iframe)

import { createResourceClient } from "@rightplace/sdk";

const rp = createResourceClient();
await rp.ready();

// Register a periodic task
await rp.cron.register("refreshData", "30s");

// Listen for tick events
const off = rp.cron.onTick("refreshData", () => {
  console.log("Tick! Time to refresh.");
  // Fetch new data, update UI, etc.
});

// Later: stop the timer
await rp.cron.unregister("refreshData");
off(); // Remove the listener

Interval Format

Format	Example	Description
Ns	"30s"	Every N seconds
Nm	"15m"	Every N minutes
Nh	"1h"	Every N hours

API Reference

rp.cron.register(taskName, interval)

Registers a periodic timer. If a timer with the same name already exists, it is replaced.

Parameter	Type	Description
taskName	string	Unique name for the task
interval	string	Interval string (e.g. "30s", "15m", "1h")

rp.cron.unregister(taskName)

Stops and removes a periodic timer.

Parameter	Type	Description
taskName	string	Name of the task to remove

rp.cron.onTick(taskName, callback) (frontend only)

Listens for tick events from a registered timer.

Parameter	Type	Description
taskName	string	Name of the task
callback	() => void	Called on each tick
Returns	() => void	Unsubscribe function

Manifest Configuration

{
  "capabilities": [
    "cron:register"
  ],
  "backend": {
    "entry": "backend/index.mjs",
    "persistent": true
  }
}

Set persistent: true so your backend stays running between method calls, allowing cron timers to fire.

Notes

• Backend cron tasks only run while the backend process is alive. If persistent is false, the backend shuts down after idle timeout and cron tasks stop.
• Frontend cron tasks run as Rust-side timers and persist as long as the resource is loaded.
• The minimum interval is "1s", but avoid intervals shorter than "30s" to limit resource usage.
• Re-registering a task with the same name replaces the existing timer.
• Errors in cron handlers are logged but do not crash the backend process.