Split READMEs per package and resolve flowvault README review - #396
Merged
Devesh-Skyflow merged 3 commits intoAug 3, 2026
Merged
Conversation
Ports the README restructure from devesh/v2-flowvault-readmes onto this release branch, which already carries the v2 -> skyvault rename: - root README.md becomes a short landing page pointing at each package - skyvault/README.md holds the full skyflow-java documentation - flowvault/README.md documents the skyflow-flowvault-java bulk surface Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…r model
Resolves review comments on the flowvault README:
- Quickstart declared `VaultController vault` twice. The second line also
called `skyflowClient.vault("<VAULT_ID>")`, which flowvault does not
expose — its `vault()` takes no argument and always resolves to the
first configured vault. Both fixed, and the single-vault behaviour is
now stated.
- Auth, Credentials, VaultConfig and error handling lived only in the
skyvault README, so flowvault users had to switch documents to get
started. flowvault now documents them inline: credential types and
their setters, credential resolution order, bearer token generation,
a full VaultConfig / Skyflow.builder() reference, timeout and retry
resolution with defaults, and logging. Only the exotic token variants
(context, scoped, signed) still point at skyvault.
- Added a note that flowvault is a new SDK versioned independently, so a
1.x flowvault next to a 2.x skyvault does not read as a downgrade. In
both the flowvault README and the root package table.
- Rewrote Error Handling around flowvault's actual model: request-level
SkyflowException versus per-record success/failure inside a call that
returns normally, including the trap that a call where every record
failed still does not throw. Documents index/httpCode/error/requestId
per record, the per-operation summaries, consumption loops for both
the one-level and two-level (tokenize) shapes, and the retry helpers.
Also brings the API surface in line with this branch, which renamed
several types after the README was first written: BulkInsertRequestRecord
(was BulkInsertRecord), tableName (was table), UpsertOptions (was
upsert/upsertType), TokenGroupRedactions (was BulkTokenGroupRedactions),
Bulk*Options (was InsertOptions/TokenizeOptions/...), CustomHeaderKey
.SkyflowAccountId/.RequestIdHeader, and the response shape, which is now
a single `records` list rather than separate `success` and `errors` lists.
Verified: all 20 Java snippets compile against the branch's classes, and
every sample JSON response matches the real toString() output.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## flowvault-release/26.8.1 #396 +/- ##
==============================================================
+ Coverage 90.98% 91.22% +0.24%
- Complexity 0 451 +451
==============================================================
Files 158 157 -1
Lines 6421 6372 -49
Branches 860 853 -7
==============================================================
- Hits 5842 5813 -29
+ Misses 376 367 -9
+ Partials 203 192 -11
Flags with carried forward coverage won't be shown. Click here to find out more.
Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
The flowvault README noted that bulk calls are split into batches sent concurrently, but never documented how to configure that. Add a "Batching and concurrency" section covering the per-operation env vars, their defaults and maximums, and how effective values are resolved. Values verified against Constants.java and the configure*ConcurrencyAndBatchSize methods in VaultController: batch size is min(value, max) with a warning-and- clamp above the max and a warning-and-default for invalid input; concurrency is additionally capped at ceil(itemCount / batchSize), so it never exceeds the number of batches to run. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Devesh-Skyflow
merged commit Aug 3, 2026
2e606ce
into
flowvault-release/26.8.1
23 of 26 checks passed
Devesh-Skyflow
added a commit
that referenced
this pull request
Aug 3, 2026
* SK-2967 split out the common things from v2 and v3 into common module * SK-2967 add interface for skyflow * SK-2967 move common code from v2 and flowvault * SK-2967 fix tests * SK-2967 add base insert request and refactor the base skyflow * SK-2967 move vault url in v3 * SK-2967 update generated code * SK-2967 update the internal release * SK-2967 update script version * [AUTOMATED] Private Release 1.15.1-dev-f6a6992 * SK-2967 update internal release workflow * [AUTOMATED] Private Release 1.15.1-dev-807824c * SK-2967 add interfaces * SK-2967 fix internal release workflows * [AUTOMATED] Private Release 1.15.1-dev-cd30d53 * SK-2967 fix internal release workflows * [AUTOMATED] Private Release 1.15.1-dev-139086e * SK-2967 fix internal release workflows * SK-2967 fix internal release workflows * SK-2967 fix internal release workflows * SK-2967 add back the bulk interfaces * SK-2967 implement client * SK-2967 fix compile errors * SK-2967 fix compile errors * SK-2967 revert generated code * SK-2967 improve the issues * SK-2984 Add contract testing for v2 SDK (#352) * SK-2967 added query and get methods * SK-3026 insert and detokenize added accordingt to doc * SK-3026 fix test env * SK-3026 fix response building * SK-3026 fix spell check * SK-3026 fix spell check * SK-3026 point codecov at per-module jacoco reports The Codecov step uploaded target/site/jacoco/jacoco.xml, which was correct when this repo was a single Maven module. Since the common/v2/flowvault split the root pom is <packaging>pom</packaging> with no sources, so that file is never generated - codecov received nothing and reported no coverage for the PR. Verified locally: 'mvn -B package -f pom.xml' produces reports only at common/, v2/ and flowvault/ target/site/jacoco/jacoco.xml; the root path does not exist. Same class of issue as the 'Distribute test fixtures to modules' step already added on this branch - a repo-root path left over from the single-module layout. * SK-3026 fix codecov component paths for the modular layout Every individual_component path was rooted at src/main/java/..., which was correct when this was a single Maven module. Sources now live at <module>/src/main/java/..., so all 11 component globs matched zero files and each component reported no coverage data - which is the 'no coverage reports found' seen on the PR. The uploaded report itself was fine: the Codecov API shows state 'complete' for c1c5719 with 115 files at 91.75% (v2 55, common 30, flowvault 30), correctly path-resolved. Only the component matching was broken. Prefixed each glob with **/ so components aggregate a functional area across all modules, matching the previous semantics. Quoted because a bare leading * is a YAML alias. Verified against the real file list from the Codecov API: 0 components match zero files (was 11/11). * SK-3026 added retries * SK-3026 update the name of vaultURL * [AUTOMATED] Private Release 3.0.0-beta.13-dev-671dbf3 * SK-3026 fix the doc error in release * [AUTOMATED] Private Release 3.0.0-beta.13-dev-0d4db0a * SK-3026 added samples folder in each modules v2 and v3 * [AUTOMATED] Private Release 3.0.0-beta.13-dev-202473d3 * SK-3026 added samples folder in each modules v2 and v3 * [AUTOMATED] Private Release 3.0.0-beta.13-dev-a341d09f * SK-3037: rework delete and tokenize to the FlowDB contract (#385) * [AUTOMATED] Private Release 3.0.0-beta.13-dev-1dea6f89 * SK-3026 fix insert issue * [AUTOMATED] Private Release 3.0.0-beta.13-dev-9a074a90 * SK-3026 Fix api exception level issue * [AUTOMATED] Private Release 3.0.0-beta.13-dev-61de168d * SK-3026 Fix api exception level issue for detokenize * [AUTOMATED] Private Release 3.0.0-beta.13-dev-f70f738d * SK-3026 fix naming for skyflow id in detokenize * [AUTOMATED] Private Release 3.0.0-beta.13-dev-28dcc895 * SK-3026 add request id in insert and detokenize * [AUTOMATED] Private Release 3.0.0-beta.13-dev-1458dbdb * SK-3026 update options name in insert and detokenize * [AUTOMATED] Private Release 3.0.0-beta.13-dev-ed84cb86 * SK-3026 fix spell check * [AUTOMATED] Private Release 3.0.0-beta.13-dev-3671a19a * [AUTOMATED] Private Release 3.0.0-beta.13-dev-16df1ee5 * SK-3037 give the bulk tokenize and delete interfaces their own options types (#390) * [AUTOMATED] Private Release 3.0.0-beta.13-dev-6577fa70 * SK-3026 retry logic update * [AUTOMATED] Private Release 3.0.0-beta.13-dev-9bd1b4be * [AUTOMATED] Private Release 3.0.0-beta.13-dev-969e339a * SK-3026 fix spell check * [AUTOMATED] Private Release 3.0.0-beta.13-dev-eb744eb6 * SK-3026 update v2 folder to skyvault * [AUTOMATED] Private Release 3.0.0-beta.13-dev-f2f6bb20 * SK-3026 add unit tests * [AUTOMATED] Private Release 3.0.0-beta.13-dev-5e368050 * [AUTOMATED] Private Release 3.0.0-beta.13-dev-f72e2218 * SK-3037 report the real cause when tokenize or delete never reach the API (#394) * [AUTOMATED] Private Release 3.0.0-beta.13-dev-2a83759e * SK-3026 add tests * [AUTOMATED] Private Release 3.0.0-beta.13-dev-58dda850 * SK-3026 add tests * [AUTOMATED] Private Release 3.0.0-beta.13-dev-1ff91444 * SK-2967 Backport pr-flowvault.yml CI workflow (#391) * Backport pr-flowvault.yml CI workflow from flowvault-release/test-artifactory-path Verified via a dummy test PR (#381) against that branch - Build and Unit Tests jobs both passed, scoped correctly to flowvault/common/pom.xml path changes. This workflow only existed on the test-artifactory-path branch until now; it was never on main or any other release branch. * SK-2967 backport internal + public release workflow fixes Internal releases (both modules) Version now comes from the module's own pom plus the commit SHA, via scripts/current_module_version.sh, instead of get-previous-tag. Tag lookup is repo-wide with no module awareness, so it stamped an unrelated v3 tag onto both flowvault and v2 builds (3.0.0-beta.13-dev.<sha>). A module's own pom is inherently per-module. Verified: flowvault 1.0.0-dev.<sha>, v2 2.1.1-dev.<sha>. internal-release.yml no longer fires on tag pushes. tags-ignore was '*.*', and Actions' glob '*' does not match '/', so slash tags like flowvault/v1.0.0 were never ignored - a public release tag also started an internal release, resolving to the wrong module. Now '**'. Public/beta releases Triggered by publishing a GitHub Release rather than a raw tag push, so the branch comes from target_commitish - the branch chosen in the release UI. It was previously guessed by matching a branch tip to the tagged commit, which failed once anything landed after the tag (re-runs never worked) and silently pushed to an unrelated branch when several shared a tip. Tags are <module>/v<semver>[-beta.N]; the prefix selects the module and is stripped, so Maven Central sees a plain semver. Malformed tags are rejected instead of publishing something unintended. beta-release.yml merged in: 'release' events cannot be filtered by tag pattern, so both files would fire on every release, and beta/public were already handled identically in every conditional. Kind is derived from the tag. Empty-commit guard: when the pom already holds the release version - the normal case when it is set before tagging - a bare git commit exits 1 and aborted the release. Now treated as success. dry-run input added so this path can be exercised without publishing; Maven Central is immutable. Verified with a real published Release (since deleted): correct module/version/branch, 383 tests, GPG signed, zero uploads. Merged with the base rather than overwriting it: the javadoc-skip added on flowvault-release/26.8.1 is kept for internal builds, but NOT applied to beta/public - Sonatype requires the -javadoc.jar and rejects bundles without one. That matches the intent stated in the base's own comment, which its code contradicted. * SK-2967 stage Maven Central releases instead of auto-publishing Sets autoPublish=false for both flowvault and v2. Deployments now upload and validate, then wait in the Central Portal as VALIDATED until someone clicks Publish - or Drop, to discard them. Maven Central is immutable: a published version can never be edited or removed, and the only remedy for a bad release is shipping another one. With autoPublish=true there was no point at which anything could be checked before that became permanent. Sonatype's validation only checks that required fields are present, not that they are correct. flowvault/pom.xml currently carries <description>Skyflow V3 SDK for the Java programming language</description> on an artifact named skyflow-flowvault-java - copy-paste from the v3 module. That passes validation and would have shipped permanently on the first release of a brand-new coordinate. Exactly what the staging step is for. Note this changes v2's behaviour too: its releases previously went live automatically once mvn deploy succeeded, and now need the extra click. * SK-2967 follow the v2 -> skyvault rename release.yml mapped the skyvault tag prefix to MODULE="v2", a directory that no longer exists - 'mvn -pl v2' would have failed outright. Both prefixes now map straight to their directory name. internal-release.yml already resolved to skyvault: that came from the base and survived the merge, so only release.yml carried the stale mapping. Also refreshed comments that still said v2. Tag examples like skyvault/v2.1.2 are unchanged and correct - the v2 there is the version 2.1.2, not the module. * SK-2967 add skyvault-release/* trigger for internal releases Gives skyvault the same per-module release branch flowvault already had, so both read the same way: flowvault-release/* and skyvault-release/*. release/* is kept as a legacy alias, still mapping to skyvault. Module resolution is now an explicit case with no catch-all. The previous if/else defaulted anything that was not flowvault-release/* to skyvault, which is exactly how a flowvault tag once ended up publishing skyvault - unrecognised refs silently became the wrong module. An unmatched branch now fails loudly, and the resolved module is logged. * [AUTOMATED] Private Release 3.0.0-beta.13-dev-ef9fa592 * SK-3037 add bulk tokenize and delete-tokens samples (#395) * SK-3026 update custom header naming convention * SK-3026 fix workfow * [AUTOMATED] Private Release 3.0.0-beta.13-dev-b05ef4fb * [AUTOMATED] Private Release 3.0.0-beta.13-dev-60859567 * [AUTOMATED] Private Release 3.0.0-beta.13-dev-e8e0e2d0 * [AUTOMATED] Private Release 3.0.0-beta.13-dev-eb82be1b * [AUTOMATED] Private Release 3.0.0-beta.13-dev-496c83a0 * [AUTOMATED] Private Release 3.0.0-beta.13-dev-5ddc5628 * [AUTOMATED] Private Release 3.0.0-beta.13-dev-e6552a0a * [AUTOMATED] Private Release 3.0.0-beta.13-dev-c804c748 * [AUTOMATED] Private Release 3.0.0-beta.13-dev-6ff46f02 * [AUTOMATED] Private Release 3.0.0-beta.13-dev-291b8206 * [AUTOMATED] Private Release 3.0.0-beta.13-dev-99612f55 * [AUTOMATED] Private Release 3.0.0-beta.13-dev-674f7b00 * [AUTOMATED] Private Release 3.0.0-beta.13-dev-068e293a * [AUTOMATED] Private Release 3.0.0-beta.13-dev-1af848a0 * [AUTOMATED] Private Release 3.0.0-beta.13-dev-821cc992 * [AUTOMATED] Private Release 3.0.0-beta.13-dev-610b8f21 * [AUTOMATED] Private Release 3.0.0-beta.13-dev-43f0ba69 * [AUTOMATED] Private Release 3.0.0-beta.13-dev-f9737826 * [AUTOMATED] Private Release 3.0.0-beta.13-dev-6ea42d7c * SK-2967 restore the [AUTOMATED] loop guard to stop the release recursion The internal release force-pushes its own version-bump commit, that push re-triggers the workflow, and it bumps and pushes again - roughly every 30 seconds. It ran ~60 times on this branch before being cancelled. The push uses PAT_ACTIONS, and PAT-authenticated pushes DO trigger workflows; GITHUB_TOKEN pushes deliberately do not. So the guard only becomes load-bearing once the PAT is wired up correctly - which is why the loop started the moment that was fixed, not before (while the secret resolved to empty, checkout failed and nothing could recurse). The guard existed on the v3 branch with a comment describing this exact failure mode, and was lost in the modularization. * Split READMEs per package and resolve flowvault README review (#396) * Split monolithic README into per-package docs for skyvault and flowvault Ports the README restructure from devesh/v2-flowvault-readmes onto this release branch, which already carries the v2 -> skyvault rename: - root README.md becomes a short landing page pointing at each package - skyvault/README.md holds the full skyflow-java documentation - flowvault/README.md documents the skyflow-flowvault-java bulk surface Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Address README review: self-contained flowvault docs, per-record error model Resolves review comments on the flowvault README: - Quickstart declared `VaultController vault` twice. The second line also called `skyflowClient.vault("<VAULT_ID>")`, which flowvault does not expose — its `vault()` takes no argument and always resolves to the first configured vault. Both fixed, and the single-vault behaviour is now stated. - Auth, Credentials, VaultConfig and error handling lived only in the skyvault README, so flowvault users had to switch documents to get started. flowvault now documents them inline: credential types and their setters, credential resolution order, bearer token generation, a full VaultConfig / Skyflow.builder() reference, timeout and retry resolution with defaults, and logging. Only the exotic token variants (context, scoped, signed) still point at skyvault. - Added a note that flowvault is a new SDK versioned independently, so a 1.x flowvault next to a 2.x skyvault does not read as a downgrade. In both the flowvault README and the root package table. - Rewrote Error Handling around flowvault's actual model: request-level SkyflowException versus per-record success/failure inside a call that returns normally, including the trap that a call where every record failed still does not throw. Documents index/httpCode/error/requestId per record, the per-operation summaries, consumption loops for both the one-level and two-level (tokenize) shapes, and the retry helpers. Also brings the API surface in line with this branch, which renamed several types after the README was first written: BulkInsertRequestRecord (was BulkInsertRecord), tableName (was table), UpsertOptions (was upsert/upsertType), TokenGroupRedactions (was BulkTokenGroupRedactions), Bulk*Options (was InsertOptions/TokenizeOptions/...), CustomHeaderKey .SkyflowAccountId/.RequestIdHeader, and the response shape, which is now a single `records` list rather than separate `success` and `errors` lists. Verified: all 20 Java snippets compile against the branch's classes, and every sample JSON response matches the real toString() output. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Document bulk batch size and concurrency configuration The flowvault README noted that bulk calls are split into batches sent concurrently, but never documented how to configure that. Add a "Batching and concurrency" section covering the per-operation env vars, their defaults and maximums, and how effective values are resolved. Values verified against Constants.java and the configure*ConcurrencyAndBatchSize methods in VaultController: batch size is min(value, max) with a warning-and- clamp above the max and a warning-and-default for invalid input; concurrency is additionally capped at ceil(itemCount / batchSize), so it never exceeds the number of batches to run. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> * [AUTOMATED] Private Release 3.0.0-beta.13-dev-2e606ceb * SK-2967 trim verbose comments in the release workflows Cuts the incident narratives down to the constraint each one exists to protect, 86 comment lines to 36. Every non-comment line is byte-identical to before - verified by stripping comments and blanks from both sides. Also removes a duplicated comment above the fixtures step that had become wrong: it described a glob-based implementation while the step uses a hardcoded module list. * [AUTOMATED] Private Release 3.0.0-beta.13-dev-18f8f1ba * SK-3026 update samples * [AUTOMATED] Private Release 3.0.0-beta.13-dev-ecf6b4be * SK-3037 run contract tests for flowvault, and gate on the public API only (#397) * [AUTOMATED] Private Release 3.0.0-beta.13-dev-962614b1 * SK-3026 remove unused tokens key in insert * [AUTOMATED] Private Release 3.0.0-beta.13-dev-dda2bace * SK-3026 fix tests * [AUTOMATED] Private Release 3.0.0-beta.13-dev-46cbffad * [AUTOMATED] Private Release 3.0.0-beta.13-dev-7e97883a * SK-3026 added tokens support * [AUTOMATED] Private Release 3.0.0-beta.13-dev-7c0fb7be * [AUTOMATED] Private Release 3.0.0-beta.13-dev-c7311820 --------- Co-authored-by: skyflow-bharti <skyflow-bharti@users.noreply.github.com> Co-authored-by: saileshwar-skyflow <156889717+saileshwar-skyflow@users.noreply.github.com> Co-authored-by: Devesh-Skyflow <devesh.bhardwaj@skyflow.com> Co-authored-by: saileshwar-skyflow <saileshwar-skyflow@users.noreply.github.com> Co-authored-by: Devesh-Skyflow <Devesh-Skyflow@users.noreply.github.com> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Splits the monolithic README into per-package docs and resolves Shruti's review comments on the flowvault README.
This release branch only had the monolithic root
README.md, so the first commit ports the split over fromdevesh/v2-flowvault-readmesand the second is the review response. Reviewing commit-by-commit keeps the diff readable.Commit 1 — the split
README.mdbecomes a short landing page pointing at each packageskyvault/README.mdholds the fullskyflow-javadocumentationflowvault/README.mddocuments theskyflow-flowvault-javabulk surfaceCommit 2 — review comments
1. Quickstart declared the same variable twice. Real, and worse than a duplicate: the second line called
skyflowClient.vault("<VAULT_ID>"), an overload flowvault does not have. ItsSkyflow.vault()takes no argument and always resolves to the first configured vault. Both lines collapsed into one, and the single-vault behaviour is now stated explicitly.2. Auth,
Credentials,VaultConfigand error handling only lived in the skyvault README. flowvault now documents them inline — credential types and their setters, the config → client →SKYFLOW_CREDENTIALSresolution order, bearer token generation, fullVaultConfigandSkyflow.builder()reference tables, timeout/retry resolution with defaults, and logging. Only the exotic token variants (context, scoped, signed) still point at skyvault.3. Independent versioning note. Added to the flowvault README header and the root package table: skyvault is 2.x, flowvault starts at 1.0.0, and a lower number is a first release rather than a downgrade.
4. Per-record success/failure reporting. Error Handling rewritten around flowvault's actual model — request-level
SkyflowExceptionversus per-record results inside a call that returns normally, including the trap that a call where every record failed still does not throw. Coversindex/httpCode/error/requestIdper record, the four per-operation summary types, consumption loops for both the flat shape and tokenize's two-level shape, and the retry helpers.Also: API surface brought in line with this branch
The README was written before several types were renamed here, so left as-is it documented an API that no longer exists:
BulkInsertRecordBulkInsertRequestRecord.table(...).tableName(...)upsert/upsertTypefieldsUpsertOptionsBulkTokenGroupRedactionsTokenGroupRedactionsInsertOptions/TokenizeOptions/ …BulkInsertOptions/BulkTokenizeOptions/ …CustomHeaderKey.SkyflowAccountID/.RequestIDHeader.SkyflowAccountId/.RequestIdHeadersuccess+errorslistsrecordslistVerification
commonandflowvault, extracted all 20 Java snippets from the README and compiled them against this branch's classes — clean.toString()output field-for-field, including null handling and field order.Out of scope, found along the way
Not touched in this PR:
flowvault/samples/src/main/java/com/example/vault/CustomHeaderExample.java:94does not compile — passesInsertOptionswhereBulkInsertOptionsis required. The samples are not in the reactor (pom.xmllists onlycommon,skyvault,flowvault), so CI never builds them.flowvault/samples/README.mdis a stale copy of the old skyvault samples README — it documents Detokenize/Get/Insert/InvokeConnection, none of which are the flowvault bulk samples next to it.🤖 Generated with Claude Code