superset 0.3.6 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a175ae90fbf33b12baafc49758b5c9b2e2869702a6be4f45849f66ac5a40afee
-  data.tar.gz: bc9938edda2fd5879b1f1824116b572638ea8685dd7b4115ca3fbfba08cf6a3f
+  metadata.gz: 59ab63d9f8d51f73e9ca6606a0a559c75def26e9c69ab09eeeb59fd91cf24447
+  data.tar.gz: c7ae83dfa2a5b5f0e100d6cce0d38e7badf04e20d174c661207223493179f851
 SHA512:
-  metadata.gz: 07d9b38d89bc252ea2a64b0cb835e9b9eefde88182636b4e8f900ccb7800e4e41f46fa3d15251ce3ba959f2805747f44b482d3b6b93c989ecbcb064d5d50ada9
-  data.tar.gz: 77a8f91b04674504ec174ba04e166b30fd5e42e30ce0c7b9a5904944893108fd5a5ef8052c066082d476c79518dacd911c3660d246e9b6bd9bf9f11fafe6c9f7
+  metadata.gz: 9f0f70518ea7bc2f9e19ba9c115bdb1c2c44f05abc0e887fcfb0de1934499847841e601ec0d5e8aabb957c368196873cad0bae6ccb300ce55fe8d9eedd3c4e29
+  data.tar.gz: 3a90c54aca065f2187bf971912dc2993f25034f6c1880fb4d973a90da3b2a1d63188871acfe64d7448abd431f27a2ea52ecc91d1c9c55194f9815016b8872b61

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 through `Superset.logger`; by default writes to `log/superset-client.log`. Consumers can inject any `::Logger`-compatible object via `Superset.configure { |c| c.logger = your_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,5 +1,21 @@
 ## Changelog
 
+## 0.5.0 - 2026-07-21
+
+* Decouple from Rollbar — remove the `Rollbar.error(...) if defined?(Rollbar)` call in `WarmUpCache`; exceptions now propagate to the caller so consumers' own error handling can react
+* Introduce configurable logger via `Superset.configure { |c| c.logger = ... }` — any object responding to `#info` and `#error` (default remains `log/superset-client.log`)
+* **Breaking:** `Superset::Dashboard::WarmUpCache.new(...).perform` now raises on per-dataset failures instead of swallowing them; wrap the call in your own `rescue` if you need the previous silent behavior
+* Remove unused `DuplicateDashboardLogger` module (dead code)
+* Drop `rollbar` dev dependency; drop `require "rollbar"` from `spec_helper.rb` and `bin/console`
+* Add explicit `require 'json'` (the gem uses `to_json` in 8+ places and was relying on rollbar to transitively load it)
+
+## 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

data/CLAUDE.md

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

data/README.md

@@ -44,6 +44,23 @@ Add to your Gemfile `gem 'superset'`
 And then execute: `bundle install`  
 Or install it yourself as `gem install superset`
 
+## Configuration
+
+The gem writes logs (dashboard duplication progress, API failures, etc.) through `Superset.logger`. By default it writes to `log/superset-client.log` relative to the working directory.
+
+To route logs elsewhere — for example, STDOUT for a background worker, a null sink for tests, or your application's existing logger — configure it once at boot:
+
+```ruby
+require 'logger'
+require 'superset'
+
+Superset.configure do |config|
+  config.logger = ::Logger.new($stdout)  # or any object responding to #info(msg) and #error(msg)
+end
+```
+
+Any object that responds to `#info(msg)` and `#error(msg)` will work — a stdlib `::Logger`, a `SemanticLogger` instance, a framework-provided logger, or a custom wrapper that forwards to your error-reporting service. The gem does not assume any particular framework.
+
 ## Run specs
 
 ```

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/configuration.rb

@@ -0,0 +1,11 @@
+require "logger"
+
+module Superset
+  class Configuration
+    attr_accessor :logger
+
+    def initialize
+      @logger = nil
+    end
+  end
+end

data/lib/superset/dashboard/import.rb

@@ -78,6 +78,7 @@ module Superset
       def source_zip_file
         return source if zip?
 
+        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/dashboard/warm_up_cache.rb

@@ -3,7 +3,7 @@ module Superset
     class WarmUpCache < Superset::Request
 
       attr_reader :dashboard_id
-      
+
       def initialize(dashboard_id:)
         @dashboard_id = dashboard_id
       end
@@ -16,11 +16,7 @@ module Superset
       def response
         dataset_details = fetch_dataset_details(dashboard_id)
         dataset_details.each do |dataset|
-          begin
-            warm_up_dataset(dataset["datasource_name"], dataset["name"])
-          rescue => e
-            Rollbar.error("Warm up cache failed for the dashboard #{dashboard_id.to_s} and for the dataset #{dataset["datasource_name"]} - #{e}") if defined?(Rollbar)
-          end 
+          warm_up_dataset(dataset["datasource_name"], dataset["name"])
         end
       end
 
@@ -29,7 +25,7 @@ module Superset
       end
 
       private
-      
+
       def validate_dashboard_id
         raise InvalidParameterError, "dashboard_id must be present and must be an integer" unless dashboard_id.present? && dashboard_id.is_a?(Integer)
       end

data/lib/superset/file_utilities.rb

@@ -1,8 +1,9 @@
-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|

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/logger.rb

@@ -1,20 +1,11 @@
 module Superset
   class Logger
-
     def info(msg)
-      # puts msg   # allow logs to console
-      logger.info msg
+      Superset.logger.info(msg)
     end
 
     def error(msg)
-      # puts msg   # allow logs to console
-      logger.error msg
-    end
-
-    def logger
-      @logger ||= begin
-        ::Logger.new("log/superset-client.log")
-      end
+      Superset.logger.error(msg)
     end
   end
 end

data/lib/superset/services/import_dashboard_across_environment.rb

@@ -87,6 +87,7 @@ module Superset
       end
 
       def create_new_dashboard_zip
+        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)

data/lib/superset/version.rb

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

data/lib/superset.rb

@@ -3,7 +3,10 @@
 require 'require_all'
 require 'terminal-table'
 require 'happi'
+require 'logger'
+require 'json'
 
+require_relative "superset/configuration"
 require_rel "superset/credential"
 require_relative "superset/authenticator"
 require_relative "superset/client"
@@ -15,5 +18,31 @@ require_rel "superset"
 
 module Superset
   class Error < StandardError; end
-  # Your code goes here...
+
+  DEFAULT_LOG_PATH = "log/superset-client.log"
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def logger
+      configuration.logger || default_logger
+    end
+
+    def reset_configuration!
+      @configuration = nil
+      @default_logger = nil
+    end
+
+    private
+
+    def default_logger
+      @default_logger ||= ::Logger.new(DEFAULT_LOG_PATH)
+    end
+  end
 end

data/superset.gemspec

@@ -37,17 +37,22 @@ 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", ">= 3.0"
   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"
   spec.add_development_dependency "rubocop", ">= 1.0"
   spec.add_development_dependency "pry", ">= 0.14"
-  spec.add_development_dependency "rollbar", ">= 3.0"
 
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: superset
 version: !ruby/object:Gem::Version
-  version: 0.3.6
+  version: 0.5.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: '3.0'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        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
@@ -177,20 +191,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.14'
-- !ruby/object:Gem::Dependency
-  name: rollbar
-  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'
 email:
 - jonathon.batson@gmail.com
 executables: []
@@ -201,7 +201,9 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
+- AGENTS.md
 - CHANGELOG.md
+- CLAUDE.md
 - Dockerfile
 - LICENSE
 - README.md
@@ -214,7 +216,6 @@ files:
 - docker-compose.override.yml
 - docker-compose.yml
 - env.sample
-- lib/loggers/duplicate_dashboard_logger.rb
 - lib/superset.rb
 - lib/superset/authenticator.rb
 - lib/superset/base_put_request.rb
@@ -227,6 +228,7 @@ files:
 - lib/superset/chart/put.rb
 - lib/superset/chart/update_dataset.rb
 - lib/superset/client.rb
+- lib/superset/configuration.rb
 - lib/superset/credential/api_user.rb
 - lib/superset/credential/embedded_user.rb
 - lib/superset/dashboard/bulk_delete.rb

data/lib/loggers/duplicate_dashboard_logger.rb

@@ -1,15 +0,0 @@
-module Superset
-  module DuplicateDashboardLogger
-   
-    
-    def logger
-      @logger ||= begin
-        if defined?(Rails)
-          Rails.try(:logger) || Logger.new(STDOUT)
-        else
-          Logger.new(STDOUT)
-        end
-      end
-    end
-  end
-end