Skip to content

refactor(server-nestjs): unify client-service vocabulary to get/create/ensure - #2832

Open
shikanime wants to merge 3 commits into
mainfrom
refactor/ensure-vocabulary
Open

refactor(server-nestjs): unify client-service vocabulary to get/create/ensure#2832
shikanime wants to merge 3 commits into
mainfrom
refactor/ensure-vocabulary

Conversation

@shikanime

@shikanime shikanime commented Oct 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Quoi

Renommage mécanique (aucun changement de comportement) du vocabulaire des
services clients dans apps/server-nestjs vers trois verbes : get*
(lecture), create* (écriture non idempotente), ensure* (converge vers
l'état désiré et retourne le nouvel état).

  • getOrCreate* renommés ensure* (entités) dans gitlab, keycloak,
    observability ; les lookups d'URL dérivée conservent la forme
    converge-puis-retourne (ensureProjectGroupPublicUrl & co) puisque le
    groupe est créé par effet de bord
  • upsert* des services clients renommés ensure* (custom-attributes /
    repo / user gitlab ; sys-policies / approle / identity / kv vault) ;
    nexus et registry utilisaient déjà ensure
  • wrappers cron vault renommés reconcile* pour libérer ensureZone /
    ensureProject au profit des méthodes publiques de convergence
  • couche DB intacte : prisma.upsert et upsert* de queries-utils
    gardent le vocabulaire Prisma ; types miroirs Upsert*Request
    inchangés (formes d'API externes) ; upsertUser keycloak-jwt rétabli
    (couche DB)

Suit la convention déjà établie par les helpers ensure({ create, reload, onCollision }) présents dans cinq modules.

Pourquoi

Un vocabulaire uniforme rend la sémantique lisible à l'appel : ensure
garantit l'état (crée ou réutilise), get lit, create crée sans
idempotence. Discussion née de la review de #2807.

Vérification

  • nest build (le verrou tsc du dépôt) : vert sur le SHA de head
  • vitest run (suite complète server-nestjs) : 764 verts / 69 skippés / 0 échec
  • eslint sur les fichiers adaptés : 0 signalement

Références

@shikanime
shikanime requested a review from a team as a code owner October 7, 2026 14:58
@github-actions github-actions Bot added the built label Oct 7, 2026
StephaneTrebel
StephaneTrebel previously approved these changes Oct 7, 2026
View reviewed changes

@StephaneTrebel StephaneTrebel left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Les renommages sont cohérents avec l’intention : les opérations de convergence portent désormais le préfixe ensure, tandis que la réconciliation périodique reste distinguée et les contrats externes/DB sont préservés. Le diff est mécanique ; tests, lint et builds passent, sans finding à signaler (sans ledger).

@shikanime
shikanime force-pushed the refactor/ensure-vocabulary branch 3 times, most recently from cd7cce1 to bfd27b3 Compare October 7, 2026 15:48
shikanime added a commit that referenced this pull request Oct 7, 2026
@shikanime @yorha-operator William Phetsinorath
docs: add client-service verb vocabulary to cpn-code-authoring
b52d21c 
Ratifies the get/create/ensure/reconcile vocabulary and module-local
ensure() util routing from #2832.

Co-authored-by: Automata <automata@shikanime.studio>
@shikanime shikanime mentioned this pull request Oct 7, 2026
Open
@shikanime shikanime self-assigned this Oct 8, 2026
@shikanime shikanime added this to the 9.28.0 milestone Oct 8, 2026
shikanime added a commit that referenced this pull request Oct 8, 2026
@shikanime @yorha-operator
docs: add client-service verb vocabulary to cpn-code-authoring
dbbbb31 
Ratifies the get/create/ensure/reconcile vocabulary and module-local
ensure() util routing from #2832.

Co-authored-by: Automata <automata@shikanime.studio>
shikanime added a commit that referenced this pull request Oct 8, 2026
@shikanime
docs: add client-service verb vocabulary to cpn-code-authoring
9ac9418 
Ratifies the get/create/ensure/reconcile vocabulary and module-local
ensure() util routing from #2832.

Co-authored-by: Automata <automata@shikanime.studio>

Signed-off-by: Shikanime Deva <22115108+shikanime@users.noreply.github.com>
@shikanime
shikanime force-pushed the refactor/ensure-vocabulary branch from bfd27b3 to 28153e4 Compare October 8, 2026 12:25
shikanime added a commit that referenced this pull request Oct 8, 2026
@shikanime
docs: add client-service verb vocabulary to cpn-code-authoring
3482eae 
Ratifies the get/create/ensure/reconcile vocabulary and module-local
ensure() util routing from #2832.

Co-authored-by: Automata <automata@shikanime.studio>

Signed-off-by: Shikanime Deva <22115108+shikanime@users.noreply.github.com>
StephaneTrebel
StephaneTrebel reviewed Oct 9, 2026
View reviewed changes
Comment thread apps/server-nestjs/src/modules/gitlab/gitlab-client.service.ts
StephaneTrebel
StephaneTrebel previously requested changes Oct 9, 2026
View reviewed changes

@StephaneTrebel StephaneTrebel left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

🔴 Le renommage laisse un appel upsertUser non migré, ce qui fait échouer la compilation Nest et les checks de CI. Voir le commentaire inline ; merci de corriger les consommateurs puis de relancer les checks.

@shikanime
shikanime force-pushed the refactor/ensure-vocabulary branch from 28153e4 to 9aba574 Compare October 9, 2026 08:52
@shikanime
refactor(server-nestjs): unify client-service vocabulary to get/creat…
06597c2 
…e/ensure

Rename-only sweep over apps/server-nestjs so every external-system client
service exposes three verbs: get* (read), create* (non-idempotent write),
ensure* (converge to desired state and return the new state).

- getOrCreate* renamed to ensure* (entity-returning) across gitlab,
  keycloak, observability; derived-URL lookups keep their
  converge-then-return shape (ensureProjectGroupPublicUrl and siblings),
  since the group is created as a side effect
- client-service upsert* renamed to ensure* (gitlab
  custom-attributes/repo/user, vault sys-policies/approle/identity/kv);
  nexus and registry wrappers already used ensure
- vault cron wrappers renamed to reconcile* to free ensureZone and
  ensureProject for the public converge methods
- DB layer untouched: prisma .upsert calls and queries-utils upsert* keep
  Prisma vocabulary; Upsert*Request mirror types unchanged (external API
  shapes); keycloak-jwt upsertUser reverted (DB layer)

No behavior change. tsc/vitest/eslint green on the touched modules.

Co-authored-by: Automata <automata@shikanime.studio>
Signed-off-by: William Phetsinorath <william.phetsinorath-open@interieur.gouv.fr>
Change-Id: If6d5c413a557b4705b1782182ccda1b36a6a6964

Signed-off-by: Shikanime Deva <22115108+shikanime@users.noreply.github.com>
@shikanime
refactor(server-nestjs): route hand-rolled race recovery through modu…
522986b 
…le ensure utils

Every ensure* method now goes through its module's ensure({ create, reload,
onCollision }) util; no hand-rolled get-or-create bodies remain in client
services.

- gitlab createGroup/createSubGroup/ensureRepo/createUser race catches
  rewritten as ensure() calls; createUser is now the raw non-idempotent
  write and ensureUser owns convergence (vocabulary-true split)
- createGroup and createSubGroup shared path-keyed attribute blocks
  deduplicated into setManagedGroupAttributesByPath
- getUserByEmail returns undefined instead of null to match the util
  contract and sibling getters
- custom-attribute ensure* log verbs aligned with the vocabulary

Keycloak, nexus, registry and sonarqube already routed through their
module utils; registry keep status-code handling local.

No behavior change. tsc error-set identical to main, vitest 106/106 on
gitlab, eslint clean.

Co-authored-by: Automata <automata@shikanime.studio>
Signed-off-by: William Phetsinorath <william.phetsinorath-open@interieur.gouv.fr>
Change-Id: Ie4ed81c6c5c1ebffc0a453fcfec803866a6a6964

Signed-off-by: Shikanime Deva <22115108+shikanime@users.noreply.github.com>
@shikanime
shikanime force-pushed the refactor/ensure-vocabulary branch from 9aba574 to da73769 Compare October 9, 2026 09:02
@shikanime @yorha-operator
fix(server-nestjs): adapt adminRole sync to the ensure vocabulary
bd9d20b 
The adminRole consumer landed on main while this branch was in review; it
called upsertUser and the admin-role specs mocked the old get-or-create
names, which broke the merge build. Repoint the caller to ensureUser and
refresh the spec mocks.

Co-authored-by: Automata <automata@shikanime.studio>
Signed-off-by: William Phetsinorath <william.phetsinorath-open@interieur.gouv.fr>
Change-Id: I44a3392ced9fd536b0d1a723711fe5326a6a6964
@shikanime
shikanime force-pushed the refactor/ensure-vocabulary branch from da73769 to bd9d20b Compare October 9, 2026 09:34
@cloud-pi-native-sonarqube

cloud-pi-native-sonarqube Bot commented Oct 9, 2026

Copy link
Copy Markdown

Passed Quality Gate passed

Issues

Measures

Project ID: cloud-pi-native_console_AYsa46O31ebDtzs-pYyZ

View in SonarQube

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@StephaneTrebel StephaneTrebel Awaiting requested review from StephaneTrebel

At least 1 approving review is required to merge this pull request.

Assignees

@shikanime shikanime

Labels

built

Projects

None yet

Milestone

9.28.0

Development

Successfully merging this pull request may close these issues.

2 participants

@shikanime @StephaneTrebel