Skip to content

feat: versioned (CAS) user writes in basic lock script - #15749

Merged
moabu merged 25 commits into
mainfrom
feat/basic-lock-cas
Nov 19, 2026
Merged

moabu merged 25 commits into
mainfrom
feat/basic-lock-cas

Conversation

@mo-auto

@mo-auto mo-auto commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

Follow-up to #15743 (merged).

Closes residual races in the basic-lock script: plain merge had no compare-and-set, so concurrent lock/unlock/counter/admin writes could overwrite each other.

  • jans-orm
    • updateWithVersion with a null version matches only entries with no stored version (SQL IS NULL, LDAP (!(attr=*))); existing rows need no backfill.
    • merge on a @Version entity writes with CAS on the version it read, re-reads on conflict, and on retry applies only the attributes the first read changed. After 10 conflicts it throws VersionMismatchException and writes nothing. Backends without versioned updates keep the plain write.
  • schema/model: jansVersion added to jansPerson; @Version on auth-server User (config-api, fido2), SCIM ScimCustomPerson and User, Casa BasePerson, Jans Link User. Equality unchanged; JSON output unchanged (@JsonIgnore on auth-server User).
  • script: failed-login count and lock are one CAS (registerFailedLogin); lock marker is locked:<ms>:<version> and unlock requires that version, never falling back to an unconditional write. A failure right after unlock uses the same counter path.
  • upgrade
    • Docker/Kubernetes: persistence loader adds the column.
    • VM: install.py -upgrade does not; run the ALTER TABLE from the MySQL/PgSQL ops docs before starting new services. Manual UPDATEs on jansPerson must advance jansVersion.
    • LDAP: setup no longer installs LDAP; custom LDAP deployments must add jansVersion to the jansPerson object class.

Tests: ORM unit tests (73), auth common UserServiceTest; Jython fake-store harness for lock, expiry unlock, admin write after lock, admin disable racing lock, parallel failures, admin edit racing unlock, threshold reset race, no-CAS fallback. Null-version predicate not run against live SQL/LDAP.

mo-auto and others added 8 commits November 18, 2026 16:16
Persist a locked:<millis> marker in the invalid-login count attribute and
re-check it right before unlocking. Admin-disabled accounts stayed
unlockable via an expired cache record, and a stale cache read could
undo a concurrent re-lock.

Co-authored-by: Mohammad Abudayyeh <47318409+moabu@users.noreply.github.com>
Signed-off-by: moauto <54212639+mo-auto@users.noreply.github.com>
Unlock only when updatedAt still matches the lock write, so an admin
disable during or after a lock survives a stale marker. Counter writes
no longer overwrite a concurrent lock marker.

Co-authored-by: Mohammad Abudayyeh <47318409+moabu@users.noreply.github.com>
Signed-off-by: moauto <54212639+mo-auto@users.noreply.github.com>
Write the lock with merge and updatedAt equal to the marker time, so
unlock needs an exact match instead of a 5 s slack that let a quick
admin change through and a slow write lock forever.

Co-authored-by: Mohammad Abudayyeh <47318409+moabu@users.noreply.github.com>
Signed-off-by: moauto <54212639+mo-auto@users.noreply.github.com>
updateWithVersion with a null version expects the version attribute
to be absent, so rows written before their class got @Version can
use versioned updates without a backfill.

Co-authored-by: Mohammad Abudayyeh <47318409+moabu@users.noreply.github.com>
Signed-off-by: moauto <54212639+mo-auto@users.noreply.github.com>
Adds jansVersion to jansPerson and @Version to the auth-server and
SCIM user entities, so every user merge bumps it. VM installs must
add the column before upgrading (documented in database ops).

Co-authored-by: Mohammad Abudayyeh <47318409+moabu@users.noreply.github.com>
Signed-off-by: moauto <54212639+mo-auto@users.noreply.github.com>
Lock, unlock and counter writes are compare-and-set on jansVersion and
re-decide on a mismatch, closing the races left by plain merge. The
lock marker records the version it writes so unlock rejects any later
change. Falls back to merge on backends without versioned updates.

Co-authored-by: Mohammad Abudayyeh <47318409+moabu@users.noreply.github.com>
Signed-off-by: moauto <54212639+mo-auto@users.noreply.github.com>
config-api user JSON names the field status, not jansStatus: create
ignored it and reads returned None, failing both lock behavior tests.

Co-authored-by: Mohammad Abudayyeh <47318409+moabu@users.noreply.github.com>
Signed-off-by: moauto <54212639+mo-auto@users.noreply.github.com>
Lock lasts 30 s in CI so the test can wait it out and log in again,
exercising the marker and updatedAt round-trip on a real database.

Co-authored-by: Mohammad Abudayyeh <47318409+moabu@users.noreply.github.com>
Signed-off-by: moauto <54212639+mo-auto@users.noreply.github.com>

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.

Tip: disable this comment in your organization's Code Review settings.

@mo-auto

mo-auto commented Nov 18, 2026 •

Copy link
Copy Markdown
Member Author

✅ Snyk checks have passed. No issues have been found so far.

Status Scan Engine Critical High Medium Low Total (0)
✅ Open Source Security 0 0 0 0 0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • Resume reviews
  • Trigger review

No actionable comments were generated in the recent review.

Walkthrough

The changes add jansVersion support to person models and persistence, including conditional updates when no version is stored. The account-lock script uses versioned lock markers and guarded unlocks. Documentation and CI behavior checks cover version setup and account-lock behavior.

Changes: Account Locking and Versioned Persistence

Layer / File(s) Summary
Person version contract
jans-auth-server/.../common/User.java, jans-scim/model/.../ScimCustomPerson.java, jans-casa/.../BasePerson.java, jans-link/.../User.java, jans-scim/service/.../User.java, jans-linux-setup/.../jans_schema.json, docs/janssen-server/reference/database/*-ops.md
Person models map version fields to jansVersion, and the schema permits the attribute. MySQL and PostgreSQL guides document column setup and manual version increments.
Nullable version updates
jans-orm/core/src/main/java/.../PersistenceEntryManager.java, jans-orm/core/src/main/java/.../BaseEntryManager.java, jans-orm/{ldap,sql}/src/main/java/.../*OperationServiceImpl.java, jans-orm/core/src/test/java/.../*
The ORM supports conditional updates when the expected version is null, retries versioned merges after conflicts, and throws VersionMismatchException after repeated conflicts. Tests cover these cases and the version values used.
Version-checked account locking
docs/script-catalog/person_authentication/basic-lock-account-external-authenticator/BasicLockAccountExternalAuthenticator.py, docs/script-catalog/person_authentication/other/basic.lock.account/README.md
The script stores a timestamp and version in lock markers. It retries guarded updates and unlocks only when the marker and version still match.
Account-lock behavior checks
automation/ci/script_catalog/aio.py, automation/ci/script_catalog/manifest.py, automation/ci/script_catalog/run.py
The AIO helper updates user status. Behavior checks cover lock expiration and disabled accounts, using a configured 30-second lock duration.

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix

Possibly related issues

Possibly related PRs

Suggested labels: kind-bug

Merge Risk: Moderate · previous review 4f7f8

The change adds version-checked account locking, but several concurrency and upgrade gaps remain open. A stale ordinary write could undo a lock, and LDAP deployments need the schema updated. Address or explicitly accept these before merging.

Pre-merge checks: Passed 3 · Inconclusive 1

Failed Failed checks: 1 inconclusive

Check name Status Explanation Resolution
Description check Inconclusive The description covers the core changes: jans-orm null-version CAS, merge retry behavior, schema and model @Version additions, the basic-lock script changes, and upgrade steps for Docker/Kubernetes, V… Add a proper target issue reference (for example, 'closes #' pointing to a real issue with a clear problem statement) instead of the auto-created #15750, or state why no issue applies. Tick the template checkboxes that now apply (sta…
Passed Passed checks: 3 passed

Check name Status Explanation
Title check Passed The title "feat: versioned (CAS) user writes in basic lock script" matches the main change. The PR adds compare-and-set versioning to user writes in the basic-lock script, backed by jansVersion schema…
Linked Issues check Passed [#15750] is the only active directly linked issue. It is open and not contextual. Its body is autocreated and states no acceptance criteria, so its title defines the coding requirement: versioned (CAS…
Out of Scope Changes check Passed Each changed area maps to the CAS objective of [#15750], directly or as support:
- Core mechanism: jans-orm BaseEntryManager, SqlOperationServiceImpl, LdapOperationServiceImpl, and PersistenceEntryMan…
Full details: Title check

Explanation

The title "feat: versioned (CAS) user writes in basic lock script" matches the main change. The PR adds compare-and-set versioning to user writes in the basic-lock script, backed by jansVersion schema, ORM null-version handling, and @Version model changes. The title is short, specific, and follows the conventional commit prefix style. It does not cover the schema, ORM, or documentation changes, which is acceptable.

Full details: Linked Issues check

Explanation

[#15750] is the only active directly linked issue. It is open and not contextual. Its body is autocreated and states no acceptance criteria, so its title defines the coding requirement: versioned (CAS) user writes in the basic lock script.

Implementation at the reviewed head:

  • jans-orm: updateWithVersion accepts a null expected version. SQL uses IS NULL (SqlOperationServiceImpl). LDAP uses an absent-attribute filter (LdapOperationServiceImpl). BaseEntryManager.merge uses CAS with bounded retries and throws VersionMismatchException at the limit.
  • Schema and models: jansVersion is permitted on jansPerson. @Version is present on auth-server User (common), ScimCustomPerson, Casa BasePerson, jans-link User, and SCIM User. Version metadata is excluded from equals and hashCode. I read Casa BasePerson and jans-link User at head. Both carry @Version with ignoreDuringUpdate=true.
  • Script: BasicLockAccountExternalAuthenticator.py uses updateWithVersion for lock, unlock, counter, and failed-login writes. It re-reads and re-checks on VersionMismatchException. The lock marker is locked:<ms>:<version>. Unlock requires the expected marker and matching version. It falls back to merge only when versioned updates are unsupported, and not during unlock.

The PR description states a gap: Casa and jans-link person classes lack @Version. The code at head contradicts this for both classes, so the description is stale on this point. The code is treated as authoritative.

Tests reported by the author: ORM BaseEntryManagerVersionTest and auth common UserServiceTest pass. The Jython fake-store harness covers the lock race cases. These tests were not re-run in this assessment. The null-version predicate was not run against live SQL or LDAP, so backend behavior is confirmed only by source reading.

No coding requirement of [#15750] is unmet on the evidence available.

Full details: Out of Scope Changes check

Explanation

Each changed area maps to the CAS objective of [#15750], directly or as support:

  • Core mechanism: jans-orm BaseEntryManager, SqlOperationServiceImpl, LdapOperationServiceImpl, and PersistenceEntryManager docs implement the null-version CAS predicate and versioned merge.
  • Version carriers: User (auth common), ScimCustomPerson, Casa BasePerson, jans-link User, SCIM User. These add jansVersion mapping so that CAS checks on their writes can detect changes.
  • Schema: jans_schema.json permits jansVersion on jansPerson.
  • Script and docs: BasicLockAccountExternalAuthenticator.py, the basic.lock.account README, and the MySQL and PgSQL ops docs describe the lock behavior, the column, and the upgrade step.
  • Tests and CI: BaseEntryManagerVersionTest, FakeVersionEntryManager, and VersionTestFixtures support the ORM tests. aio.py, run.py, and manifest.py change the basic_lock behavior tests and the BASIC_LOCK_SECONDS expiry.

The PR head includes three commits from #15743, which the PR description names as a dependency. Their content was not separately assessed. The changed areas above cover the files in the summary. No changed file lacks a concrete connection to the objective.

Full details: Description check

Explanation

The description covers the core changes: jans-orm null-version CAS, merge retry behavior, schema and model @Version additions, the basic-lock script changes, and upgrade steps for Docker/Kubernetes, VM, and LDAP. It lists tests run and the known gap (null-version predicate not run against live SQL/LDAP). It links a follow-up to an earlier merged PR and cites a closes reference. However, the template's 'Target issue' is not clearly linked: 'closes' is absent, and the objectives note the only linked issue (#15750) was auto-created with no requested outcome. The template's 'Implementation Details' section is effectively covered by the bullets, but the 'Prepare' checklist and the required docs-only commit confirmation checkbox are not visibly completed. The 'Test and Document' checkboxes are not marked, and the docs checkbox ('I confirm that there is no impact on the docs') conflicts with the docs changes the PR itself makes.

Resolution

Add a proper target issue reference (for example, 'closes #<issue>' pointing to a real issue with a clear problem statement) instead of the auto-created #15750, or state why no issue applies. Tick the template checkboxes that now apply (static analysis, unit/integration tests, docs updated) and confirm the Prepare items. Remove or correct the 'no impact on the docs' checkbox, because this PR updates docs/janssen-server/reference/database/mysql-ops.md, pgsql-ops.md, and the basic.lock.account README. Confirm that commits starting with 'docs:' exist, since the template states the PR will not be merged without them.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: bedc94ac-3572-4c18-9800-5930859c6fa7
Commits

Reviewing files that changed from the base of the PR and between 44a93b0 and 4f7f8a1.

Files selected for processing: 3

  • jans-orm/core/src/main/java/io/jans/orm/PersistenceEntryManager.java
  • jans-orm/core/src/main/java/io/jans/orm/impl/BaseEntryManager.java
  • jans-orm/core/src/test/java/io/jans/orm/impl/BaseEntryManagerVersionTest.java

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 0 remain after this review.

@mo-auto mo-auto added area-CI Issue or changes required in automatic builds or CI infrastructure area-documentation Documentation needs to change as part of issue or PR comp-docs Touching folder /docs comp-jans-auth-server Component affected by issue or PR comp-jans-linux-setup Component affected by issue or PR comp-jans-orm Component affected by issue or PR comp-jans-scim Component affected by issue or PR kind-feature Issue or PR is a new feature request labels Nov 18, 2026
@mo-auto

mo-auto commented Nov 18, 2026

Copy link
Copy Markdown
Member Author

Error: Hi @mo-auto, You did not reference an open issue in your PR. I attempted to create an issue for you.
Please update that issues' title and body and make sure I correctly referenced it in the above PRs body.

The unconditional write after repeated conflicts could store a version a
concurrent writer also stored, so a lock and an admin write became
indistinguishable to unlock. merge now throws VersionMismatchException
after 10 conflicts and writes nothing.

Co-authored-by: Mohammad Abudayyeh <47318409+moabu@users.noreply.github.com>
Signed-off-by: moauto <54212639+mo-auto@users.noreply.github.com>
coderabbitai[bot]
coderabbitai Bot previously approved these changes Nov 19, 2026
Co-authored-by: Mohammad Abudayyeh <47318409+moabu@users.noreply.github.com>
Signed-off-by: moauto <54212639+mo-auto@users.noreply.github.com>
Co-authored-by: Mohammad Abudayyeh <47318409+moabu@users.noreply.github.com>
Signed-off-by: moauto <54212639+mo-auto@users.noreply.github.com>
…at/basic-lock-cas

Signed-off-by: moauto <54212639+mo-auto@users.noreply.github.com>

# Conflicts:
#	docs/script-catalog/person_authentication/basic-lock-account-external-authenticator/BasicLockAccountExternalAuthenticator.py
#	docs/script-catalog/person_authentication/other/basic.lock.account/README.md
@yurem
yurem temporarily deployed to integration-tests November 19, 2026 13:31 — with GitHub Actions Inactive
@sonarqubecloud

Copy link
Copy Markdown

@sonarqubecloud

Copy link
Copy Markdown

@sonarqubecloud

Copy link
Copy Markdown

@sonarqubecloud

Copy link
Copy Markdown

@sonarqubecloud

Copy link
Copy Markdown

@sonarqubecloud

Copy link
Copy Markdown

Quality Gate Passed Quality Gate passed for 'Jans authentication server parent'

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

@moabu
moabu merged commit 65e934a into main Nov 19, 2026
31 of 32 checks passed
@moabu
moabu deleted the feat/basic-lock-cas branch November 19, 2026 14:14

This branch was previously deployed

1 inactive deployment
integration-tests — f3115e95 Deployed Nov 19, 2026 by yurem via integration (MYSQL) #1719
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area-CI Issue or changes required in automatic builds or CI infrastructure area-documentation Documentation needs to change as part of issue or PR comp-docs Touching folder /docs comp-jans-auth-server Component affected by issue or PR comp-jans-casa Touching folder /jans-casa comp-jans-link Touching folder /jans-link comp-jans-linux-setup Component affected by issue or PR comp-jans-orm Component affected by issue or PR comp-jans-scim Component affected by issue or PR kind-bug Issue or PR is a bug in existing functionality kind-feature Issue or PR is a new feature request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants