@render-lab/tasks-launchdarkly

⚠️ Experimental: proof of concept. This package is part of the Render Tasks POC and is published for testing only. It is not fully tested or production ready. Task names, inputs, outputs, and behavior can change or break in any release. Pin exact versions and expect breaking changes.

Durable LaunchDarkly flag, approval, and scheduled-change tasks for Render Workflows.

This is a vendor-first pack: it talks to the LaunchDarkly REST API v2 directly over fetch rather than through the official SDK. A vendor SDK retries, polls, and paginates internally, which would hide each attempt from Render Workflows. Direct HTTP keeps every read, convergent patch, poll, and retry as one observable durable run, with the baked-in retry policy as the single source of truth (vendor retries are off).

pnpm add @render-lab/tasks-launchdarkly

import {
  createFlag,
  getFlag,
  setFlagEnabled,
  setFlagRollout,
  addFlagTarget,
  removeFlagTarget,
  createApprovalRequest,
  getApprovalRequest,
  reviewApprovalRequest,
  awaitApproval,
  applyApprovalRequest,
  scheduleFlagChange,
} from "@render-lab/tasks-launchdarkly";

Tasks

| Task | Input | Output | Retry | | --- | --- | --- | --- | | launchdarkly.createFlag | CreateFlagInput | FeatureFlagDTO | none (0 retries) | | launchdarkly.getFlag | GetFlagInput | FeatureFlagDTO | general (3× backoff) | | launchdarkly.setFlagEnabled | SetFlagEnabledInput | FeatureFlagDTO | general (3× backoff) | | launchdarkly.setFlagRollout | SetFlagRolloutInput | FeatureFlagDTO | general (3× backoff) | | launchdarkly.addFlagTarget | AddFlagTargetInput | FeatureFlagDTO | general (3× backoff) | | launchdarkly.removeFlagTarget | RemoveFlagTargetInput | FeatureFlagDTO | general (3× backoff) | | launchdarkly.createApprovalRequest | CreateApprovalRequestInput | ApprovalRequestDTO | none (0 retries) | | launchdarkly.getApprovalRequest | GetApprovalRequestInput | ApprovalRequestDTO | general (3× backoff) | | launchdarkly.reviewApprovalRequest | ReviewApprovalRequestInput | ApprovalRequestDTO | none (0 retries) | | launchdarkly.awaitApproval | AwaitApprovalInput | AwaitApprovalResult | await (poll every 15s up to 24h) | | launchdarkly.applyApprovalRequest | ApplyApprovalRequestInput | ApplyApprovalRequestResult | none (0 retries) | | launchdarkly.scheduleFlagChange | ScheduleFlagChangeInput | ScheduledChangeDTO | none (0 retries) |

Retry and idempotency

The four flag mutation tasks (setFlagEnabled, setFlagRollout, addFlagTarget, removeFlagTarget) are convergent: the port reads current state, returns it unchanged when the desired state already holds, and otherwise sends exactly one version-aware semantic patch. A retry therefore converges rather than toggling a flag or duplicating a target, so these get the general transient retry.

createFlag, createApprovalRequest, reviewApprovalRequest, applyApprovalRequest, and scheduleFlagChange get zero retries. They have no find-or-create identity, so a retried attempt after an ambiguous timeout could open a duplicate request, append a duplicate review, or re-execute a change. Resume by reading state (getFlag, getApprovalRequest) instead.

awaitApproval is a durable wait. SDK 0.6.0 has no native sleep, so it polls by throwing: a pending review throws a progress error that the fixed-interval retry re-runs; a declined review and a failed execution status throw distinct terminal errors so a human sees them rather than a silent forever-retry; an approved review returns.

Flag instructions

createApprovalRequest and scheduleFlagChange carry a list of FlagInstructions — a documented discriminated union the client maps to LaunchDarkly semantic-patch instructions through an exhaustive switch:

| kind | Effect | | --- | --- | | turnFlagOn | Turn targeting on | | turnFlagOff | Turn targeting off | | updateFallthroughVariation | Set the fallthrough to a single variation (variationId) | | updateFallthroughRollout | Set an absolute weighted fallthrough rollout | | addIncludedTarget | Add context keys to a variation's individual targets | | removeIncludedTarget | Remove context keys from a variation's individual targets |

Rollout weights — for both setFlagRollout and the updateFallthroughRollout instruction — are expressed in hundred-thousandths and must be nonnegative integers totaling exactly 100,000 (that is, 50% is 50000).

Approvals and scheduled changes require a LaunchDarkly Enterprise plan. On lower plans those endpoints return an error, which the durable task surfaces on its (single) attempt.

Lifecycle example

Open an approval request, wait for a human to approve it, then apply it:

const request = await createApprovalRequest({
  projectKey: "default",
  flagKey: "release-x",
  environmentKey: "production",
  description: "Roll release X to 100%",
  instructions: [
    { kind: "turnFlagOn" },
    {
      kind: "updateFallthroughRollout",
      rollout: [
        { variationId: "v-true", weight: 100_000 },
        { variationId: "v-false", weight: 0 },
      ],
    },
  ],
});

// Durable wait: polls every 15s for up to 24h, resuming across restarts.
await awaitApproval({ approvalRequestId: request.id });

const applied = await applyApprovalRequest({ approvalRequestId: request.id });

Schedule a change for a future time instead of applying it now:

await scheduleFlagChange({
  projectKey: "default",
  flagKey: "release-x",
  environmentKey: "production",
  executionDate: "2026-07-14T09:00:00Z", // RFC 3339
  instructions: [{ kind: "turnFlagOn" }],
});

Payload limits

Every task returns bounded JSON well under the 4 MB Render Workflows payload limit. getFlag returns one flag's variations and per-environment on/version state (not full targeting rules or audit history), and the approval and scheduled-change DTOs carry status and metadata rather than unbounded histories.

Extending a task

Each task exports its raw *Impl, so you can wrap it, inject a fake port, or re-register it under your own namespaced name (never shadow launchdarkly.*):

import { task } from "@renderinc/sdk/workflows";
import { setFlagRolloutImpl, LAUNCHDARKLY_RETRY } from "@render-lab/tasks-launchdarkly";

export const setRolloutAudited = task(
  { name: "release.setRolloutAudited", retry: LAUNCHDARKLY_RETRY },
  async (input) => {
    const flag = await setFlagRolloutImpl(input);
    // ... record an audit entry ...
    return flag;
  },
);

Environment contract

Credentials are read lazily at first use, never at import (ADR-0007), so importing the pack for one task never requires another's secret.

| Variable | Required | Purpose | | --- | --- | --- | | LAUNCHDARKLY_ACCESS_TOKEN | Yes | Lazy REST API authentication with flag and approval permissions. | | LAUNCHDARKLY_WEBHOOK_SECRET | For the webhook adapter | HMAC secret configured when creating the signed LaunchDarkly webhook. |

Webhooks

The registration-free @render-lab/tasks-launchdarkly/webhooks subpath (ADR-0017) exposes a signed inbound adapter. It imports only node:crypto and the trigger webhook types — it never registers a task, constructs a client, or reads credentials at import time.

import { launchDarklyAdapter } from "@render-lab/tasks-launchdarkly/webhooks";

const adapter = launchDarklyAdapter({
  // secret defaults to LAUNCHDARKLY_WEBHOOK_SECRET, read only inside verify()
  onEvent: ({ payload }) => ({
    task: "release.handleLaunchDarklyEvent",
    args: [{ id: payload._id, kind: payload.kind, name: payload.name }],
  }),
});

verify checks LaunchDarkly's X-LD-Signature header: a hex HMAC-SHA256 of the exact raw body, compared in constant time (a lowercase or uppercase digest is accepted).

Replay limitation. LaunchDarkly does not include a signed timestamp, so the adapter authenticates and integrity-checks the payload but cannot independently reject a replayed valid payload. Terminate TLS in front of the receiver and dedupe on the event _id in the receiving workflow. This adapter is a true HMAC signature check — not a shared-secret header comparison.

Testing

pnpm -C packages/tasks-launchdarkly test        # Tier 1: hermetic unit tests (no secrets, no network)
pnpm -C packages/tasks-launchdarkly build
pnpm -C packages/tasks-launchdarkly typecheck
RUN_LIVE=1 pnpm -C packages/tasks-launchdarkly test:live   # Tier 2: hits the real LaunchDarkly API