refactor: rename heartbeat_timeout_seconds to debounce with interval type (#528)

# Replace `heartbeat_timeout_seconds` with `debounce` interval in worker management

This PR changes the worker function debounce mechanism from using an integer seconds field to a proper PostgreSQL interval type. The change:

- Renames `heartbeat_timeout_seconds` to `debounce` in the `worker_functions` table
- Uses the native interval type instead of converting integers to intervals
- Adds a check constraint ensuring debounce is at least 1 second
- Updates all references in functions and comments to use the new field name
- Updates TypeScript type definitions to reflect the schema change

This improves type safety and makes the code more semantically clear by using the proper PostgreSQL data type for time intervals.

Author: jumski

pkgs/core/schemas/0056_table_worker_functions.sql

@@ -4,7 +4,8 @@
 create table if not exists pgflow.worker_functions (
   function_name text not null primary key,
   enabled boolean not null default true,
-  heartbeat_timeout_seconds integer not null default 6,
+  debounce interval not null default '6 seconds'
+  check (debounce >= '1 second'),
   last_invoked_at timestamptz,
   created_at timestamptz not null default now(),
   updated_at timestamptz not null default now()
@@ -19,8 +20,8 @@ comment on column pgflow.worker_functions.function_name is
 comment on column pgflow.worker_functions.enabled is
 'Whether ensure_workers() should ping this function';
 
-comment on column pgflow.worker_functions.heartbeat_timeout_seconds is
-'How long before considering a worker dead (no heartbeat)';
+comment on column pgflow.worker_functions.debounce is
+'Minimum interval between invocation attempts for this function';
 
 comment on column pgflow.worker_functions.last_invoked_at is
 'When ensure_workers() last pinged this function (used for debouncing)';

pkgs/core/schemas/0059_function_ensure_workers.sql

@@ -28,12 +28,12 @@ as $$
 
     -- Find functions that pass the debounce check
     debounce_passed as (
-      select wf.function_name, wf.heartbeat_timeout_seconds
+      select wf.function_name, wf.debounce
       from pgflow.worker_functions as wf
       where wf.enabled = true
         and (
           wf.last_invoked_at is null
-          or wf.last_invoked_at < now() - (wf.heartbeat_timeout_seconds || ' seconds')::interval
+          or wf.last_invoked_at < now() - wf.debounce
         )
     ),
 
@@ -44,7 +44,7 @@ as $$
       inner join debounce_passed as dp on w.function_name = dp.function_name
       where w.stopped_at is null
         and w.deprecated_at is null
-        and w.last_heartbeat_at > now() - (dp.heartbeat_timeout_seconds || ' seconds')::interval
+        and w.last_heartbeat_at > now() - dp.debounce
     ),
 
     -- Determine which functions should be invoked
@@ -104,7 +104,7 @@ comment on function pgflow.ensure_workers() is
 'Ensures worker functions are running by pinging them via HTTP when needed.
 In local mode: pings ALL enabled functions (ignores debounce AND alive workers check).
 In production mode: only pings functions that pass debounce AND have no alive workers.
-Debounce: skips functions pinged within their heartbeat_timeout_seconds window (production only).
+Debounce: skips functions pinged within their debounce interval (production only).
 Credentials: Uses Vault secrets (supabase_service_role_key, supabase_project_id) or local fallbacks.
 URL is built from project_id: https://{project_id}.supabase.co/functions/v1
 Returns request_id from pg_net for each HTTP request made.';

pkgs/core/src/database-types.ts

@@ -317,25 +317,25 @@ export type Database = {
       worker_functions: {
         Row: {
           created_at: string
+          debounce: unknown
           enabled: boolean
           function_name: string
-          heartbeat_timeout_seconds: number
           last_invoked_at: string | null
           updated_at: string
         }
         Insert: {
           created_at?: string
+          debounce?: unknown
           enabled?: boolean
           function_name: string
-          heartbeat_timeout_seconds?: number
           last_invoked_at?: string | null
           updated_at?: string
         }
         Update: {
           created_at?: string
+          debounce?: unknown
           enabled?: boolean
           function_name?: string
-          heartbeat_timeout_seconds?: number
           last_invoked_at?: string | null
           updated_at?: string
         }

pkgs/core/supabase/migrations/20251209074533_pgflow_worker_management.sql

@@ -8,20 +8,21 @@ ALTER TABLE "pgflow"."workers" ADD COLUMN "stopped_at" timestamptz NULL;
 CREATE TABLE "pgflow"."worker_functions" (
   "function_name" text NOT NULL,
   "enabled" boolean NOT NULL DEFAULT true,
-  "heartbeat_timeout_seconds" integer NOT NULL DEFAULT 6,
+  "debounce" interval NOT NULL DEFAULT '00:00:06'::interval,
   "last_invoked_at" timestamptz NULL,
   "created_at" timestamptz NOT NULL DEFAULT now(),
   "updated_at" timestamptz NOT NULL DEFAULT now(),
-  PRIMARY KEY ("function_name")
+  PRIMARY KEY ("function_name"),
+  CONSTRAINT "worker_functions_debounce_check" CHECK (debounce >= '00:00:01'::interval)
 );
 -- Set comment to table: "worker_functions"
 COMMENT ON TABLE "pgflow"."worker_functions" IS 'Registry of edge functions that run pgflow workers, used by ensure_workers() cron';
 -- Set comment to column: "function_name" on table: "worker_functions"
 COMMENT ON COLUMN "pgflow"."worker_functions"."function_name" IS 'Name of the Supabase Edge Function';
 -- Set comment to column: "enabled" on table: "worker_functions"
 COMMENT ON COLUMN "pgflow"."worker_functions"."enabled" IS 'Whether ensure_workers() should ping this function';
--- Set comment to column: "heartbeat_timeout_seconds" on table: "worker_functions"
-COMMENT ON COLUMN "pgflow"."worker_functions"."heartbeat_timeout_seconds" IS 'How long before considering a worker dead (no heartbeat)';
+-- Set comment to column: "debounce" on table: "worker_functions"
+COMMENT ON COLUMN "pgflow"."worker_functions"."debounce" IS 'Minimum interval between invocation attempts for this function';
 -- Set comment to column: "last_invoked_at" on table: "worker_functions"
 COMMENT ON COLUMN "pgflow"."worker_functions"."last_invoked_at" IS 'When ensure_workers() last pinged this function (used for debouncing)';
 -- Create "cleanup_ensure_workers_logs" function
@@ -122,12 +123,12 @@ with
 
     -- Find functions that pass the debounce check
     debounce_passed as (
-      select wf.function_name, wf.heartbeat_timeout_seconds
+      select wf.function_name, wf.debounce
       from pgflow.worker_functions as wf
       where wf.enabled = true
         and (
           wf.last_invoked_at is null
-          or wf.last_invoked_at < now() - (wf.heartbeat_timeout_seconds || ' seconds')::interval
+          or wf.last_invoked_at < now() - wf.debounce
         )
     ),
 
@@ -138,7 +139,7 @@ with
       inner join debounce_passed as dp on w.function_name = dp.function_name
       where w.stopped_at is null
         and w.deprecated_at is null
-        and w.last_heartbeat_at > now() - (dp.heartbeat_timeout_seconds || ' seconds')::interval
+        and w.last_heartbeat_at > now() - dp.debounce
     ),
 
     -- Determine which functions should be invoked
@@ -197,7 +198,7 @@ $$;
 COMMENT ON FUNCTION "pgflow"."ensure_workers" IS 'Ensures worker functions are running by pinging them via HTTP when needed.
 In local mode: pings ALL enabled functions (ignores debounce AND alive workers check).
 In production mode: only pings functions that pass debounce AND have no alive workers.
-Debounce: skips functions pinged within their heartbeat_timeout_seconds window (production only).
+Debounce: skips functions pinged within their debounce interval (production only).
 Credentials: Uses Vault secrets (supabase_service_role_key, supabase_project_id) or local fallbacks.
 URL is built from project_id: https://{project_id}.supabase.co/functions/v1
 Returns request_id from pg_net for each HTTP request made.';

pkgs/core/supabase/migrations/atlas.sum

@@ -1,4 +1,4 @@
-h1:+LFk0wyD7sBjvwZW93t7THECms67qWV2Vm0E5GHTCxQ=
+h1:s6n1PLk8xdvwsEbFcEbLUMaRj0zxGmAfBcaVkk3GKak=
 20250429164909_pgflow_initial.sql h1:I3n/tQIg5Q5nLg7RDoU3BzqHvFVjmumQxVNbXTPG15s=
 20250517072017_pgflow_fix_poll_for_tasks_to_use_separate_statement_for_polling.sql h1:wTuXuwMxVniCr3ONCpodpVWJcHktoQZIbqMZ3sUHKMY=
 20250609105135_pgflow_add_start_tasks_and_started_status.sql h1:ggGanW4Wyt8Kv6TWjnZ00/qVb3sm+/eFVDjGfT8qyPg=
@@ -12,4 +12,4 @@ h1:+LFk0wyD7sBjvwZW93t7THECms67qWV2Vm0E5GHTCxQ=
 20251103222045_pgflow_fix_broadcast_order_and_timestamp_handling.sql h1:K/XnZpOmxfelsaNoJbR5HxhBrs/oW4aYja222h5cps4=
 20251104080523_pgflow_upgrade_pgmq_1_5_1.sql h1:Fw7zpMWnjhAHQ0qBJAprAvGl7dJMd8ExNHg8aKvkzTg=
 20251130000000_pgflow_auto_compilation.sql h1:qs+3qq1Vsyo0ETzbxDnmkVtSUa6XHkd/K9wF/3W46jM=
-20251209074533_pgflow_worker_management.sql h1:Yi+WZEgL+AcK0eAfKJD8v/uPBVBM8WcL+ZOL4ilkYz8=
+20251209074533_pgflow_worker_management.sql h1:ozFkYM1EvEH7dGvW+1pWgpzbwdWlwuQoddqLomL1GXw=

pkgs/core/supabase/tests/ensure_workers/debounce.test.sql

@@ -53,16 +53,16 @@ select is(
   'Function with NULL last_invoked_at IS returned'
 );
 
--- TEST: Debounce uses heartbeat_timeout_seconds from function config
+-- TEST: Debounce uses debounce interval from function config
 update pgflow.worker_functions
-set heartbeat_timeout_seconds = 3,
+set debounce = '3 seconds'::interval,
     last_invoked_at = now() - interval '4 seconds'
 where function_name = 'my-function';
 
 select is(
   (select count(*) from pgflow.ensure_workers()),
   1::bigint,
-  'Debounce respects function-specific heartbeat_timeout_seconds'
+  'Debounce respects function-specific debounce interval'
 );
 
 select finish();

pkgs/core/supabase/tests/track_worker_function/basic.test.sql

@@ -17,11 +17,11 @@ select is(
   'New worker function has enabled=true by default'
 );
 
--- TEST: New worker function has default heartbeat_timeout_seconds
+-- TEST: New worker function has default debounce interval
 select is(
-  (select heartbeat_timeout_seconds from pgflow.worker_functions where function_name = 'my-edge-function'),
-  6,
-  'New worker function has heartbeat_timeout_seconds=6 by default'
+  (select debounce from pgflow.worker_functions where function_name = 'my-edge-function'),
+  '6 seconds'::interval,
+  'New worker function has debounce=6 seconds by default'
 );
 
 -- TEST: Does NOT set last_invoked_at on insert (debounce handled by ensure_workers)