fix(update): discover channels from verified release assets

Publish an immutable channel snapshot with each release and advance a fixed release pointer only after public assets pass verification. Check the exact platform package before notifying clients.

Co-authored-by: Codex <noreply@openai.com>

.github/scripts/published-channels.rb

@@ -1,11 +1,12 @@
 require 'base64'
+require 'digest'
 require 'uri'
 require_relative 'release-metadata'
 
-# 所有发行线只推进 main 中已公开可下载的候选，保留备版字段
+# 通道快照随版本封存，固定 Release 只记录已公开快照和可恢复的待发布摘要
 module PublishedChannels
-  PATH = 'release/version.yaml'
-  LIMIT = 8192
+  POINTER = 'update-index'
+  LIMIT = 128 * 1024
 
   def self.advance(document, version)
     version = ReleaseMetadata.version(version)
@@ -34,49 +35,136 @@ module PublishedChannels
     changed
   end
 
-  def self.api(endpoint, payload = nil)
-    args = ['gh', 'api', endpoint]
-    args.concat(%w[--method PUT --input -]) if payload
-    out, error, status = Open3.capture3(*args, stdin_data: payload ? JSON.generate(payload) : '')
-    return :conflict if payload && !status.success? && error.include?('(HTTP 409)')
-    raise "Cannot access #{endpoint}: #{error.strip}" unless status.success?
-    JSON.parse(out)
-  end
-
-  def self.verify_assets(base, version, request)
-    tag = "v#{version}"
-    release = request.call("#{base}/releases/tags/#{tag}")
-    raise "Release is not public or tag identity differs: #{tag}" unless release.fetch('tag_name') == tag &&
-      !release.fetch('draft') && release.fetch('prerelease') == ReleaseMetadata.prerelease?(version)
-    platforms = request.call("#{base}/contents/release/platforms.yaml?ref=#{URI.encode_www_form_component(tag)}")
-    expected = YAML.safe_load(Base64.decode64(platforms.fetch('content'))).fetch('platforms').map do |p|
-      ReleaseMetadata.archive_name(version, p)
+  class Publisher
+    def api(endpoint, method: 'GET', data: nil, optional: false)
+      args = ['gh', 'api', endpoint, '--method', method]
+      args.concat(%w[--input -]) if data
+      out, error, status = Open3.capture3(*args, stdin_data: data ? JSON.generate(data) : '')
+      return nil if optional && !status.success? && error.include?('(HTTP 404)')
+      raise "Cannot access #{endpoint}: #{error.strip}" unless status.success?
+      JSON.parse(out)
     end
-    assets = release.fetch('assets').select { |a| a.fetch('state') == 'uploaded' && a.fetch('size').positive? }.map { |a| a.fetch('name') }
-    missing = (expected + %w[checksums.txt compose.yaml config.example.yaml plugin-release-manifest.json]) - assets
-    raise "Incomplete release #{tag}: #{missing.join(', ')}" if expected.empty? || !missing.empty?
-  end
 
-  def self.publish(repository, version, &request)
-    request ||= method(:api)
-    version = ReleaseMetadata.version(version)
-    base = "repos/#{repository}"
-    verify_assets(base, version, request)
-    endpoint = "#{base}/contents/#{PATH}"
-    3.times do
-      file = request.call("#{endpoint}?ref=main")
-      document = YAML.safe_load(Base64.decode64(file.fetch('content')))
-      return unless advance(document, version)
-      content = YAML.dump(document)
+    def initialize(repository)
+      @repository = repository
+      @base = "repos/#{repository}"
+      release = api("#{@base}/releases/tags/#{POINTER}", optional: true)
+      if release
+        raise 'Invalid update-index release' unless release.fetch('tag_name') == POINTER &&
+          release.fetch('prerelease') && !release.fetch('draft')
+        @id = release.fetch('id')
+        @state = JSON.parse(release.fetch('body'))
+        @state.fetch('current')
+      else
+        @state = { 'current' => nil }
+      end
+    end
+
+    def save(current:, pending: nil)
+      state = { 'current' => current }
+      state['pending'] = pending if pending
+      body = { body: JSON.generate(state), make_latest: 'false' }
+      if @id
+        api("#{@base}/releases/#{@id}", method: 'PATCH', data: body)
+      else
+        release = api("#{@base}/releases", method: 'POST', data: body.merge(
+          tag_name: POINTER, name: '更新通道索引', target_commitish: 'main', prerelease: true
+        ))
+        @id = release.fetch('id')
+      end
+      @state = state
+    end
+
+    def release(version)
+      api("#{@base}/releases/tags/v#{ReleaseMetadata.version(version)}", optional: true)
+    end
+
+    def verify_assets(version, release, index:)
+      tag = "v#{version}"
+      raise "Release is not public or tag differs: #{tag}" unless release && release.fetch('tag_name') == tag &&
+        !release.fetch('draft') && release.fetch('prerelease') == ReleaseMetadata.prerelease?(version)
+      data = api("#{@base}/contents/release/platforms.yaml?ref=#{URI.encode_www_form_component(tag)}")
+      platforms = YAML.safe_load(Base64.decode64(data.fetch('content'))).fetch('platforms')
+      raise "Missing platforms for #{tag}" if platforms.empty?
+      expected = platforms.map { |p| ReleaseMetadata.archive_name(version, p) }
+      expected.concat(%w[checksums.txt compose.yaml config.example.yaml plugin-release-manifest.json])
+      expected << 'version.yaml' if index
+      assets = release.fetch('assets').select { |a| a.fetch('state') == 'uploaded' && a.fetch('size').positive? }.to_h { |a| [a.fetch('name'), a] }
+      missing = expected - assets.keys
+      raise "Incomplete release #{tag}: #{missing.join(', ')}" unless missing.empty?
+      assets
+    end
+
+    def download(version)
+      content, error, status = Open3.capture3('gh', 'release', 'download', "v#{version}", '--repo', @repository,
+        '--pattern', 'version.yaml', '--output', '-')
+      raise "Cannot download v#{version} snapshot: #{error.strip}" unless status.success?
+      content
+    end
+
+    def read_snapshot(version, asset)
+      raise 'Invalid version.yaml size' unless (1..LIMIT).cover?(asset.fetch('size'))
+      content = download(version)
+      digest = Digest::SHA256.hexdigest(content)
+      raise "Snapshot size or digest differs for v#{version}" unless content.bytesize == asset.fetch('size') && asset.fetch('digest') == "sha256:#{digest}"
+      doc = YAML.safe_load(content)
+      raise 'Invalid channel snapshot' unless doc.fetch('version') == version && doc.fetch('published').is_a?(Hash)
+      [doc, digest]
+    end
+
+    def previous
+      if (current = @state.fetch('current'))
+        assets = verify_assets(current, release(current), index: true)
+        return read_snapshot(current, assets.fetch('version.yaml')).first
+      end
+      # 首次接入时从实际公开的稳定版引导；没有历史 Release 的仓库从空表开始
+      doc = { 'published' => {} }
+      latest = api("#{@base}/releases/latest", optional: true)
+      if latest
+        version = ReleaseMetadata.version(latest.fetch('tag_name'))
+        verify_assets(version, latest, index: false)
+        PublishedChannels.advance(doc, version)
+      end
+      doc
+    end
+
+    # 调用方持有同一仓库的发布锁；快照必须在取锁后生成，不能在并行构建中预先合并
+    def prepare(version, directory)
+      if (pending = @state.dig('pending', 'version')) && (old = release(pending)) && !old.fetch('draft')
+        finish(pending)
+      end
+      existing = release(version)
+      raise "Release v#{version} already public; use index-only recovery" if existing && !existing.fetch('draft')
+      doc = previous
+      doc['version'] = version
+      PublishedChannels.advance(doc, version)
+      content = YAML.dump(doc)
       raise 'Published index exceeds the client size limit' if content.bytesize > LIMIT
-      written = request.call(endpoint, { branch: 'main', sha: file.fetch('sha'), content: Base64.strict_encode64(content),
-        message: "chore(release): publish channel index for v#{version}" })
-      return unless written == :conflict
+      digest = Digest::SHA256.hexdigest(content)
+      File.write(File.join(directory, 'version.yaml'), content)
+      File.open(File.join(directory, 'checksums.txt'), 'a') { |file| file.puts "#{digest}  version.yaml" }
+      save(current: @state.fetch('current'), pending: { 'version' => version, 'sha256' => digest })
+    end
+
+    def finish(version)
+      assets = verify_assets(version, release(version), index: true)
+      _, digest = read_snapshot(version, assets.fetch('version.yaml'))
+      return if @state.fetch('current') == version
+      unless @state['pending'] == { 'version' => version, 'sha256' => digest }
+        raise "v#{version} is not the reserved snapshot; refusing to overwrite another publication"
+      end
+      save(current: version)
     end
-    raise 'main changed during channel publication; rerun the index step'
   end
 end
 
 if $PROGRAM_NAME == __FILE__
-  PublishedChannels.publish(ENV.fetch('GITHUB_REPOSITORY'), ARGV.fetch(0))
+  mode, raw = ARGV
+  version = ReleaseMetadata.version(raw || '')
+  publisher = PublishedChannels::Publisher.new(ENV.fetch('GITHUB_REPOSITORY'))
+  case mode
+  when 'prepare' then publisher.prepare(version, 'dist/release')
+  when 'finish' then publisher.finish(version)
+  else abort 'usage: published-channels.rb prepare|finish VERSION'
+  end
 end

.github/scripts/tests/published-channels-test.rb

@@ -0,0 +1,115 @@
+require 'tmpdir'
+require_relative '../published-channels'
+
+# 测试只替换 GitHub 读写边界，执行真实的发布状态转换
+class PublishedChannelsTest
+  def assert_equal(expected, actual)
+    raise "expected #{expected.inspect}, got #{actual.inspect}" unless expected == actual
+  end
+
+  def assert_rejected
+    yield
+  rescue RuntimeError
+    return
+  else
+    raise 'expected publication to be rejected'
+  end
+
+  def initialize
+    @pointer = nil
+    @releases = {}
+    @files = {}
+    @calls = []
+    @platforms = [{ 'os' => 'linux', 'arch' => 'amd64', 'archive' => 'tar.gz' }]
+  end
+
+  def api(endpoint, method: 'GET', data: nil, optional: false)
+    path = endpoint.delete_prefix('repos/test/repo/')
+    @calls << [method, path]
+    case [method, path]
+    when ['GET', 'releases/tags/update-index'] then @pointer
+    when ['POST', 'releases']
+      raise 'duplicate pointer' if @pointer
+      @pointer = data.transform_keys(&:to_s).merge('id' => 12, 'draft' => false)
+    when ['PATCH', 'releases/12']
+      @pointer.merge!(data.transform_keys(&:to_s))
+    when ['GET', 'releases/latest'] then @releases['3.41.2']
+    else
+      return @releases[path.delete_prefix('releases/tags/v')] if method == 'GET' && path.start_with?('releases/tags/v')
+      return { 'content' => Base64.encode64(YAML.dump({ 'platforms' => @platforms })) } if path.start_with?('contents/release/platforms.yaml?ref=v')
+      raise "unexpected #{method} #{path}"
+    end
+  end
+
+  def publish_assets(version, content = nil)
+    names = %w[checksums.txt compose.yaml config.example.yaml plugin-release-manifest.json]
+    names << ReleaseMetadata.archive_name(version, @platforms.first)
+    @files[version] = content if content
+    assets = names.map { |name| { 'name' => name, 'size' => 100, 'state' => 'uploaded' } }
+    assets << { 'name' => 'version.yaml', 'size' => content.bytesize, 'digest' => "sha256:#{Digest::SHA256.hexdigest(content)}", 'state' => 'uploaded' } if content
+    @releases[version] = { 'tag_name' => "v#{version}", 'draft' => false, 'prerelease' => ReleaseMetadata.prerelease?(version), 'assets' => assets }
+  end
+
+  def publisher
+    github = self
+    files = @files
+    Class.new(PublishedChannels::Publisher) do
+      define_method(:api) { |endpoint, **args| github.api(endpoint, **args) }
+      define_method(:download) { |version| files.fetch(version) }
+    end.new('test/repo')
+  end
+
+  def prepare(version)
+    Dir.mktmpdir do |dir|
+      File.write(File.join(dir, 'checksums.txt'), '')
+      publisher.prepare(version, dir)
+      content = File.read(File.join(dir, 'version.yaml'))
+      assert_equal "#{Digest::SHA256.hexdigest(content)}  version.yaml\n", File.read(File.join(dir, 'checksums.txt'))
+      content
+    end
+  end
+
+  def current = JSON.parse(@pointer.fetch('body')).fetch('current')
+
+  def test_interrupted_publication_recovers_without_losing_another_channel
+    publish_assets('3.41.2')
+    stable = prepare('3.42.0')
+    assert_equal nil, current
+    assert_rejected { publisher.finish('3.42.0') }
+    publish_assets('3.42.0', stable)
+    # 模拟公开后更新指针中断，下一次发布在同一把锁内补写，再合并自己的通道
+    beta = prepare('3.43.0-beta.1')
+    assert_equal '3.42.0', current
+    assert_equal({ 'stable' => '3.42.0', 'rc' => '3.42.0', 'beta' => '3.43.0-beta.1', 'alpha' => '3.43.0-beta.1' },
+      YAML.safe_load(beta).dig('published', '3'))
+    publish_assets('3.43.0-beta.1', beta)
+    publisher.finish('3.43.0-beta.1')
+    publisher.finish('3.43.0-beta.1')
+    assert_rejected { publisher.finish('3.42.0') }
+    assert_equal '3.43.0-beta.1', current
+    experiment = YAML.safe_load(prepare('3.44.0-exp.1')).dig('published', '3')
+    assert_equal({ '3.44.0' => '3.44.0-exp.1' }, experiment.fetch('exp'))
+    assert_equal '3.43.0-beta.1', experiment.fetch('beta')
+    assert_equal false, @calls.include?(['GET', 'releases'])
+  end
+
+  def test_incomplete_corrupt_or_draft_release_keeps_last_public_snapshot
+    publish_assets('3.42.0', prepare('3.42.0'))
+    publisher.finish('3.42.0')
+    beta = prepare('3.43.0-beta.1')
+    publish_assets('3.43.0-beta.1', beta)
+    release = @releases.fetch('3.43.0-beta.1')
+    release['draft'] = true
+    assert_rejected { publisher.finish('3.43.0-beta.1') }
+    release['draft'] = false
+    missing = release.fetch('assets').shift
+    assert_rejected { publisher.finish('3.43.0-beta.1') }
+    release.fetch('assets') << missing
+    publish_assets('3.43.0-beta.1', beta.sub('3.42.0', '3.10.0'))
+    assert_rejected { publisher.finish('3.43.0-beta.1') }
+    assert_equal '3.42.0', current
+  end
+end
+PublishedChannelsTest.new.test_interrupted_publication_recovers_without_losing_another_channel
+PublishedChannelsTest.new.test_incomplete_corrupt_or_draft_release_keeps_last_public_snapshot
+puts 'Published channel recovery and integrity checks passed'

.github/workflows/_quality.yml

@@ -258,4 +258,5 @@ jobs:
           for script in .github/**/*.sh; do bash -n "$script"; done
           for script in .github/scripts/*.rb; do ruby -c "$script"; done
           ruby .github/scripts/toolchains.rb
+          ruby .github/scripts/tests/published-channels-test.rb
           ruby -c backend/crates/gateway-plugin/runtime/plugin-api-lifecycle.rb

.github/workflows/release.yml

@@ -7,6 +7,10 @@ on:
         description: 'Tag to release, for example v0.1.0'
         required: true
         type: string
+      index_only:
+        description: 'Recover the index for an already public release without rebuilding'
+        type: boolean
+        default: false
 
 permissions:
   contents: read
@@ -21,6 +25,7 @@ env:
 
 jobs:
   release-info:
+    if: ${{ !inputs.index_only }}
     runs-on: ubuntu-26.04
     timeout-minutes: 10
     permissions:
@@ -239,8 +244,6 @@ jobs:
     timeout-minutes: 20
     permissions:
       contents: read
-      id-token: write
-      attestations: write
 
     steps:
       - name: Checkout
@@ -274,11 +277,6 @@ jobs:
           PLATFORM_MATRIX: ${{ needs.release-info.outputs.platform_matrix }}
         run: ruby .github/scripts/package-release.rb archives
 
-      - name: Generate release asset provenance
-        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
-        with:
-          subject-path: dist/release/*
-
       - name: Upload release assets
         uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
@@ -540,6 +538,17 @@ jobs:
           File.write(output, "#{notes}\n\n#{installation}\n")
           RUBY
 
+      - name: Prepare versioned channel snapshot under the publication lock
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ needs.release-info.outputs.version }}
+        run: ruby .github/scripts/published-channels.rb prepare "$VERSION"
+
+      - name: Generate release asset provenance
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
+        with:
+          subject-path: dist/release/*
+
       - name: Upload GitHub Release assets
         id: release
         uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
@@ -564,8 +573,24 @@ jobs:
           RELEASE_ID: ${{ steps.release.outputs.id }}
         run: ruby .github/scripts/publish-release.rb
 
-      - name: Advance published channels on main
+      - name: Advance update-index to the verified snapshot
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           VERSION: ${{ needs.release-info.outputs.version }}
-        run: ruby .github/scripts/published-channels.rb "$VERSION"
+        run: ruby .github/scripts/published-channels.rb finish "$VERSION"
+
+  recover-index:
+    if: inputs.index_only
+    runs-on: ubuntu-26.04
+    concurrency:
+      group: release-publication
+      queue: max
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Verify public assets and finish pending publication
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ inputs.tag }}
+        run: ruby .github/scripts/published-channels.rb finish "$TAG"