superset 0.3.5 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b991d014f7094976acde768b112309443a38f741c2b4d2834ecc9575366ad1eb
-  data.tar.gz: 5701ba1956f94f51037b78f878cb6bb154c74509d4c86d9b0e2b71c83abc1af8
+  metadata.gz: 6ec3571934b0c40b84d75e2bfc55fb010fbae561539d65b2a20f6131cfcef323
+  data.tar.gz: 9e68d4aa5a36aba31b4b548eb9a7bf131e45c3c168090782207ea9e1238228de
 SHA512:
-  metadata.gz: aaa349b9a890fea6b8a45323d80aca1ed9b57d0a71a39defed7430b72ce2ab92a37671b8f91d745c178d55d3e28d2e14b35fbad01c22c38db517ea13cafa94e9
-  data.tar.gz: 305171e61d4c0ecb3d5cd9b4c7e828f57aa3002e2b089996356c41264046095677c012ed6a147e4baad51aa74110e0189002f7967984b12f6fff22b361e40527
+  metadata.gz: 9ac4a4a54a6d41d7094c3e0e4220b1af461066d433a8ddb3199644b243b16e9db177d290dfd48b54beea967f930c5eb677d81ca99b68add155bc688e1e6aa062
+  data.tar.gz: d169a9b5b1f85cec5f07e25a54619530923ad1e12ad97f7b5c4f5a73abf5c751f8c83392595f0d0806648c83f59617948523e208ee19dd8307b9105c9375b7c9

data/AGENTS.md

@@ -0,0 +1,105 @@
+# Agents
+
+This file provides guidance to AI coding agents working with code in this repository.
+
+## Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Open interactive console (auto-loads .env)
+bin/console
+
+# Run full test suite
+rspec
+
+# Run a single test file
+rspec spec/path/to/test_spec.rb
+
+# Run a single test by line number
+rspec spec/path/to/test_spec.rb:42
+
+# Lint
+rubocop
+
+# Run specs + rubocop together
+rake
+```
+
+Docker equivalents: prefix commands with `docker-compose run --rm app`.
+
+### Environment Setup
+
+Copy `env.sample` to `.env` and fill in:
+- `SUPERSET_HOST` — API base URL (required)
+- `SUPERSET_API_USERNAME` / `SUPERSET_API_PASSWORD` — API credentials (required)
+- `SUPERSET_ENVIRONMENT` — optional; loads `.env-{ENVIRONMENT}` instead
+- `CONSOLE_TIMEOUT` — seconds before auto-logout in console (default 1800)
+
+## Architecture
+
+### Request Framework
+
+All API interactions inherit from `Superset::Request` (`lib/superset/request.rb`). Subclasses implement:
+- `route` — returns the API path (e.g., `"dashboard/#{id}"`)
+- `filters` — returns a filter query string or `""`
+- `list_attributes` — array of field names used for terminal table display
+
+**Patterns by HTTP verb:**
+- **GET/LIST** — inherit `Superset::Request`, implement `route` and `filters`
+- **PUT** — inherit `Superset::BasePutRequest`, takes `target_id:` and `params:`, implement `route`
+- **DELETE/POST** — call `client.delete(route)` or `client.post(route, params)` directly
+
+Pagination is built into `Superset::Request` (default page size: 100, max: 1000). List classes accept `page_num:` and `page_size:` kwargs.
+
+### Authentication Flow
+
+1. `Superset::Client` (extends `Happi::Client`) includes `Credential::ApiUser` and creates a `Superset::Authenticator`
+2. `Authenticator` POSTs to `api/v1/security/login` and extracts `access_token`
+3. `Client#connection` builds a Faraday connection with Bearer token; supports both JSON and multipart modes (`config.use_json`)
+
+### Query Filter Syntax
+
+Superset uses an ORM-like filter string format:
+```
+filters:!((col:column_name,opr:operation,value:value)),
+```
+Common operations: `ct` (contains), `eq` (equals), `neq` (not equals), `rel_o_m`, `rel_m_m`, `dashboard_tags`.
+
+### Service Layer
+
+`lib/superset/services/` contains complex multi-step workflows. The main one is `DuplicateDashboard`, which:
+1. Validates source/target IDs, schema existence, and data sovereignty rules (all chart datasets must share the same DB schema)
+2. Copies the dashboard and its charts
+3. Duplicates datasets pointing to the target schema
+4. Rewires chart JSON metadata and filter configs to the new dataset IDs
+5. Optionally sets embedded config, tags, and publishes
+6. **Rolls back all created objects on failure**
+
+`ImportDashboardAcrossEnvironment` handles cross-environment migration via export/import ZIP files.
+
+### Display Mixin
+
+`Superset::Display` (`lib/superset/display.rb`) is included in `Superset::Request` and provides `list`, `rows`, `to_h`, and `ids`. Requires `list_attributes` and `result` to be implemented by the subclass.
+
+### Resource–Relationship Model
+
+- **Dashboards** contain **Charts**
+- **Charts** reference **Datasets** (datasources)
+- **Dashboard JSON metadata** stores layout, chart positions, and filter configurations
+- **Filters** reference Datasets for filter values
+- Duplication/migration requires updating all these cross-references
+
+### Conventions
+
+- Namespace: `Superset::<ResourceType>::<Action>` (e.g., `Superset::Dashboard::List`)
+- `perform` — executes a state-changing action, returns `self`
+- `response` — raw (cached) HTTP response
+- `result` — extracts `response['result']`
+- Constructor filter params follow naming: `title_contains:`, `title_equals:`, etc.
+- Logging goes to `log/superset-client.log` via `Superset::Logger`
+
+### Console Helpers
+
+In `bin/console`: `sshelp` (alias: `superset_class_list`) lists all available `Superset::` classes. On startup, `Superset::Database::List.call` prints available DB connections.

data/CHANGELOG.md

@@ -1,4 +1,28 @@
-## Change Log
+## Changelog
+
+## 0.4.0 - 2026-06-05
+
+* send X-CSRFToken (and replay the session cookie) on state-changing requests so writes work against a CSRF-protected Superset
+* send a same-origin Referer on state-changing requests to satisfy Flask-WTF WTF_CSRF_SSL_STRICT over HTTPS
+* GuestToken: send X-CSRFToken + Referer (and replay the session cookie) on the guest_token POST — that endpoint is CSRF-protected too, so embedded dashboards broke without it
+* add faraday-cookie_jar dependency
+
+## 0.3.6 - 2026-02-26
+
+* add dry_run to dashboard bulk delete cascade #74
+* update to rubyzip 3.2.2 #73
+
+## 0.3.5 - 2026-02-24
+
+* allow for empty filter datasets #72
+
+## 0.3.4 - 2026-02-21
+
+* cascade ownership should also update datasets for filter only in #68
+* add owner filter #62
+* list dataset catalog db names #69
+* bump version to 0.3.4 #70
+* Adjust asset order for board cascade deletion #71
 
 ## 0.3.3 - 2025-12-11
 * Add databases method to Superset::Dashboard::Datasets::List

data/CLAUDE.md

@@ -0,0 +1 @@
+See [AGENTS.md](AGENTS.md) for project context and development instructions.

data/doc/setting_up_personal_api_credentials.md

@@ -4,6 +4,8 @@ Superset API Credentials are essentially the username, password and host of the
 
 If you know these already, plug them and your host value into the `.env` and it should all just work.  A sample env.sample is provided as a template.
 
+Note: `.env` files are for local development only—do not store production credentials in a `.env` file (or commit it to git). In production, inject secrets at runtime via your platform's environment variables or a secret manager.
+
 Create your own .env file with
 
 ```
@@ -59,9 +61,17 @@ Scroll down to the 'Security Users' area and find the PUT request that will upda
 
 PUT `/api/v1/security/users/{pk}`
 
-Click 'Try it Out' and add your users ID in the PK input box.  
+Click 'Try it Out' and add your users ID in the PK input box.
+
+Generate a secure random password with your preferred tool ... or in ruby with something like:
+```ruby
+# ruby SecureRandom code to provide 32 random bytes
+require 'securerandom'
+SecureRandom.urlsafe_base64(32)
+```
+
+Edit the params to only consist of only the password field and the value of your new password.
 
-Edit the params to only consist of only the password field and the value of your new password.  
 
 ```
 {
@@ -159,5 +169,15 @@ Superset::GuestToken.new(embedded_dashboard_id: '15').guest_token
 => "eyJ0eXAiOi............VV4mrMfsvg"
 ```
 
+## Troubleshooting tips
 
+### Password or token expired
+
+If your Superset password has expired (or your auth token is no longer valid), API calls may fail with an error like:
+
+```ruby
+Superset::Dashboard::List.call
+ArgumentError: Can't build an Authorization Bearer header from nil
+```
 
+Fix: refresh your credentials via swagger interface then update your credentials in .env and try again.

data/lib/superset/client.rb

@@ -1,7 +1,14 @@
+require 'faraday-cookie_jar'
+
 module Superset
   class Client < Happi::Client
     include Credential::ApiUser
 
+    # Superset enforces CSRF on state-changing requests once WTF_CSRF_ENABLED is on;
+    # GETs are never CSRF-checked. Bearer-token auth is not sufficient,
+    # so these verbs must carry an X-CSRFToken header (see #call / #csrf_token).
+    CSRF_PROTECTED_METHODS = %i[post put patch delete].freeze
+
     attr_reader :authenticator
 
     def initialize
@@ -17,6 +24,15 @@ module Superset
       @superset_host ||= authenticator.superset_host
     end
 
+    # All verbs funnel through Happi::Client#call. Before any state-changing request,
+    # attach a CSRF token; fetching one also sets the Flask session cookie that the
+    # token is validated against, which the cookie jar on this connection replays on
+    # the write.
+    def call(method, url, params = {})
+      set_csrf_token if CSRF_PROTECTED_METHODS.include?(method)
+      super
+    end
+
     # TODO: Happi has not got a put method yet
     def put(resource, params = {})
       call(:put, url(resource), param_check(params))
@@ -40,9 +56,27 @@ module Superset
 
     private
 
+    # Set the CSRF headers for the upcoming write:
+    #   * X-CSRFToken — session-bound token; GET /api/v1/security/csrf_token/ returns it
+    #     and sets the Flask session cookie it is validated against (the cookie jar on
+    #     this connection replays that cookie on the write).
+    #   * Referer — over HTTPS, Flask-WTF's WTF_CSRF_SSL_STRICT (default True) also
+    #     requires a Referer matching the Superset host (same-origin check), else the
+    #     write fails with "400 The referrer header is missing." Browsers send this
+    #     automatically; an API client must set it explicitly.
+    def set_csrf_token
+      connection.headers['X-CSRFToken'] = csrf_token
+      connection.headers['Referer'] = superset_host
+    end
+
+    def csrf_token
+      @csrf_token ||= get('security/csrf_token/')['result']
+    end
+
     def connection
       @connection ||= Faraday.new(superset_host) do |f|
         f.authorization :Bearer, access_token
+        f.use :cookie_jar  # persist the Flask session cookie across the csrf_token GET and the write
         f.use FaradayMiddleware::ParseJson, content_type: 'application/json'
 
         if self.config.use_json

data/lib/superset/dashboard/bulk_delete_cascade.rb

@@ -9,10 +9,11 @@ module Superset
     class BulkDeleteCascade
       class InvalidParameterError < StandardError; end
 
-      attr_reader :dashboard_ids
+      attr_reader :dashboard_ids, :dry_run
 
-      def initialize(dashboard_ids: [])
+      def initialize(dashboard_ids: [], dry_run: true)
         @dashboard_ids = dashboard_ids
+        @dry_run = dry_run
       end
 
       def perform
@@ -20,9 +21,16 @@ module Superset
         raise InvalidParameterError, "dashboard_ids array must contain Integer only values" unless dashboard_ids.all? { |item| item.is_a?(Integer) }
 
         dashboard_ids.sort.each do |dashboard_id|
-          logger.info("Dashboard Id: #{dashboard_id.to_s} Attempting CASCADE delete of dashboard, charts, datasets")
-          delete_charts(dashboard_id)
-          delete_datasets(dashboard_id)
+          chart_ids = retrieve_chart_ids(dashboard_id)
+          dataset_ids = retrieve_dataset_ids(dashboard_id)
+
+          log_msg("------------------------- DRY RUN ONLY ---------------------------") if dry_run
+          log_msg("Dashboard Id: #{dashboard_id.to_s} Attempting CASCADE delete of dashboard, charts, datasets")
+          log_msg("  Charts: #{chart_ids.sort.join(', ')}")
+          log_msg("  Datasets: #{dataset_ids.sort.join(', ')}")
+
+          delete_charts(chart_ids)
+          delete_datasets(dataset_ids)
           delete_dashboard(dashboard_id)
         end
         true
@@ -30,18 +38,29 @@ module Superset
 
       private
 
-      def delete_datasets(dashboard_id)
-        datasets_to_delete = Superset::Dashboard::Datasets::List.new(dashboard_id: dashboard_id).datasets_details.map{|d| d[:id] }
-        Superset::Dataset::BulkDelete.new(dataset_ids: datasets_to_delete).perform if datasets_to_delete.any?
+      def delete_datasets(dataset_ids)
+        Superset::Dataset::BulkDelete.new(dataset_ids: dataset_ids).perform if dataset_ids.any? && !dry_run
       end
 
-      def delete_charts(dashboard_id)
-        charts_to_delete = Superset::Dashboard::Charts::List.new(dashboard_id).chart_ids
-        Superset::Chart::BulkDelete.new(chart_ids: charts_to_delete).perform if charts_to_delete.any?
+      def delete_charts(chart_ids)
+        Superset::Chart::BulkDelete.new(chart_ids: chart_ids).perform if chart_ids.any? && !dry_run
       end
 
       def delete_dashboard(dashboard_id)
-        Superset::Dashboard::Delete.new(dashboard_id: dashboard_id, confirm_zero_charts: true).perform
+        Superset::Dashboard::Delete.new(dashboard_id: dashboard_id, confirm_zero_charts: true).perform if !dry_run
+      end
+
+      def retrieve_chart_ids(dashboard_id)
+        Superset::Dashboard::Charts::List.new(dashboard_id).chart_ids
+      end
+
+      def retrieve_dataset_ids(dashboard_id)
+        Superset::Dashboard::Datasets::List.new(dashboard_id: dashboard_id).ids
+      end
+
+      def log_msg(message)
+        puts message
+        logger.info(message)
       end
 
       def logger

data/lib/superset/dashboard/export.rb

@@ -3,8 +3,12 @@
 # Will then unzip and copy the files into the destination_path with the dashboard_id as a subfolder
 #
 # Usage
-# Superset::Dashboard::Export.new(dashboard_id: 15, destination_path: '/tmp/superset_dashboard_backups/').perform
-#
+=begin
+  Superset::Dashboard::Export.new(
+    dashboard_id: 15,
+    destination_path: '/superset_dashboard_backups/'
+  ).perform
+=end
 
 require 'superset/file_utilities'
 
@@ -13,7 +17,7 @@ module Superset
     class Export < Request
       include FileUtilities
 
-      TMP_SUPERSET_DASHBOARD_PATH = '/tmp/superset_dashboard_exports'
+      TMP_SUPERSET_DASHBOARD_PATH = '/tmp/superset_dashboard_exports'.freeze
 
       attr_reader :dashboard_id, :destination_path
 
@@ -125,21 +129,6 @@ module Superset
       def datestamp
         @datestamp ||= Time.now.strftime('%Y%m%d')
       end
-
-      def unzip_file(zip_path, destination)
-        extracted_files = []
-        Zip::File.open(zip_path) do |zip_file|
-          zip_file.each do |entry|
-            entry_path = File.join(destination, entry.name)
-            FileUtils.mkdir_p(File.dirname(entry_path))
-            zip_file.extract(entry, entry_path) unless File.exist?(entry_path)
-            extracted_files << entry_path
-          end
-        end
-        extracted_files
-      rescue => e
-        raise
-      end
     end
 
     def logger

data/lib/superset/dashboard/import.rb

@@ -78,7 +78,8 @@ module Superset
       def source_zip_file
         return source if zip?
 
-        Zip::File.open(new_zip_file, Zip::File::CREATE) do |zipfile|
+        require 'zip'  # lazy: only import/export needs rubyzip
+        Zip::File.open(new_zip_file, create: true) do |zipfile|
           Dir[File.join(source, "**", "**")].each do |file|
             next unless File.file?(file)
 

data/lib/superset/dataset/bulk_delete.rb

@@ -16,10 +16,10 @@ module Superset
       end
 
       def perform
-        raise InvalidParameterError, "dataset_ids array of integers expected" unless dataset_ids.is_a?(Array)
+        raise InvalidParameterError, "dataset_ids array of integers expected" unless dataset_ids.is_a?(Array) && dataset_ids.any?
         raise InvalidParameterError, "dataset_ids array must contain Integer only values" unless dataset_ids.all? { |item| item.is_a?(Integer) }
 
-        logger.info("Deleting datasets with id: #{dataset_ids.join(', ')}")
+        logger.info("Deleting datasets with id: #{dataset_ids&.sort&.join(',')}")
         response
       end
 
@@ -30,7 +30,8 @@ module Superset
       private
 
       def params
-        { q: "!(#{dataset_ids.join(',')})" }
+        dataset_ids_str = dataset_ids&.sort&.join(',')
+        { q: "!(#{dataset_ids_str})" }
       end
 
       def route

data/lib/superset/file_utilities.rb

@@ -1,16 +1,21 @@
-require 'zip'
-
 module Superset
   module FileUtilities
+    # rubyzip is loaded lazily so the gem can be required without it; only
+    # consumers that actually import/export need rubyzip installed.
     def unzip_file(zip_file, destination)
+      require 'zip'
       entries = []
       Zip::File.open(zip_file) do |zip|
         zip.each do |entry|
+          next if entry.name.empty?
+
           entry_path = File.join(destination, entry.name)
           entries << entry_path
           FileUtils.mkdir_p(File.dirname(entry_path))
 
-          zip.extract(entry, entry_path) unless File.exist?(entry_path)
+          zip.extract(entry, entry.name, destination_directory: destination) { true }
+        rescue => e
+          raise "Error extracting file #{entry.name}: #{e.message}"
         end
       end
 

data/lib/superset/guest_token.rb

@@ -1,3 +1,5 @@
+require 'faraday-cookie_jar'
+
 module Superset
   class GuestToken
     include Credential::EmbeddedUser
@@ -52,13 +54,27 @@ module Superset
       'api/v1/security/guest_token/'
     end
 
+    # The guest_token endpoint is CSRF-protected (it is NOT in Superset's CSRF
+    # exempt list), so this POST needs the same treatment as Client writes:
+    # an X-CSRFToken bound to the session cookie, plus a same-origin
+    # Referer for WTF_CSRF_SSL_STRICT over HTTPS. The csrf_token GET also sets the
+    # session cookie that the cookie jar replays on the POST.
     def response
-      @response ||= connection.post(route, params.to_json)
+      @response ||= begin
+        connection.headers['X-CSRFToken'] = csrf_token
+        connection.headers['Referer'] = authenticator.superset_host
+        connection.post(route, params.to_json)
+      end
+    end
+
+    def csrf_token
+      @csrf_token ||= connection.get('api/v1/security/csrf_token/').env.body['result']
     end
 
     def connection
       @connection ||= Faraday.new(authenticator.superset_host) do |f|
         f.authorization :Bearer, access_token
+        f.use :cookie_jar  # replay the Flask session cookie from the csrf_token GET on the POST
         f.use FaradayMiddleware::ParseJson, content_type: 'application/json'
         f.request :json
         f.adapter :net_http

data/lib/superset/services/import_dashboard_across_environment.rb

@@ -87,7 +87,8 @@ module Superset
       end
 
       def create_new_dashboard_zip
-        Zip::File.open(new_zip_file, Zip::File::CREATE) do |zipfile|
+        require 'zip'  # lazy: only import/export needs rubyzip
+        Zip::File.open(new_zip_file, create: true) do |zipfile|
           Dir[File.join(dashboard_export_root_path, '**', '**')].each do |file|
             zipfile.add(file.sub(dashboard_export_root_path + '/', File.basename(dashboard_export_root_path) + '/' ), file) if File.file?(file)
           end

data/lib/superset/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Superset
-  VERSION = "0.3.5"
+  VERSION = "0.4.0"
 end

data/superset.gemspec

@@ -37,11 +37,17 @@ Gem::Specification.new do |spec|
   spec.add_dependency "json", ">= 2.0"
   spec.add_dependency "terminal-table", "~> 4.0"
   spec.add_dependency "require_all", ">= 3.0"
-  spec.add_dependency "rubyzip", ">= 1.3"
   spec.add_dependency "faraday", "~> 1.0"
   spec.add_dependency "faraday-multipart", "~> 1.0"
+  spec.add_dependency "faraday-cookie_jar", "~> 0.0.7"  # replay the Flask session cookie for CSRF
   spec.add_dependency "enumerate_it", ">= 1.7"
 
+  # rubyzip is only needed by the dashboard import/export feature, which lazily
+  # `require 'zip'` at call time. Kept as a dev dependency so those specs run here,
+  # but NOT a runtime dependency — consumers that don't import/export (embedders,
+  # read/write API clients) shouldn't inherit its rubyzip >= 3 pin.
+  # Apps that DO use import/export must declare rubyzip (>= 3.0) themselves.
+  spec.add_development_dependency "rubyzip", ">= 3.0"
   spec.add_development_dependency "dotenv", ">= 2.0"
   spec.add_development_dependency "rake", ">= 13.0"
   spec.add_development_dependency "rspec", ">= 3.0"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: superset
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.4.0
 platform: ruby
 authors:
 - jbat
@@ -52,21 +52,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
-  name: rubyzip
+  name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
-  name: faraday
+  name: faraday-multipart
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -80,19 +80,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.0'
 - !ruby/object:Gem::Dependency
-  name: faraday-multipart
+  name: faraday-cookie_jar
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 0.0.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 0.0.7
 - !ruby/object:Gem::Dependency
   name: enumerate_it
   requirement: !ruby/object:Gem::Requirement
@@ -107,6 +107,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rubyzip
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: dotenv
   requirement: !ruby/object:Gem::Requirement
@@ -201,7 +215,9 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
+- AGENTS.md
 - CHANGELOG.md
+- CLAUDE.md
 - Dockerfile
 - LICENSE
 - README.md