activeadmin_batched_export 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f422e2d7c0f709e46fabfda5bc837d53835c5951d35520687c8c0008b0fbc851
-  data.tar.gz: c0f9c04756c060ac5c9b5e3d8ad85fcf825a13deaad5f59eadd6b3d625ee97f4
+  metadata.gz: f53b863da20a561edbc6192d923009b25b6f2f7efb69befbaca5385ebb5dfac4
+  data.tar.gz: 727a408e9c7f12a5238441845e37222aef9dd8d34a4217ef8e2b1cf4871e4d12
 SHA512:
-  metadata.gz: 168669e5c28b6adbac2f09f7fe2f01cba5209639d36f32221d15592e4197730a948d2cd02646bbb679ec9e195a059746282d181abc9b72f43fe9ea14ea211d61
-  data.tar.gz: 7714ba53d4b2592d167e89ca07a41a16d61be9bec0db2a3f28fea88642d17852606ee15a96bf5adbc80524676629804013b689735065b15daa56c2a157b544f6
+  metadata.gz: 336b5af8351b73c2422fc566400c54c35926dcf8f953c06c53481ed8c9b34dc3eb28f8b1e5f7411d20b70746ac35bfde91c545371afd4bbc77b81681aaa1b150
+  data.tar.gz: ac52d361d860f738200c9c334c2d40d198e32558a356d26f78313cc464e1054ece083dc8f34c8455acfe737b30f6ac470df05bec40822963c7457dc1b5919adc

data/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.3.0 (2026-09-04)
+
+- BREAKING: Walk export batches with `export_cursor` and `X-Batched-Export-Next` instead of OFFSET `batch_page`. Hosts that copied the Stimulus controller must pick up the new loop.
+- Freeze filtered ids when table `active_admin_batched_export_snapshot_rows` exists (`export_snapshot`, `X-Batched-Export-Snapshot`). Without the table, batches keep walking a live keyset.
+- Add `max_export_rows` (nil = unlimited). A COUNT over the cap is 400 on the first batch; meta still returns 200 with `over_max`.
+- Sort NULL keys last in both directions.
+- Always refetch export meta before load. Stop on a short last page. Concatenate JSON chunks as one array. Cancel keeps an incomplete Blob.
+- Return 400 when `export_columns` resolve to no columns.
+
 ## 0.2.0 (2026-07-14)
 
 - Treat a per-resource `batched_export` DSL call as enablement; `enabled: true` is no longer required when opting in per resource.

data/CODE_OF_CONDUCT.md

@@ -1,38 +1,26 @@
 # Code of Conduct
 
-## Our Pledge
+## Pledge
 
-We pledge to make participation in our community a harassment-free experience for everyone. We operate on principles of mutual respect, privacy, and authentic engagement. We value substantive contributions and clarity on intentions.
+Participation is a harassment-free experience. Treat each other with respect. Keep private context private.
 
-## Our Standards
+## Expected behavior
 
-Examples of behavior that contributes to a positive environment include:
+- Engage with genuine curiosity. Admit uncertainty.
+- Own every line you submit, including generated code.
+- Correct errors politely.
+- Use language that welcomes people and respects identity and privacy.
 
-* **Authenticity:** Engaging with genuine curiosity and admitting uncertainty rather than feigning knowledge.
+## Unacceptable behavior
 
-* **Responsible Innovation:** Taking full responsibility for any content or code contributed, whether manually written or generated by automation tools.
+- Harassment, trolling, or insulting comments, public or private.
+- Using jargon or volume, including automated spam, to silence others.
+- Sharing others' data or personal context without permission.
 
-* **Gentle Correction:** Responding politely to errors. We view mistakes as opportunities for learning, provided they are addressed with humility.
+## Automation
 
-* **Inclusive Language:** Using language that welcomes diverse perspectives and respects the privacy and identity of all participants.
-
-Examples of unacceptable behavior include:
-
-* **Harassment:** Public or private harassment, trolling, or insulting comments.
-
-* **Weaponized Complexity:** Using jargon or overwhelming volume (including automated spam) to silence others.
-
-* **Publishing Private Information:** Sharing others' data or personal context without explicit permission.
-
-## Artificial Intelligence & Automation
-
-In accordance with our commitment to **Collective Awareness**:
-
-* Contributors are responsible for the accuracy and security of any AI-generated artifacts they submit.
-
-* "The AI wrote it" is not a valid excuse for introducing bugs, security vulnerabilities, or bias.
+You remain responsible for bugs, security holes, and bias in generated artifacts you submit.
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at contact@kiskolabs.com. All complaints will be reviewed and investigated promptly and fairly.
-
+Report abusive or harassing behavior to contact@kiskolabs.com. Reports are reviewed and investigated.

data/CONTRIBUTING.md

@@ -1,29 +1,23 @@
 # Contributing Guidelines
 
-Thank you for your interest in contributing to activeadmin_batched_export. We value **learning over perfection** but require **rigor and responsibility**.
+## Automation authorship
 
-## The Golden Rule of Automation
+You may use AI and automation tools. You remain the author of every line you submit: review, debug, and understand the change.
 
-We welcome the use of AI and automation tools to reduce toil, but you must strictly adhere to the following:
+Keep pull requests small enough to review. Annotate non-obvious logic.
 
-1. **You are the Author:** You act as the responsible agent for any code you submit. You must review, debug, and understand every line.
-2. **Manage Cognitive Load:** Do not submit massive, unreviewed automated dumps. Respect the reviewers' time by annotating complex logic.
-3. **Security:** Never feed project secrets or private context into public AI models.
+Never send project secrets or private context to public models.
 
-## How to Contribute
+## How to contribute
 
-### 1. Reporting Issues
+### Reporting issues
 
-- **Verify Accuracy:** Before posting, verify your information. Avoid generalizations.
-- **Use Structured Inputs:** Use our Issue Templates to provide clear goals, constraints, and reproduction steps.
+Verify the facts before filing. Use issue templates for goals, constraints, and reproduction steps.
 
-### 2. Pull Request Process
+### Pull requests
 
-- **Scope:** Keep PRs focused on a single goal.
-- **Context:** Explain why the change is necessary.
-- **Testing:** Run `make test` locally before opening a PR.
+Keep one pull request to one goal. Explain why the change is needed. Run smoke tests and regression checks locally before opening the request.
 
-### 3. Review Process
+### Review
 
-- We encourage productive friction. Expect questions about your approach.
-- If a reviewer suggests a change, view it as mutual aid, not criticism.
+Reviewers will ask about approach and trade-offs. Treat suggested changes as part of the work.

data/GOVERNANCE.md

@@ -1,32 +1,25 @@
 # Project Governance
 
-## Overview
-
-This project balances **individual autonomy** with **collective coordination**. We aim for a workflow that supports rapid iteration while maintaining strict guardrails for safety and architectural integrity.
-
 ## Roles
 
 ### Contributors
 
-Anyone who submits code, documentation, or participates in discussions. Contributors are expected to exercise **Direct Action**—taking ownership of problems they identify—while adhering to our quality standards.
-
-### Maintainers (Human Oversight)
-
-Maintainers are responsible for:
-
-1.  **Strategic Judgment:** Defining scope and architectural direction.
+Anyone who submits code, documentation, or participates in discussions. Contributors take ownership of problems they identify and follow the project's quality standards.
 
-2.  **Review:** verifying that contributions (human or automated) meet security and logic standards.
+### Maintainers
 
-3.  **Consensus Building:** Facilitating decisions when the community is divided.
+Maintainers:
 
-## Decision Making process
+1. Set scope and architectural direction.
+2. Review contributions (human or automated) against security and logic standards.
+3. Decide when the community is divided.
 
-### Lazy Consensus
+## Decision making
 
-For most routine changes, we operate on "lazy consensus." If a proposal is made and no objections are raised within two weeks, it is considered approved.
+### Lazy consensus
 
-### Strategic Alignment
+For routine changes, a proposal that draws no objection within two weeks is approved.
 
-Major architectural changes, high-risk automation integrations, or changes that affect business logic require explicit approval from the Maintainers. We prioritize **substance over performance**—a change must solve a real problem, not just appear polished.
+### Maintainer approval
 
+Major architectural changes, high-risk automation integrations, or changes that affect business logic need explicit maintainer approval. A change must solve a real problem.

data/README.md

@@ -4,11 +4,11 @@
 
 Batched CSV, JSON, and XML export workspace for ActiveAdmin 4.
 
-Replaces single long-lived index downloads with a workspace page that loads filtered data in sequential HTTP batches, then offers one client-side file download.
+Replaces single long-lived index downloads with a workspace page that loads filtered data in sequential batches, then offers one client-side file download.
 
 ## Requirements
 
-- Ruby 3.2+
+- Ruby 3.4+
 - Rails 7.1+
 - ActiveAdmin 4.0.0.beta13+
 - importmap-rails and Stimulus (ActiveAdmin 4 default)
@@ -39,6 +39,22 @@ bundle install
 
 The engine registers routes, views, importmap pins, and install hooks automatically. Optional host overrides go in `config/initializers/activeadmin_batched_export.rb`.
 
+To freeze export ids across batches (RFC-0003), create this table in the host app:
+
+```ruby
+create_table :active_admin_batched_export_snapshot_rows do |t|
+  t.string :token, null: false
+  t.string :resource_type, null: false
+  t.bigint :record_id, null: false
+  t.integer :position, null: false
+  t.datetime :created_at, null: false
+end
+add_index :active_admin_batched_export_snapshot_rows, [:token, :position], unique: true
+add_index :active_admin_batched_export_snapshot_rows, :created_at
+```
+
+Without that table, batches walk a live keyset cursor. With it, the first batch stores filtered primary keys and later batches join live rows in freeze order. The token is not an access grant: rows still load through `find_collection`.
+
 Enable download formats per resource:
 
 ```ruby
@@ -62,6 +78,8 @@ ActiveAdmin::BatchedExport.configure do |config|
   config.batch_size = 1000
   config.max_batch_size = 10_000
   config.large_export_row_threshold = 25_000
+  config.max_export_rows = nil
+  config.snapshot_ttl = 86_400
   config.stimulus_controller = "activeadmin-batched-export--batched-export"
 
   config.styles = ActiveAdmin::BatchedExport::Styles.new(
@@ -121,6 +139,7 @@ ActiveAdmin::BatchedExport.configure do |config|
     card: "rounded-lg border border-slate-200 bg-slate-50 p-6",
     primary_button: "btn btn-primary",
     secondary_button: "btn btn-outline",
+    cancel_button: "btn btn-ghost",
     back_link: "link link-primary"
   )
 end
@@ -128,7 +147,7 @@ end
 
 Override only the keys you need; unset keys keep gem defaults (light and dark Tailwind classes).
 
-Available keys: `workspace`, `card`, `card_title`, `table`, `table_body`, `table_row`, `table_header`, `table_cell`, `table_cell_mono`, `hint`, `column_grid`, `column_label`, `column_checkbox`, `heading`, `progress_wrap`, `progress_bar`, `progress_status_row`, `error`, `warning`, `actions`, `primary_button`, `secondary_button`, `back_link`.
+Available keys: `workspace`, `card`, `card_title`, `table`, `table_body`, `table_row`, `table_header`, `table_cell`, `table_cell_mono`, `hint`, `column_grid`, `column_label`, `column_checkbox`, `heading`, `progress_wrap`, `progress_bar`, `progress_status_row`, `error`, `warning`, `actions`, `primary_button`, `secondary_button`, `cancel_button`, `back_link`.
 
 ### Override partials
 
@@ -139,7 +158,7 @@ Copy any partial from the gem into `app/views/active_admin/batched_export/` in t
 - `_columns.html.erb`
 - `_filters.html.erb`
 - `_progress.html.erb`
-- `_actions.html.erb` — export and back buttons
+- `_actions.html.erb` — load, cancel, save, and back buttons
 
 ### Stimulus controller
 
@@ -157,20 +176,20 @@ See [examples/custom_theme/README.md](examples/custom_theme/README.md) for local
 
 ## Stimulus controller and assets
 
-The engine pins `controllers/activeadmin_batched_export/batched_export_controller` on both the host and ActiveAdmin importmaps. Include the gem asset path in your ActiveAdmin importmap cache sweeper when developing locally.
+The engine pins `controllers/activeadmin_batched_export/batched_export_controller` and `activeadmin_batched_export/chunk_assembly` on both the host and ActiveAdmin importmaps. Include the gem `app/assets/controllers` and `app/assets/javascripts` paths in your ActiveAdmin importmap cache sweeper when developing locally.
 
 ## How it works
 
 1. Index download links route to `batched_export` instead of synchronous format URLs.
 2. Workspace shows filter context, optional column checkboxes, and batch metadata.
-3. Stimulus fetches `export_meta` JSON, then each `batch_page` chunk.
-4. User saves the assembled Blob locally.
+3. Load export always refetches `export_meta` JSON for a progress estimate, then walks chunks with `export_cursor` / `X-Batched-Export-Next` until that header is absent. When the freeze table exists, the first batch also returns `X-Batched-Export-Snapshot` and later chunks send `export_snapshot` with the cursor.
+4. User saves the assembled Blob locally. Cancel keeps an incomplete file when any chunks already arrived.
 
-Batched requests limit server memory per request; the browser still holds the full assembled file before save. Very large exports can exhaust tab memory. Tune `batch_size`, `max_batch_size`, and `large_export_row_threshold` for your data width and row counts. The workspace shows a warning when row count reaches the threshold.
+Batched requests limit server memory per request; the browser still holds the full assembled file before save. Very large exports can exhaust tab memory. Tune `batch_size`, `max_batch_size`, and `large_export_row_threshold` for your data width and row counts. The workspace shows a warning when row count reaches the threshold. Set `max_export_rows` to refuse a collection larger than that count (`over_max` on meta, 400 on the first batch).
 
-Each batch page uses offset pagination on the filtered collection. Later batches can slow down on very large tables; narrowing filters or raising `batch_size` within `max_batch_size` reduces batch count.
+When the freeze table exists, the first batch stores filtered primary keys in NULL-safe order (RFC-0003). Later batches walk those positions and join live cells. Inserts after freeze are omitted. Updates after freeze appear. Deleted freeze ids are skipped. Without the table, each chunk continues after the last returned sort key and primary key (RFC-0002) and is not a point-in-time snapshot. Custom `order_by` expressions fall back to primary key descending. NULL sort keys sort last in both directions.
 
-JSON and XML exports use the same column definitions as `csv` blocks. JSON batches return arrays of row objects; the client merges them into one array. XML batches return record fragments; the client wraps them in a single `<export>` root. Shapes differ from ActiveAdmin synchronous JSON/XML downloads.
+JSON and XML exports use the same column definitions as `csv` blocks. JSON batches return arrays of row objects; the client concatenates those arrays as text into one array. XML batches return record fragments; the client wraps them in a single `<export>` root. Shapes differ from ActiveAdmin synchronous JSON/XML downloads.
 
 Authorization follows ActiveAdmin `download_links` and `authorize!` on the resource. Disable a format with `index download_links: [:csv]` (or `false` to hide exports). Batch endpoints reject formats not listed on the resource index presenter.
 
@@ -182,10 +201,11 @@ From the gem root:
 bundle install
 bundle exec appraisal install
 bundle exec rubocop
+make test-javascript
 bundle exec polyrun parallel-rspec --workers 5 --merge-failures
 ```
 
-Matrixed Rails versions use [Appraisal](https://github.com/thoughtbot/appraisal): `gemfiles/rails72.gemfile`, `rails8ruby34.gemfile`, and `rails8truffleruby.gemfile`. Run `bundle exec appraisal rspec` to execute RSpec in each gemfile context.
+Matrixed Rails versions use [Appraisal](https://github.com/thoughtbot/appraisal): `gemfiles/rails72.gemfile` and `rails8ruby34.gemfile`. Run `bundle exec appraisal rspec` to execute RSpec in each gemfile context.
 
 Shared agent guidance is managed with [pray](https://github.com/kiskolabs/pray) via `Prayfile`.
 
@@ -195,6 +215,19 @@ Shared agent guidance is managed with [pray](https://github.com/kiskolabs/pray)
 
 See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and pull requests are welcome at https://github.com/amkisko/activeadmin_batched_export.rb/issues
 
+## Links
+
+- [GitHub](https://github.com/amkisko/activeadmin_batched_export.rb)
+- [GitLab](https://gitlab.com/amkisko/activeadmin_batched_export.rb)
+- [RubyGems](https://rubygems.org/gems/activeadmin_batched_export)
+- [Versions Atom](https://rubygems.org/gems/activeadmin_batched_export/versions.atom) (feed id `11574013576629`)
+- [libraries.io](https://libraries.io/rubygems/activeadmin_batched_export)
+- [Deps.dev](https://deps.dev/rubygems/activeadmin_batched_export)
+- [SonarCloud](https://sonarcloud.io/project/overview?id=amkisko_activeadmin_batched_export.rb)
+- [Snyk](https://snyk.io/test/github/amkisko/activeadmin_batched_export.rb)
+- [Codecov](https://app.codecov.io/github/amkisko/activeadmin_batched_export.rb)
+- [OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/amkisko/activeadmin_batched_export.rb)
+
 ## License
 
 MIT — see [LICENSE.md](LICENSE.md).

data/SECURITY.md

@@ -2,27 +2,24 @@
 
 ## Reporting a Vulnerability
 
-Do NOT open a public GitHub issue for security vulnerabilities.
-
 Email security details to: security@kiskolabs.com
 
-Include: description, steps to reproduce, potential impact, and suggested fix (if available).
+Send the report only to that address. Include description, steps to reproduce, potential impact, and a suggested fix when you have one.
 
 ### Response Timeline
 
-- We will acknowledge receipt of your report
-- We will provide an initial assessment
-- We will keep you informed of our progress and resolution timeline
+- We will acknowledge receipt of your report.
+- We will provide an initial assessment.
+- We will keep you informed of our progress and resolution timeline.
 
 ### Disclosure Policy
 
-- We will work with you to understand and resolve the issue
-- We will credit you for the discovery (unless you prefer to remain anonymous)
-- We will publish a security advisory after the vulnerability is patched
-- We will coordinate public disclosure with you
+- We will work with you to understand and resolve the issue.
+- We will credit you for the discovery unless you prefer to remain anonymous.
+- We will publish a security advisory after the vulnerability is patched.
+- We will coordinate public disclosure with you.
 
 ## Automation Security
 
-* Context Isolation: It is strictly forbidden to include production credentials, API keys, or Personally Identifiable Information (PII) in prompts sent to third-party LLMs or automation services.
-
-* Supply Chain: All automated dependencies must be verified.
+- Keep production credentials, API keys, and personal data out of prompts sent to third-party models or automation services.
+- Verify automated dependencies.

data/activeadmin_batched_export.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description = "Replaces long-lived ActiveAdmin index downloads with a batched export workspace, customizable views, and export column macros."
   spec.license = "MIT"
   spec.platform = Gem::Platform::RUBY
-  spec.required_ruby_version = ">= 3.2.0"
+  spec.required_ruby_version = ">= 3.4"
 
   repository_url = "https://github.com/amkisko/activeadmin_batched_export.rb"
 
@@ -63,5 +63,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "standard-performance", "~> 1.8"
   spec.add_development_dependency "standard-rails", "~> 1.5"
   spec.add_development_dependency "standard-rspec", "~> 0.3"
-  spec.add_development_dependency "rbs", "~> 3"
+  spec.add_development_dependency "rbs", "~> 4"
 end