superset 0.3.6 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a175ae90fbf33b12baafc49758b5c9b2e2869702a6be4f45849f66ac5a40afee
-  data.tar.gz: bc9938edda2fd5879b1f1824116b572638ea8685dd7b4115ca3fbfba08cf6a3f
+  metadata.gz: 6ec3571934b0c40b84d75e2bfc55fb010fbae561539d65b2a20f6131cfcef323
+  data.tar.gz: 9e68d4aa5a36aba31b4b548eb9a7bf131e45c3c168090782207ea9e1238228de
 SHA512:
-  metadata.gz: 07d9b38d89bc252ea2a64b0cb835e9b9eefde88182636b4e8f900ccb7800e4e41f46fa3d15251ce3ba959f2805747f44b482d3b6b93c989ecbcb064d5d50ada9
-  data.tar.gz: 77a8f91b04674504ec174ba04e166b30fd5e42e30ce0c7b9a5904944893108fd5a5ef8052c066082d476c79518dacd911c3660d246e9b6bd9bf9f11fafe6c9f7
+  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,5 +1,12 @@
 ## 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

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/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/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/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.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", ">= 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"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: superset
 version: !ruby/object:Gem::Version
-  version: 0.3.6
+  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: '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
@@ -201,7 +215,9 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
+- AGENTS.md
 - CHANGELOG.md
+- CLAUDE.md
 - Dockerfile
 - LICENSE
 - README.md