Merge pull request #972 from flippercloud/cloud-migrate-api-cli-ui

Auto Cloud Migration

Author: jnunemaker

CLAUDE.md

@@ -69,6 +69,14 @@ The project is structured as multiple gems:
 **Memoization**: Automatic caching of feature checks within request/thread scope
 **Type Safety**: Strong typing system for actors, percentages, and other values
 
+### Serialization and HTTP
+
+Use `Flipper::Typecast` for JSON and gzip serialization instead of calling `JSON.generate`/`JSON.parse` or `Zlib` directly:
+- `Typecast.to_json(hash)` / `Typecast.from_json(string)` for JSON serialization
+- `Typecast.to_gzip(string)` / `Typecast.from_gzip(string)` for gzip compression
+
+For outbound HTTP requests, use `Flipper::Adapters::Http::Client` instead of raw `Net::HTTP`. It provides timeouts, retries (`max_retries`), SSL verification, and diagnostic headers (user-agent, client-language, client-platform, etc.). See `lib/flipper/cloud/migrate.rb` for an example.
+
 ### Testing
 
 Uses both RSpec (currently preferred for new tests) and Minitest. Shared adapter specs ensure consistency across all storage backends. Extensive testing across multiple Rails versions (5.0-8.0).

lib/flipper/cli.rb

@@ -84,6 +84,57 @@ def initialize(stdout: $stdout, stderr: $stderr, shell: Bundler::Thor::Base.shel
         end
       end
 
+      command 'export' do |c|
+        c.description = "Export features as JSON"
+        c.action do
+          export = Flipper.export(format: :json, version: 1)
+          ui.info export.contents
+        end
+      end
+
+      command 'cloud' do |c|
+        c.description = "Flipper Cloud commands"
+        c.action do |subcommand = nil, *args|
+          require 'flipper/cloud/migrate'
+
+          case subcommand
+          when 'migrate'
+            result = Flipper::Cloud.migrate(Flipper)
+            if result.url
+              ui.info "Migrating to Flipper Cloud..."
+              ui.info result.url
+              system("open", result.url)
+            else
+              message = "Migration failed (HTTP #{result.code})"
+              message << ": #{result.message}" if result.message
+              ui.error message
+              exit 1
+            end
+          when 'push'
+            token = args.first
+            unless token
+              ui.error "Usage: flipper cloud push <token>"
+              exit 1
+            end
+            result = Flipper::Cloud.push(token, Flipper)
+            if result.code == 204
+              ui.info "Successfully pushed features to Flipper Cloud"
+            else
+              message = "Push failed (HTTP #{result.code})"
+              message << ": #{result.message}" if result.message
+              ui.error message
+              exit 1
+            end
+          else
+            ui.info "Usage: flipper cloud <command>"
+            ui.info ""
+            ui.info "Commands:"
+            ui.info "  migrate  Migrate features to a new Flipper Cloud account"
+            ui.info "  push     Push features to an existing Flipper Cloud project"
+          end
+        end
+      end
+
       command 'help' do |c|
         c.load_environment = false
         c.action do |command = nil|

lib/flipper/cloud.rb

@@ -4,6 +4,7 @@
 require "flipper/cloud/configuration"
 require "flipper/cloud/dsl"
 require "flipper/cloud/middleware"
+require "flipper/cloud/migrate"
 
 module Flipper
   module Cloud

lib/flipper/cloud/migrate.rb

@@ -0,0 +1,71 @@
+require "flipper/adapters/http/client"
+require "flipper/typecast"
+
+module Flipper
+  module Cloud
+    MigrateResult = Struct.new(:code, :url, :message, keyword_init: true)
+
+    DEFAULT_CLOUD_URL = "https://www.flippercloud.io".freeze
+
+    # Public: Migrate features to Flipper Cloud.
+    #
+    # flipper  - The Flipper instance to export features from (default: Flipper).
+    # app_name - Optional String name of the application.
+    #
+    # Returns a MigrateResult with code, url, and message.
+    def self.migrate(flipper = Flipper, app_name: nil)
+      export = flipper.export(format: :json, version: 1)
+      payload = {
+        export: Typecast.from_json(export.contents),
+        metadata: {app_name: app_name},
+      }
+
+      client = build_client("/api")
+      response = client.post("/migrate", Typecast.to_gzip(Typecast.to_json(payload)))
+      body = Typecast.from_json(response.body) rescue nil
+
+      MigrateResult.new(
+        code: response.code.to_i,
+        url: body&.dig("url"),
+        message: body&.dig("error"),
+      )
+    end
+
+    # Public: Push features to an existing Flipper Cloud project.
+    #
+    # token   - The String token for the Cloud environment.
+    # flipper - The Flipper instance to export features from (default: Flipper).
+    #
+    # Returns a MigrateResult with code and message.
+    def self.push(token, flipper = Flipper)
+      export = flipper.export(format: :json, version: 1)
+
+      client = build_client("/adapter", headers: {
+        "flipper-cloud-token" => token,
+      })
+      response = client.post("/import", Typecast.to_gzip(export.contents))
+      body = Typecast.from_json(response.body) rescue nil
+
+      MigrateResult.new(
+        code: response.code.to_i,
+        url: nil,
+        message: body&.dig("error"),
+      )
+    end
+
+    # Private: Build an HTTP client for Cloud API requests.
+    def self.build_client(path, headers: {})
+      base_url = ENV.fetch("FLIPPER_CLOUD_URL", DEFAULT_CLOUD_URL)
+
+      Flipper::Adapters::Http::Client.new(
+        url: "#{base_url}#{path}",
+        headers: {"content-encoding" => "gzip"}.merge(headers),
+        open_timeout: 5,
+        read_timeout: 30,
+        write_timeout: 30,
+        max_retries: 2,
+      )
+    end
+    private_class_method :build_client
+  end
+end

lib/flipper/ui/actions/cloud_migrate.rb

@@ -0,0 +1,26 @@
+require 'flipper/ui/action'
+require 'flipper/ui/util'
+
+module Flipper
+  module UI
+    module Actions
+      class CloudMigrate < UI::Action
+        route %r{\A/settings\/cloud/?\Z}
+
+        def post
+          result = Flipper::Cloud.migrate(flipper)
+
+          if result.url
+            status 302
+            header 'location', result.url
+            halt [@code, @headers, ['']]
+          else
+            message = "Migration failed (HTTP #{result.code})"
+            message << ": #{result.message}" if result.message
+            redirect_to "/settings?error=#{Flipper::UI::Util.escape(message)}"
+          end
+        end
+      end
+    end
+  end
+end

lib/flipper/ui/middleware.rb

@@ -27,6 +27,7 @@ def initialize(app, options = {})
         @action_collection.add UI::Actions::Features
         @action_collection.add UI::Actions::Export
         @action_collection.add UI::Actions::Import
+        @action_collection.add UI::Actions::CloudMigrate
         @action_collection.add UI::Actions::Settings
 
         # Static Assets/Files

lib/flipper/ui/views/settings.erb

@@ -1,3 +1,30 @@
+<% if params.key?("error") %>
+  <div class="alert alert-danger"><%= params["error"] %></div>
+<% end %>
+
+<div class="card mb-4">
+  <div class="card-header">
+    <h4 class="m-0">Migrate to Flipper Cloud</h4>
+  </div>
+  <div class="card-body">
+    <p>Flipper Cloud gives you audit history, rollback, finer-grained permissions, and multi-environment sync. We even have a free tier!</p>
+
+    <ul class="mb-3">
+      <li>Audit log of every feature change</li>
+      <li>Instant rollback to any previous state</li>
+      <li>Team permissions and approval workflows</li>
+      <li>Sync flags across environments</li>
+    </ul>
+
+    <p>You have <strong><%= flipper.features.count %></strong> <%= flipper.features.count == 1 ? 'feature' : 'features' %> ready to migrate.</p>
+
+    <form action="<%= script_name %>/settings/cloud" method="post">
+      <%== csrf_input_tag %>
+      <input type="submit" value="Migrate to Flipper Cloud" class="btn btn-primary">
+    </form>
+  </div>
+</div>
+
 <div class="card mb-4 ">
   <div class="card-header">
     <h4 class="m-0">Export</h4>

spec/flipper/cli_spec.rb

@@ -147,6 +147,57 @@
     it { should have_attributes(status: 1, stderr: /invalid option: --nope/) }
   end
 
+  describe "export" do
+    before do
+      Flipper.enable :search
+      Flipper.disable :analytics
+    end
+
+    it "outputs valid JSON export" do
+      expect(subject).to have_attributes(status: 0)
+      data = JSON.parse(subject.stdout)
+      expect(data["version"]).to eq(1)
+      expect(data["features"]).to have_key("search")
+      expect(data["features"]).to have_key("analytics")
+    end
+  end
+
+  describe "cloud" do
+    it "shows help when no subcommand given" do
+      expect(subject).to have_attributes(status: 0, stdout: /migrate/)
+      expect(subject.stdout).to match(/push/)
+    end
+  end
+
+  describe "cloud migrate" do
+    before do
+      Flipper.enable :search
+      require 'flipper/cloud/migrate'
+      allow(Flipper::Cloud).to receive(:migrate).and_return(
+        Flipper::Cloud::MigrateResult.new(code: 200, url: "https://www.flippercloud.io/cloud/setup/abc123")
+      )
+      allow(cli).to receive(:system)
+    end
+
+    it "prints the cloud URL" do
+      expect(subject).to have_attributes(status: 0, stdout: /flippercloud\.io/)
+    end
+  end
+
+  describe "cloud push test-token" do
+    before do
+      Flipper.enable :search
+      require 'flipper/cloud/migrate'
+      allow(Flipper::Cloud).to receive(:push).and_return(
+        Flipper::Cloud::MigrateResult.new(code: 204, url: nil)
+      )
+    end
+
+    it "prints success message" do
+      expect(subject).to have_attributes(status: 0, stdout: /Successfully pushed/)
+    end
+  end
+
   describe "show foo" do
     context "boolean" do
       before { Flipper.enable :foo }