feat: Add shared storage and lifecycle coordination

[M03ED]

Summary by CodeRabbit

• New Features

  • Added configurable node creation from saved configurations or registries.
  • Added shared storage support for queued user synchronization across workers and hosts.
  • Added lifecycle coordination for node starts, stops, and updates, including status tracking and lease handling.
  • Added in-memory registries, synchronization stores, and lifecycle coordinators.

• Documentation

  • Documented shared storage, lifecycle coordination, and registry-based node configuration.

• Bug Fixes

  • Improved synchronization reliability through exclusive claims, acknowledgements, retries, and lease expiry handling.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7dc4cea3-0625-4ffc-85b3-3b1fd5ac977b

📥 Commits

Reviewing files that changed from the base of the PR and between 1167859 and c82f1d5.

📒 Files selected for processing (7)

• PasarGuardNodeBridge/__init__.py
• PasarGuardNodeBridge/controller.py
• PasarGuardNodeBridge/grpclib.py
• PasarGuardNodeBridge/rest.py
• PasarGuardNodeBridge/storage.py
• README.md
• tests/test_storage.py

---

Walkthrough

The bridge adds in-memory and protocol-based storage for node configs, queued user synchronization, and lifecycle leases. Controllers use leased claims and coordinated updates, REST/gRPC nodes report lifecycle states, and public helpers support registry-backed node creation.

Changes

Shared storage and lifecycle coordination

Layer / File(s)	Summary
Storage contracts and in-memory primitives PasarGuardNodeBridge/storage.py, tests/test_storage.py	Adds node configuration, registry, user-sync, and lifecycle contracts with in-memory implementations and tests for persistence, claiming, deduplication, requeueing, and lease expiry.
Controller storage-backed synchronization PasarGuardNodeBridge/controller.py	Moves user synchronization to leased store claims and centralizes lifecycle-coordinated node, core, and geofile updates.
REST and gRPC lifecycle integration PasarGuardNodeBridge/rest.py, PasarGuardNodeBridge/grpclib.py	Wraps node start and stop flows with lifecycle lease acquisition and success or failure state reporting.
Registry-backed node configuration API PasarGuardNodeBridge/__init__.py, README.md	Adds configuration save/load and node-construction helpers, exports storage symbols, and documents shared stores and lifecycle coordination.

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

Sequence Diagram(s)

sequenceDiagram
  participant Controller
  participant UserSyncStore
  participant NodeLifecycleCoordinator
  participant NodeAPI
  Controller->>UserSyncStore: claim pending users
  Controller->>NodeLifecycleCoordinator: acquire update lease
  Controller->>NodeAPI: send coordinated update
  NodeAPI-->>Controller: return update result
  Controller->>UserSyncStore: acknowledge or requeue users
  Controller->>NodeLifecycleCoordinator: release update lease

Loading

Possibly related PRs

• PasarGuard/node_bridge_py#11: Both changes modify controller user-sync worker behavior, including chunking and retry/requeue handling.

Poem

A bunny hops through queues of mail,
With leased paws that never fail.
Node states bloom from stop to start,
Old claims hop back when workers part.
Configs rest safely in their store—
Thump, thump, and sync some more!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding shared storage and lifecycle coordination.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch shared-storage

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}