[codex] Add random sticky rollouts

cli/README.md

@@ -242,13 +242,22 @@ Capgo never inspects external content. Add encryption for trustless security.
 npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel production
 ```
 
+Upload directly as a progressive rollout target while keeping the channel's stable bundle as fallback:
+
+```bash
+npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel production --rollout 10
+```
+
 **Options:**
 
 | Param          | Type          | Description          |
 | -------------- | ------------- | -------------------- |
 | **-a** | <code>string</code> | API key to link to your account |
 | **-p** | <code>string</code> | Path of the folder to upload, if not provided it will use the webDir set in capacitor.config |
 | **-c** | <code>string</code> | Channel to link to |
+| **--rollout** | <code>string</code> | Set the uploaded bundle as this channel's rollout target at a percentage from 0 to 100 |
+| **--rollout-percentage-bps** | <code>string</code> | Set the uploaded bundle rollout percentage in basis points from 0 to 10000 |
+| **--rollout-cache-ttl-seconds** | <code>string</code> | Cloudflare rollout decision cache TTL in seconds |
 | **-e** | <code>string</code> | Link to external URL instead of upload to Capgo Cloud |
 | **--iv-session-key** | <code>string</code> | Set the IV and session key for bundle URL external |
 | **--s3-region** | <code>string</code> | Region for your S3 bucket |

cli/skills/release-management/SKILL.md

@@ -19,6 +19,7 @@ Use this skill for OTA update workflows in Capgo Cloud.
 
 - Alias: `u`
 - Example: `npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel production`
+- Progressive rollout example: `npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel production --rollout 10`
 - Key behavior:
   - Bundle version must be greater than `0.0.0` and unique.
   - Deleted versions cannot be reused.
@@ -29,6 +30,9 @@ Use this skill for OTA update workflows in Capgo Cloud.
 - Important options:
   - `-p, --path <path>`
   - `-c, --channel <channel>`
+  - `--rollout <percentage>`
+  - `--rollout-percentage-bps <basisPoints>`
+  - `--rollout-cache-ttl-seconds <seconds>`
   - `-e, --external <url>`
   - `--iv-session-key <key>`
   - `-b, --bundle <bundle>`

cli/src/api/channels.ts

@@ -22,7 +22,7 @@ export async function checkVersionNotUsedInChannel(
     .from('channels')
     .select()
     .eq('app_id', appid)
-    .eq('version', versionData.id)
+    .or(`version.eq.${versionData.id},rollout_version.eq.${versionData.id}`)
 
   if (channelName)
     query = query.eq('name', channelName)
@@ -66,14 +66,26 @@ export async function checkVersionNotUsedInChannel(
     const s = silent ? null : spinner()
     s?.start(`Unlinking channel ${channel.name}`)
 
-    const unknownVersion = await findUnknownVersion(supabase, appid, { silent })
-    if (!unknownVersion) {
-      s?.stop(`Cannot find unknown version for ${appid}`)
-      throw new Error(`Cannot find unknown version for ${appid}`)
+    const patch: Database['public']['Tables']['channels']['Update'] = {}
+    if (channel.version === versionData.id) {
+      const unknownVersion = await findUnknownVersion(supabase, appid, { silent })
+      if (!unknownVersion) {
+        s?.stop(`Cannot find unknown version for ${appid}`)
+        throw new Error(`Cannot find unknown version for ${appid}`)
+      }
+      patch.version = unknownVersion.id
     }
+    if (channel.rollout_version === versionData.id) {
+      patch.rollout_version = null
+      patch.rollout_enabled = false
+      patch.rollout_percentage_bps = 0
+      patch.rollout_paused_at = null
+      patch.rollout_pause_reason = null
+    }
+
     const { error: errorChannelUpdate } = await supabase
       .from('channels')
-      .update({ version: unknownVersion.id })
+      .update(patch)
       .eq('id', channel.id)
 
     if (errorChannelUpdate) {
@@ -190,7 +202,7 @@ export function findBundleIdByChannelName(supabase: SupabaseClient<Database>, ap
     .from('channels')
     .select(`
       id,
-      version (id, name)
+      version:app_versions!channels_version_fkey(id, name)
     `)
     .eq('app_id', appId)
     .eq('name', name)
@@ -255,7 +267,7 @@ export async function getActiveChannels(
       created_at,
       created_by,
       app_id,
-      version (id, name)
+      version:app_versions!channels_version_fkey(id, name)
     `)
     .eq('app_id', appid)
     .order('created_at', { ascending: false })

cli/src/bundle/upload.ts

@@ -137,7 +137,7 @@ async function verifyCompatibility(supabase: SupabaseType, pm: pmType, options:
 
   const { data: channelData, error: channelError } = await supabase
     .from('channels')
-    .select('disable_auto_update, version ( min_update_version, native_packages )')
+    .select('disable_auto_update, version:app_versions!channels_version_fkey( min_update_version, native_packages )')
     .eq('name', channel)
     .eq('app_id', appid)
     .maybeSingle()
@@ -612,11 +612,36 @@ type LinkedChannelVersion = {
   name: string
 } | null
 
+function getUploadRolloutPercentageBps(options: OptionsUpload) {
+  if (options.rollout == null && options.rolloutPercentageBps == null)
+    return undefined
+
+  if (options.rolloutPercentageBps != null)
+    return options.rolloutPercentageBps
+
+  return Math.round((options.rollout ?? 0) * 100)
+}
+
+function formatRolloutPercentage(bps: number) {
+  return `${Number((bps / 100).toFixed(2))}%`
+}
+
+async function getVersionIdForChannelUpdate(supabase: SupabaseType, apikey: string, appid: string, bundle: string) {
+  const { data: versionId } = await supabase
+    .rpc('get_app_versions', { apikey, name_version: bundle, appid })
+    .single()
+
+  if (!versionId)
+    uploadFail('Cannot get version id, cannot set channel')
+
+  return versionId
+}
+
 // It is really important that this function never terminates the program, it should always return.
 async function getLinkedBundleOnChannel(supabase: SupabaseType, appid: string, channel: string): Promise<LinkedChannelVersion> {
   const { data, error } = await supabase
     .from('channels')
-    .select('version ( id, name, deleted )')
+    .select('version:app_versions!channels_version_fkey( id, name, deleted )')
     .eq('app_id', appid)
     .eq('name', channel)
 
@@ -673,12 +698,7 @@ async function setVersionInChannel(
   localConfig: localConfigType,
   selfAssign?: boolean,
 ) {
-  const { data: versionId } = await supabase
-    .rpc('get_app_versions', { apikey, name_version: bundle, appid })
-    .single()
-
-  if (!versionId)
-    uploadFail('Cannot get version id, cannot set channel')
+  const versionId = await getVersionIdForChannelUpdate(supabase, apikey, appid, bundle)
 
   const apiAccess = await hasCliPermission(supabase, apikey, 'app.create_channel', { appId: appid })
 
@@ -707,6 +727,72 @@ async function setVersionInChannel(
   }
 }
 
+async function setRolloutVersionInChannel(
+  supabase: SupabaseType,
+  apikey: string,
+  displayBundleUrl: boolean,
+  bundle: string,
+  channel: string,
+  appid: string,
+  localConfig: localConfigType,
+  rolloutPercentageBps: number,
+  rolloutCacheTtlSeconds?: number,
+  selfAssign?: boolean,
+) {
+  const versionId = await getVersionIdForChannelUpdate(supabase, apikey, appid, bundle)
+
+  const { data: apiAccess } = await supabase
+    .rpc('is_allowed_capgkey', { apikey, keymode: ['write', 'all'] })
+    .single()
+
+  if (!apiAccess) {
+    log.warn('The upload key is not allowed to set the rollout in the channel')
+    return
+  }
+
+  const { data: existingChannel, error: channelError } = await supabase
+    .from('channels')
+    .select('id, version')
+    .eq('app_id', appid)
+    .eq('name', channel)
+    .single()
+
+  if (channelError || !existingChannel) {
+    uploadFail(`Cannot set rollout, channel ${channel} must already exist with a stable bundle`)
+  }
+  if (!existingChannel.version) {
+    uploadFail(`Cannot set rollout, channel ${channel} needs a stable bundle before using progressive rollout`)
+  }
+
+  const channelPayload: Database['public']['Tables']['channels']['Update'] = {
+    rollout_version: versionId,
+    rollout_percentage_bps: rolloutPercentageBps,
+    rollout_enabled: true,
+    rollout_paused_at: null,
+    rollout_pause_reason: null,
+    ...(selfAssign ? { allow_device_self_set: true } : {}),
+  }
+  if (rolloutCacheTtlSeconds != null)
+    channelPayload.rollout_cache_ttl_seconds = rolloutCacheTtlSeconds
+
+  const { error: rolloutError, data } = await supabase
+    .from('channels')
+    .update(channelPayload)
+    .eq('app_id', appid)
+    .eq('name', channel)
+    .select('id')
+    .single()
+
+  if (rolloutError)
+    uploadFail(`Cannot set rollout in channel ${formatError(rolloutError)}`)
+
+  const bundleUrl = `${localConfig.hostWeb}/app/${appid}/channel/${data.id}`
+  log.info(`Set ${appid} channel ${channel} rollout target to @${bundle} (${formatRolloutPercentage(rolloutPercentageBps)})`)
+
+  if (displayBundleUrl)
+    log.info(`Bundle url: ${bundleUrl}`)
+}
+
 export async function getDefaultUploadChannel(appId: string, supabase: SupabaseType, hostWeb: string) {
   const { error, data } = await supabase.from('apps')
     .select('default_upload_channel')
@@ -835,6 +921,7 @@ export async function uploadBundleInternal(preAppid: string, options: OptionsUpl
 
   const defaultUploadChannel = options.channel ? null : await getDefaultUploadChannel(appid, supabase, localConfig.hostWeb)
   const channel = options.channel || defaultUploadChannel || 'production'
+  const rolloutPercentageBps = getUploadRolloutPercentageBps(options)
   if (options.verbose)
     log.info(`[Verbose] Target channel: ${channel}`)
 
@@ -1237,9 +1324,16 @@ export async function uploadBundleInternal(preAppid: string, options: OptionsUpl
   }
 
   if (hasOrganizationPerm(permissions, OrganizationPerm.write)) {
-    if (options.verbose)
-      log.info(`[Verbose] Setting bundle ${bundle} to channel ${channel}...`)
-    await setVersionInChannel(supabase, apikey, !!options.bundleUrl, bundle, channel, userId, orgId, appid, localConfig, options.selfAssign)
+    if (rolloutPercentageBps != null) {
+      if (options.verbose)
+        log.info(`[Verbose] Setting bundle ${bundle} as rollout target for channel ${channel}...`)
+      await setRolloutVersionInChannel(supabase, apikey, !!options.bundleUrl, bundle, channel, appid, localConfig, rolloutPercentageBps, options.rolloutCacheTtlSeconds, options.selfAssign)
+    }
+    else {
+      if (options.verbose)
+        log.info(`[Verbose] Setting bundle ${bundle} to channel ${channel}...`)
+      await setVersionInChannel(supabase, apikey, !!options.bundleUrl, bundle, channel, userId, orgId, appid, localConfig, options.selfAssign)
+    }
     if (options.verbose)
       log.info(`[Verbose] Channel updated successfully`)
 
@@ -1329,6 +1423,7 @@ function checkValidOptions(options: OptionsUpload) {
   const noKey = options.key === false
   const forceCrc32 = options.forceCrc32Checksum === true
   const hasEncryptionKey = (options.keyV2 || options.keyDataV2 || existsSync(baseKeyV2))
+  const hasUploadRollout = options.rollout != null || options.rolloutPercentageBps != null
 
   if (options.ivSessionKey && !options.external) {
     uploadFail('You need to provide an external url if you want to use the --iv-session-key option')
@@ -1371,6 +1466,21 @@ function checkValidOptions(options: OptionsUpload) {
   if (forceCrc32 && hasEncryptionKey && !noKey) {
     uploadFail('You cannot use --force-crc32-checksum when encryption is enabled. Remove the flag or disable encryption.')
   }
+  if (options.rollout != null && (!Number.isFinite(options.rollout) || options.rollout < 0 || options.rollout > 100)) {
+    uploadFail('Rollout percentage must be between 0 and 100')
+  }
+  if (options.rolloutPercentageBps != null && (!Number.isInteger(options.rolloutPercentageBps) || options.rolloutPercentageBps < 0 || options.rolloutPercentageBps > 10000)) {
+    uploadFail('Rollout percentage basis points must be between 0 and 10000')
+  }
+  if (options.rolloutCacheTtlSeconds != null && (!Number.isInteger(options.rolloutCacheTtlSeconds) || options.rolloutCacheTtlSeconds < 60 || options.rolloutCacheTtlSeconds > 31536000)) {
+    uploadFail('Rollout cache TTL seconds must be between 60 and 31536000')
+  }
+  if (hasUploadRollout && options.dryUpload) {
+    uploadFail('You cannot use --rollout with --dry-upload because dry upload does not update channels')
+  }
+  if (hasUploadRollout && options.deleteLinkedBundleOnUpload) {
+    uploadFail('You cannot use --rollout with --delete-linked-bundle-on-upload because rollout needs the stable channel bundle as fallback')
+  }
 }
 
 async function maybePromptStarCapgoRepo() {

cli/src/channel/currentBundle.ts

@@ -51,7 +51,7 @@ export async function currentBundleInternal(channel: string, appId: string, opti
 
   const { data: supabaseChannel, error } = await supabase
     .from('channels')
-    .select('version ( name )')
+    .select('version:app_versions!channels_version_fkey( name )')
     .eq('name', channel)
     .eq('app_id', appId)
     .limit(1)