Antigravity
711480f8f6
This pull request introduces the dedicated containerized infrastructure and configuration for deploying NexusReader's beta version in the Test environment. ### Summary of Changes 1. **Docker Infrastructure & Secrets**: - **`docker-compose.test.yml`**: Configured dedicated database and auxiliary services (PostgreSQL 17, Qdrant, Neo4j) on isolated, non-standard ports to ensure zero conflict with the existing server configurations. - **`.env.test.template`**: Provided an environment variable template showing required setups, including mandatory database passwords, API keys, and admin custom passwords. - **`.gitignore`**: Excluded local `.env` files to prevent accidental commits of production or staging secrets. 2. **Database Hardening**: - Configured Neo4j with basic authentication (`IDriver` instantiation uses basic auth when credentials are provided in configuration). - Configured PostgreSQL to use mandatory authentication. - Configured the admin seeder (`DbInitializer.cs`) to dynamically use `NEXUS_ADMIN_PASSWORD` from environment variables, falling back to a default password in local Development only. 3. **Feature-Flagged Restrictions**: - **`appsettings.Test.json`**: Implemented `Features:AllowRegistration` and `Features:AllowPasswordReset` flags set to `false`. - **Middleware Enforcement (`Program.cs`)**: Intercepts requests to `/identity/register` and `/identity/forgotPassword` (and their MVC/form variations) and rejects them with a `403 Forbidden` response in restricted environments. - **OAuth Provisioning Guard (`Program.cs`)**: Blocks new account provisioning via Google OAuth callback by checking the `Features:AllowRegistration` configuration, redirecting users to the login page with a descriptive error. - **UI Protection (`Login.razor`, `Register.razor`)**: Conditionally hides registration/password reset links and intercepts manual navigation attempts to `/account/register` by redirecting to login with a warning. --------- Co-authored-by: Marek Jasiński <jasins.marek@gmail.com> Reviewed-on: #56 Co-authored-by: Antigravity <antigravity@google.com> Co-committed-by: Antigravity <antigravity@google.com>
4.3 KiB
4.3 KiB
name, description
| name | description |
|---|---|
| nexus-code-review | Code Review Checklist and Standards for NexusReader SaaS |
NexusReader Code Review Standards
When conducting or receiving a code review for NexusReader, ensure the implementation adheres to the following critical architectural and performance standards:
1. Architectural Boundaries (CQRS & Blazor Hybrid)
- Client vs. Server Execution: MediatR handlers that depend on server-side infrastructure (
AppDbContext,IHubContext, secrets) MUST NOT be executed directly from client environments (WASM/MAUI). - Dependency Leakage: Ensure
NexusReader.Web.Client(WASM) does not referenceNexusReader.Infrastructureif the infrastructure requiresMicrosoft.AspNetCore.Appframework references. - SignalR Bridges: Client-initiated state changes should be sent via SignalR
SendAsyncto a server Hub, which then dispatches the internalMediatRcommand.
2. Event Handling & Debouncing
- High-Frequency UI Events: UI actions like scrolling, resizing, or typing must be debounced.
- Trailing-Edge Debounce: Use a
CancellationTokenSourceandTask.Delayto ensure the last event in a rapid sequence is executed. Do not use simple time-window drops, as they result in lost final states. - Async Void: Ensure UI event handlers do not use
async voidunless they are top-level framework event bindings, and even then, they must catch all exceptions.
3. SignalR & Real-Time Contexts
- Authentication Context: Do not rely on
IHttpContextAccessorinside MediatR handlers triggered by SignalR Hubs. UseContext.UserIdentifierdirectly from the Hub and pass it as a command parameter. - Connection State: Always check
HubConnection.State == HubConnectionState.Connectedbefore attempting to send messages from the client. - Targeted Broadcasting: Use SignalR
Groups(e.g.,$"User_{userId}") to broadcast updates only to the devices owned by the relevant user.
4. Performance & Scalability
- Database Write Contention: High-frequency telemetry (like reading progress) should ideally be batched or cached in-memory before writing to SQL, unless real-time persistence is strictly required.
- Memory Leaks: Ensure all components and services that subscribe to events (e.g.,
OnProgressReceived, JS Observers) implementIDisposableorIAsyncDisposableand properly unsubscribe.
5. Standard Nexus Guidelines
- Result Pattern: Ensure all application logic returns
ResultorResult<T>via FluentResults. No exceptions for control flow. - AI Prompts: Ensure changes to AI logic do not bypass the
PromptRegistryor token estimation limits defined inAiSettings.
6. Code Review Comments
6.1 Posting Comments
- Code-Linked Comments: Every review comment must be anchored to a specific file and line range using the Gitea inline comment API (
path+new_line_num/old_line_num). Free-floating general comments are only acceptable for summary notes that cannot be attributed to a single location. - Severity Prefix: Prefix each comment with its severity so the author can prioritize:
🔴 Blocking,🟡 Design/Architecture, or🟢 Minor/Suggestion. - Actionable Guidance: Each comment must include a concrete, actionable suggestion — not just a description of the problem. Where applicable, provide a corrected code snippet.
6.2 Resolving Comments (Author Responsibility)
- Reply Before Resolving: When a review comment has been addressed, the author must reply to the specific thread explaining how the issue was resolved (e.g., commit SHA, approach taken, or a reasoned rejection with justification). Do not close a thread without a reply.
- Link to Fix: If the resolution is a code change, include the commit SHA or a reference to the changed line in the reply (e.g.,
Fixed in abc1234 — moved the guard before CTS allocation). - Close Only After Reply: Mark a thread as Resolved only after posting the reply. A thread with no reply must remain open, even if the underlying code has changed.
- Rejection Must Be Justified: If the author disagrees with a comment and chooses not to act on it, they must reply with a clear technical justification. The reviewer then decides whether to accept the reasoning and close the thread, or escalate it.