feat(api): graphql sandbox on unraid servers

[pujitm]

---

• To see the specific tasks where the Asana app for GitHub is being used, see below:
  • https://app.asana.com/0/0/1209125914949311

Summary by CodeRabbit

Release Notes

• New Features

  • Added a development environment configuration option for deployment scripts.
  • Introduced a new sandbox page rendering mechanism for the GraphQL server.

• Improvements

  • Enhanced deployment script with conditional environment checks.
  • Updated GraphQL server configuration with a new sandbox plugin.
  • Refined organization of import statements and provider configuration in the GraphQL module.

[coderabbitai]

Walkthrough

The pull request introduces modifications to the deployment script and GraphQL module configuration. The deploy-dev.sh script now includes a conditional check for the development environment, allowing for different restart behaviors. In the GraphQL module, the configuration has been updated to use a new sandbox plugin, replacing the previous landing page plugin. A new sandbox-plugin.ts file has been added to handle the rendering of the GraphQL sandbox page with more flexible configuration options.

Changes

File	Change Summary
api/scripts/deploy-dev.sh	Added conditional logic for development environment, introducing a dev variable that controls command execution with an optional INTROSPECTION=true environment variable
api/src/unraid-api/graph/graph.module.ts	Updated import statements and GraphQL module configuration, replacing ApolloServerPluginLandingPageLocalDefault with sandboxPlugin
api/src/unraid-api/graph/sandbox-plugin.ts	New file added to implement a custom GraphQL sandbox plugin with dynamic rendering and precondition checks

Possibly related PRs

• fix(api): update deploy-dev script & add ready signal to unraid-api start #1023: Updates deploy-dev.sh script to include a "ready" signal for the unraid-api
• fix(api): pm2 start script & limit auto restarts #1040: Modifies startup script for the unraid-api related to deployment process

Suggested reviewers

• mdatelle

Poem

🐰 A Rabbit's Deployment Delight 🚀

In scripts of dev and server's might,
Conditional checks now shine so bright,
Sandbox plugin dances with grace,
Rendering pages at its own pace,
Code hops forward with pure delight! 🌈

---

📜 Recent review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro (Legacy)

📥 Commits

Reviewing files that changed from the base of the PR and between b296ebb and b73e76c.

📒 Files selected for processing (2)

• api/src/unraid-api/graph/graph.module.ts (3 hunks)
• api/src/unraid-api/graph/sandbox-plugin.ts (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (2)

• api/src/unraid-api/graph/graph.module.ts
• api/src/unraid-api/graph/sandbox-plugin.ts

⏰ Context from checks skipped due to timeout of 90000ms (2)

• GitHub Check: Build Web App
• GitHub Check: Build and Test API

---

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit testing code for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR. (Beta)
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (3)

api/src/unraid-api/graph/graph.module.ts (1)

65-67: Consider documenting sandbox configuration.

The sandbox configuration includes important security settings (cookies, CSRF). Consider adding documentation about these security features.

api/src/store/modules/emhttp.ts (1)

119-140: Consider using a type-safe mapping object.

The switch statement could be replaced with a type-safe mapping object to reduce complexity and improve maintainability.

-            switch (stateFileKey) {
-                case StateFileKey.var:
-                    return { var: config };
-                case StateFileKey.devs:
-                    return { devices: config };
-                // ... other cases
-            }
+            const stateKeyMapping = {
+                [StateFileKey.var]: { var: config },
+                [StateFileKey.devs]: { devices: config },
+                // ... other mappings
+            } as const;
+            return stateKeyMapping[stateFileKey] ?? null;

api/scripts/deploy-dev.sh (1)

48-49: Document the DEV environment variable.

Add a comment explaining the purpose and impact of the DEV environment variable.

+# Controls development mode features (e.g., GraphQL introspection)
+# Default: true
 dev=${DEV:-true}

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro (Legacy)

📥 Commits

Reviewing files that changed from the base of the PR and between bb7800a and 4dec9a7.

📒 Files selected for processing (3)

• api/scripts/deploy-dev.sh (1 hunks)
• api/src/store/modules/emhttp.ts (4 hunks)
• api/src/unraid-api/graph/graph.module.ts (3 hunks)

⏰ Context from checks skipped due to timeout of 90000ms (3)

• GitHub Check: Build and Test API
• GitHub Check: Build Web App
• GitHub Check: Cloudflare Pages

🔇 Additional comments (5)

api/src/unraid-api/graph/graph.module.ts (2)

29-48: Well-structured initial query example.

The sample query provides a good starting point for users exploring the API through the Apollo sandbox, focusing on the notifications feature.

---

64-75: Verify CSRF token handling in GraphQL sandbox.

The sandbox configuration includes CSRF token handling, but we should ensure it's properly synchronized with the server's CSRF protection mechanism.

✅ Verification successful

CSRF token handling in GraphQL sandbox is properly implemented and secure.

The sandbox configuration is correctly synchronized with the server's CSRF protection mechanism through:

• Server-side validation in the authentication flow
• Proper token inheritance in the GraphQL context
• Integration with the cookie-based authentication strategy

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Check if CSRF validation is implemented in the GraphQL context
rg -A 5 "csrf" --glob "*.ts"

Length of output: 10278

api/src/store/modules/emhttp.ts (2)

92-104: Well-structured state initialization.

The new loadState function provides a clean, centralized approach to loading all state files with proper default values.

---

111-112: Address TODO comment regarding type definition.

The TODO comment indicates a need for proper type definition.

Would you like me to help implement the correct type for the loadSingleStateFile thunk?

api/scripts/deploy-dev.sh (1)

48-54: Security: Control introspection in production.

While enabling introspection in development is useful, ensure it's properly restricted in production environments.

Consider these recommendations:

1. Set DEV=false explicitly in production deployment scripts
2. Add a warning log when introspection is enabled
3. Document the security implications in the deployment guide

Run this check to verify introspection handling:

[elibosley]

Pujit and I discussed possibly moving this to be instantiated within Nest.js as it's own controller, to allow instantiation on runtime, rather than on build time.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (3)

api/src/unraid-api/graph/sandbox-plugin.ts (3)

27-29: Avoid unnecessary whitespace in function implementation

In the preconditionFailed function, consider removing the extra space at the end of the error message string on line 28 for consistency and to avoid unintended formatting issues.

Apply this diff to remove the extra space:

-    throw new HttpException(`Precondition failed: ${preconditionName} `, HttpStatus.PRECONDITION_FAILED);
+    throw new HttpException(`Precondition failed: ${preconditionName}`, HttpStatus.PRECONDITION_FAILED);

---

45-68: Handle potential errors from dynamic imports

While using dynamic imports enhances flexibility, it's important to handle cases where the modules might fail to load. This ensures that the server can respond gracefully to such failures.

Apply this diff to add error handling for the dynamic imports:

 async function renderSandboxPage(service: GraphQLServerContext) {
-    const { getters } = await import('@app/store');
+    let getters;
+    try {
+        ({ getters } = await import('@app/store'));
+    } catch (error) {
+        return preconditionFailed('Failed to import @app/store');
+    }

-    const { ApolloServerPluginLandingPageLocalDefault } = await import(
-        '@apollo/server/plugin/landingPage/default'
-    );
+    let ApolloServerPluginLandingPageLocalDefault;
+    try {
+        ({ ApolloServerPluginLandingPageLocalDefault } = await import(
+            '@apollo/server/plugin/landingPage/default'
+        ));
+    } catch (error) {
+        return preconditionFailed('Failed to import ApolloServerPluginLandingPageLocalDefault');
+    }

---

62-67: Simplify precondition checks for better clarity

The sequential precondition checks can be streamlined to enhance readability and maintainability.

Apply this diff to consolidate the precondition checks:

 if (!plugin.serverWillStart) return preconditionFailed('serverWillStart');
 const serverListener = await plugin.serverWillStart(service);

-if (!serverListener) return preconditionFailed('serverListener');
-if (!serverListener.renderLandingPage) return preconditionFailed('renderLandingPage');
+if (!serverListener?.renderLandingPage) {
+    return preconditionFailed('renderLandingPage');
+}
 return serverListener.renderLandingPage();

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro (Legacy)

📥 Commits

Reviewing files that changed from the base of the PR and between 4dec9a7 and b296ebb.

📒 Files selected for processing (2)

• api/src/unraid-api/graph/graph.module.ts (3 hunks)
• api/src/unraid-api/graph/sandbox-plugin.ts (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• api/src/unraid-api/graph/graph.module.ts

⏰ Context from checks skipped due to timeout of 90000ms (3)

• GitHub Check: Build Web App
• GitHub Check: Build and Test API
• GitHub Check: Cloudflare Pages

🔇 Additional comments (3)

api/src/unraid-api/graph/sandbox-plugin.ts (3)

1-82: Overall, the implementation is well-structured

The new sandbox-plugin.ts file provides a flexible approach to rendering the GraphQL Sandbox page at runtime. The use of dynamic imports and deferred configuration aligns with the objectives outlined in the PR.

---

77-82: Confirm TypeScript compatibility with the 'satisfies' operator

The use of the satisfies operator on line 81 requires TypeScript version 4.9 or above. Ensure that the project's TypeScript configuration supports this feature to prevent build errors.

You can verify the installed TypeScript version with the following script:

✅ Verification successful

TypeScript version is compatible with 'satisfies' operator

The project uses TypeScript 5.x (^5.0.0, ^5.6.3), which fully supports the 'satisfies' operator introduced in TypeScript 4.9. No configuration changes are needed.

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Description: Check the installed TypeScript version.

# Expected result: Version 4.9.0 or higher.
npx tsc --version

Length of output: 113

---

Script:

#!/bin/bash
# Find and check package.json files for TypeScript version
echo "=== Checking package.json files ==="
fd package.json --type f --exec cat {} \; | jq -r 'select(.dependencies.typescript or .devDependencies.typescript) | "TypeScript version: \(.dependencies.typescript // .devDependencies.typescript)"'

echo -e "\n=== Checking tsconfig files ==="
fd tsconfig.json --type f --exec cat {} \;

Length of output: 3410

---

5-24: Verify that the initial GraphQL query matches the schema

Ensure that the initialDocument query aligns with the current GraphQL schema. Any discrepancies might lead to runtime errors when loading the sandbox.

You can run the following script to check for matching fields in the schema:

✅ Verification successful

The initial GraphQL query perfectly matches the schema

The query structure and all fields (notifications, overview, unread, archive, and their respective counts) align with the schema definitions in notifications.graphql.

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Description: Verify that fields in initialDocument exist in the schema.

# Extract fields from the initialDocument.
echo "$initialDocument" | grep -oP '\w+(?=\s*\{|\s*\()' | sort -u > query_fields.txt

# Search the entire codebase for schema definitions of these fields.
while read -r field; do
    echo "Searching for field: $field"
    rg --context 5 "type.*$field|$field.*:" api/src/
done < query_fields.txt

Length of output: 67

---

Script:

#!/bin/bash
# Find GraphQL schema files
echo "=== GraphQL Schema Files ==="
fd -e graphql -e gql

# Search for notifications type and field definitions
echo -e "\n=== Notifications Type Definition ==="
rg -t graphql -t typescript "type.*Notifications|notifications.*:|Query.*{" -A 10

# Search for Overview type
echo -e "\n=== Overview Type Definition ==="
rg -t graphql -t typescript "type.*Overview|overview.*:" -A 10

# Search for specific nested fields
echo -e "\n=== Nested Fields Definitions ==="
rg -t graphql -t typescript "unread|archive|info|warning|alert|total" -A 3 -B 3

Length of output: 2852

---

Script:

#!/bin/bash
# Read the notifications schema
echo "=== Notifications Schema ==="
cat api/src/graphql/schema/types/notifications/notifications.graphql

# Read the base schema for Query type
echo -e "\n=== Base Schema ==="
cat api/src/graphql/schema/types/base.graphql

Length of output: 2961

[github-actions]

This plugin has been deployed to Cloudflare R2 and is available for testing.
Download it at this URL: https://preview.dl.unraid.net/unraid-api/pr/1047/dynamix.unraid.net.staging.plg

[github-actions]

This plugin has been deployed to Cloudflare R2 and is available for testing.
Download it at this URL: https://preview.dl.unraid.net/unraid-api/pr/1047/dynamix.unraid.net.staging.plg