Add core TypeScript submodules: cron, retry, rate-limit, and crypto by bradleyshep · Pull Request #5903 · clockworklabs/SpacetimeDB

bradleyshep · 2026-09-09T18:29:18Z

Description of Changes

Adds reusable scheduling, retry, rate-limit, and cryptographic helpers for SpacetimeDB TypeScript modules.

Cron: calendar and interval jobs with typed arguments, time zones, and run history.
Retry: scheduled attempts, exponential backoff, and attempt history.
Rate-limit: fixed-window limits with configuration and administrative controls.
Crypto: hashing, encoding, and webhook-signature helpers.
Shared example UI/server support, package documentation, tests, and examples.
Registers the packages in the pnpm workspace and existing lint/build commands. Adds a submodule CI job for type checks, tests, and builds.

This is the prerequisite branch for the remaining submodule groups. It is based on master commit 3653d2ed4.

Example screenshots

Existing example screenshots from #5823:

Cron

Rate Limit

API and ABI breaking changes

No existing SpacetimeDB API or ABI is changed. This adds new TypeScript package APIs that need review before merge.

Rollback safety impact

n/a. This adds opt-in TypeScript packages and examples; it does not change existing server storage formats.

Expected complexity level and risk

3/5

The packages are opt-in and do not change existing server behavior. Complexity is in scheduling, retry recovery, and cron's direct use of the internal spacetime:sys@2.0 host ABI. Review failure recovery and repeated execution for applications that use these packages.

Testing

Verified locally on bradley/submodules-core:

Frozen-lockfile install for the root, SDK, and present submodule workspaces.
Type checks for the added packages.
Existing test scripts for the added packages and examples.
Build scripts for the added packages and examples.
Regenerate client bindings and verify no tracked changes.
Lint and formatting checks for the added packages and examples.
Verify workspace dependencies are present in this branch.
Review the public APIs, documentation, and cron host-ABI dependency.
Run local scheduling/recovery smoke tests against a running SpacetimeDB instance.

Commands used for this group:

pnpm -r -F "./spacetime-cron-ts/**" -F "./spacetime-retry-ts/**" -F "./spacetime-rate-limit-ts/**" -F "./spacetime-crypto-ts/**" -F "./spacetime-submodule-shared-ts/**" run typecheck
pnpm -r -F "./spacetime-cron-ts/**" -F "./spacetime-retry-ts/**" -F "./spacetime-rate-limit-ts/**" -F "./spacetime-crypto-ts/**" -F "./spacetime-submodule-shared-ts/**" run test
pnpm -r -F "./spacetime-cron-ts/**" -F "./spacetime-retry-ts/**" -F "./spacetime-rate-limit-ts/**" -F "./spacetime-crypto-ts/**" -F "./spacetime-submodule-shared-ts/**" run build
pnpm -r -F "./spacetime-cron-ts/**" -F "./spacetime-retry-ts/**" -F "./spacetime-rate-limit-ts/**" -F "./spacetime-crypto-ts/**" -F "./spacetime-submodule-shared-ts/**" run lint

The TypeScript SDK was built first. Live deployment and provider tests were not run during split validation. Existing workspace peer-dependency warnings remain.

clockwork-tien

There are places where we are using snake_case instead of camelCase, worth checking thoroughly to ensure consistency. I have also left additional comments inline.

clockwork-tien · 2026-09-16T14:00:59Z

+  "name": "@spacetimedb/crypto",
+  "description": "Deterministic hashing, encoding, and webhook-signature helpers for SpacetimeDB TypeScript modules.",
+  "version": "0.1.0",
+  "license": "BUSL-1.1",


Is BUSL-1.1 license intentional?

should be apache 2

clockwork-tien · 2026-09-16T14:04:08Z

+      : []
+);
+
+export const start_reactor = spacetimedb.procedure(


These should be lowerCamelCase

Suggested change

export const start_reactor = spacetimedb.procedure(

export const startReactor = spacetimedb.procedure(

clockwork-tien · 2026-09-16T14:04:20Z

+  }
+);
+
+export const tap_reactor = spacetimedb.procedure(


These should be lowerCamelCase

Suggested change

export const tap_reactor = spacetimedb.procedure(

export const tapReactor = spacetimedb.procedure(

clockwork-tien · 2026-09-16T14:04:38Z

+  }
+);
+
+export const buy_upgrade = spacetimedb.procedure(


Suggested change

export const buy_upgrade = spacetimedb.procedure(

export const buyUpgrade = spacetimedb.procedure(

clockwork-tien · 2026-09-16T14:04:46Z

+  }
+);
+
+export const repair_reactor = spacetimedb.procedure(


Suggested change

export const repair_reactor = spacetimedb.procedure(

export const repairReactor = spacetimedb.procedure(

clockwork-tien · 2026-09-16T14:09:02Z

+    return isAdmin(ctx) ? takeRows(retryCtx.db.retryTask.iter()) : [];
+  }
+
+  function retryHistoryAdmin(ctx: unknown): RetryHistoryRow[] {


retryHistory is never pruned, and with takeRows(iter(), 1000) after 1000 attempts the admin view stops showing anything recent

clockwork-tien · 2026-09-16T14:09:58Z

+npm install @spacetimedb/retry spacetimedb@^2.8.3
+```
+
+Requires SpacetimeDB 2.8.3 or later for submodule mounting.


Seems incorrect since nothing here mounts (no export default schema etc)

clockwork-tien · 2026-09-16T14:11:43Z

+
+## Requirements
+
+- SpacetimeDB CLI 2.8.3


Is it expected to pin the requirement to 2.8.3? e.g. the peer dependency is workspace:^

clockwork-tien · 2026-09-16T14:12:27Z

@@ -0,0 +1,340 @@
+// Verify the pure-TS implementations against published test vectors.


Worth adding here that hashing is @noble/hashes, not an implementation in this package

clockwork-tien · 2026-09-16T14:13:38Z

+      ranAt: retryCtx.timestamp,
+    });
+
+    const result = dispatchRetry(


Seems if a handler throws instead of returning retryFailed, the whole reducer aborts. Worth adding try/catch here

clockwork-tien

I noticed a lot of the public surface is only public because the settings are passed in on every call instead of being encapsulated by the library. I would be interested to hear if there is reasoning behind this.

The example writes its own wrapper in consumer code to call the rate limiter which should be handled internally by the library. Here buildRateLimitKey is exported only so a caller can build the key, and scope is passed in twice. With the current design the caller has to build the argument, so the builder has to be exported.

function consumeAction(
  tx: Tx,
  scope: string,
  actorKey: string,
  limit: number,
  windowSeconds: number,
  cost = 1,
) {
  return rateLimit.consumeRateLimit(tx.as.rateLimit, {
    key: rateLimit.buildRateLimitKey(scope, actorKey),
    scope,
    limit,
    windowSeconds,
    cost,
  });
}

const result = consumeAction(tx, TAP_SCOPE, key, tapLimit, TAP_WINDOW_SECONDS);

Possible improvements, one way is a client(config) per package:

const tapLimiter = rateLimit.client({ scope: TAP_SCOPE, windowSeconds: TAP_WINDOW_SECONDS });

const result = tapLimiter.consume(tx.as.rateLimit, { key, limit: tapLimit });

A few more points:

Worth exporting the error codes, seems there are quite a few of them, e.g. rate_limit.not_authorized, since renaming one breaks callers silently
Worth having a setup function per package with consistent naming and signature, client(config) when the module loads and install(ctx) in init (resend.install rather than resend.installResend), instead of

spacetimeCron(sdk) + createCron(jobs, opts) // needs both
createRetrySubmodule(deps, handlers, auth?)
installRateLimit(ctx)   
installRateLimitState(ctx, opts?)
installResend(ctx)
installRetry(ctx)

clockwork-tien · 2026-09-24T14:20:22Z

+export { installRateLimit } from './submodule/install';
+export {
+  DEFAULT_SWEEP_BATCH,
+  MAX_SWEEP_BATCH,


DEFAULT_SWEEP_BATCH and MAX_SWEEP_BATCH are public only because install.ts and operations.ts import them from '../index' rather than '../limit'

clockwork-tien · 2026-09-24T14:20:47Z

+export { installRateLimit } from './submodule/install';
+export {
+  DEFAULT_SWEEP_BATCH,
+  MAX_SWEEP_BATCH,


DEFAULT_SWEEP_BATCH and MAX_SWEEP_BATCH are public only because install.ts and operations.ts import them from '../index' rather than '../limit'

clockwork-tien · 2026-09-24T14:20:59Z

+  DEFAULT_SWEEP_BATCH,
+  MAX_SWEEP_BATCH,
+  assertRateLimitSweepBatch,
+  DEFAULT_SWEEP_INTERVAL_SECONDS,


DEFAULT_SWEEP_INTERVAL_SECONDS is not used outside limit.ts

clockwork-tien · 2026-09-24T14:21:32Z

+export interface ConsumeRateLimitOpts {
+  key: string;
+  scope: string;
+  limit: number;
+  windowSeconds: number;
+  cost?: number;
+}


The policy is passed on every call so 2 places can set the same limit differently and a typo in scope makes a new bucket

clockwork-tien · 2026-09-24T14:22:03Z

+  let deleted = 0;
+  for (const row of expiredRows) {
+    if (deleted >= maxRows) break;
+    if ((row.expiresAt.microsSinceUnixEpoch as bigint) > nowMicros) break;


The sweep breaks on the first unexpired row so with iter() everything past it is skipped

clockwork-tien · 2026-09-24T14:25:07Z

+ * contains at least one valid v1 signature AND the timestamp is within
+ * tolerance.
+ */
+export function verifyStripeSignature(opts: StripeVerifyOpts): boolean {


All failures return false so failure info is swallowed. Worth returning { ok: false, reason } instead, since it is a library and the consumer decides what to surface

clockwork-tien · 2026-09-24T14:25:32Z

+  { name: 'rate_limit_admin_identity', public: false },
+  {
+    identity: t.identity().primaryKey(),
+    addedAtMicros: t.i64(),


Here is t.i64() where every other time column is t.timestamp() so clients get a plain number for this one

clockwork-tien · 2026-09-24T14:25:56Z

+
+function requireAdmin(ctx: ReducerModuleCtx): void {
+  if (ctx.db.rateLimitAdminIdentity.identity.find(ctx.sender) == null) {
+    throw new SenderError('rate_limit.not_authorized');


This string is the entire response body, with no code field beside it, and it is not exported. The only way to branch on the reason is to compare the string, so a rename breaks consumers with no warning

clockwork-tien · 2026-09-24T14:26:21Z

@@ -0,0 +1,17 @@
+export { sha256, SHA256_BYTES } from './sha256.ts';


Importing with .ts needs allowImportingTsExtensions, and the tsconfig spacetime init generates does not set this so the first spacetime build fails. Worth shipping compiled dist instead

clockwork-tien · 2026-09-24T14:26:57Z

+  const out = new Uint8Array((s.length / 4) * 3 - pad);
+  let oi = 0;
+  for (let i = 0; i < s.length; i += 4) {
+    const c0 = lookup[s.charCodeAt(i)];


Here base64 accepts invalid input so a bad signing secret fails silently. With lookup 256 long, a char with a code above 255 is undefined, undefined < 0 is false so it decodes as A instead of hitting the base64: invalid char guard just below

Configure fixed policies once, expose stable errors, keep installers idempotent, and support admin revocation. Remove internal sweep exports and align init naming. Verify packed consumers with the default TypeScript template.

bradleyshep added 2 commits September 8, 2026 17:18

Add core TypeScript submodules and shared example support

646954a

Reuse noble hex conversion helpers

e0f5d86

bradleyshep requested review from bfops, cloutiertyler and jdetter as code owners September 9, 2026 18:29

Merge branch 'master' into bradley/submodules-core

a513320

bradleyshep mentioned this pull request Sep 9, 2026

Submodules (TS) #5823

Closed

7 tasks

bradleyshep requested a review from aasoni September 10, 2026 12:56

clockwork-tien requested changes Sep 16, 2026

View reviewed changes

bradleyshep and others added 4 commits September 17, 2026 08:52

Merge branch 'master' into bradley/submodules-core

f38ca85

Address core submodule review and retry failure handling

5418e2f

Use matching workspace artifacts for submodule CI

983341c

Merge branch 'master' into bradley/submodules-core

720daa3

clockwork-tien requested changes Sep 24, 2026

View reviewed changes

bradleyshep added 2 commits September 24, 2026 13:00

Simplify rate-limit policy setup and reject invalid base64

470045f

Configure fixed policies once, expose stable errors, keep installers idempotent, and support admin revocation. Remove internal sweep exports and align init naming. Verify packed consumers with the default TypeScript template.

Keep Retry compatible with generated consumer TypeScript options

0cce532

	export const start_reactor = spacetimedb.procedure(
	export const startReactor = spacetimedb.procedure(

	export const tap_reactor = spacetimedb.procedure(
	export const tapReactor = spacetimedb.procedure(

	export const buy_upgrade = spacetimedb.procedure(
	export const buyUpgrade = spacetimedb.procedure(

	export const repair_reactor = spacetimedb.procedure(
	export const repairReactor = spacetimedb.procedure(

		@@ -0,0 +1,340 @@
		// Verify the pure-TS implementations against published test vectors.

		@@ -0,0 +1,17 @@
		export { sha256, SHA256_BYTES } from './sha256.ts';

Conversation

bradleyshep commented Sep 9, 2026

Description of Changes

Example screenshots

Cron

Rate Limit

API and ABI breaking changes

Rollback safety impact

Expected complexity level and risk

Testing

Uh oh!

clockwork-tien left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

clockwork-tien left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants