system_app.py

Overview

system_app.py is a Flask-based backend API module that provides system-level endpoints for the InfiniFlow application. It includes routes for retrieving system version and status, managing API tokens for authentication, and fetching system configuration settings.

The file primarily serves the following purposes:

Expose system metadata (version, status, configuration).
Provide API token management (creation, listing, deletion) tied to user tenants.
Perform health checks on critical system components: document engine, storage backend, database, and Redis cache.
Serve as a gateway for authenticated users to access system-level information and manage their API tokens.

This module interacts heavily with database services, Redis cache, storage engine implementations, and authentication utilities to consolidate and expose relevant system information.

Detailed Description of Endpoints and Functions

1. `version()`

Route: /version
Method: GET
Authentication: Required (login_required decorator)

Description:
Returns the current version of the InfiniFlow application.

Returns:

HTTP 200 with JSON payload containing the version string.

Usage Example:

GET /version
Authorization: Bearer <token>

Response:

{
  "version": "1.2.3"
}

Implementation Details:
Uses get_ragflow_version() from api.versions to retrieve the version string and wraps the result with get_json_result() for standardized JSON response formatting.

2. `status()`

Route: /status
Method: GET
Authentication: Required

Description:
Performs a comprehensive health check on core system components:

Document engine (likely Elasticsearch or similar)
Storage backend (file system, cloud storage, etc.)
Database (used for knowledge base and other data)
Redis cache
Task executor heartbeats (checks activity of distributed task executors)

Returns:

HTTP 200 with JSON object containing health status, elapsed response times, and any error messages.
HTTP 503 if any critical service is unavailable (handled by the client based on status).

Implementation Details:

Uses Python’s timeit.default_timer() for measuring elapsed time per check.
Calls .health() method on document engine and storage implementations.
Executes a dummy fetch (KnowledgebaseService.get_by_id("x")) to test database connectivity.
Checks Redis connectivity via REDIS_CONN.health().
Queries Redis for active task executors and their recent heartbeat logs (last 30 minutes).
Catches exceptions individually per component to report granular status without failing the entire status endpoint.

Usage Example:

GET /status
Authorization: Bearer <token>

Response Example:

{
  "doc_engine": {
    "status": "green",
    "elapsed": "12.3"
  },
  "storage": {
    "storage": "filesystem",
    "status": "green",
    "elapsed": "5.0"
  },
  "database": {
    "database": "postgresql",
    "status": "green",
    "elapsed": "8.7"
  },
  "redis": {
    "status": "green",
    "elapsed": "2.1"
  },
  "task_executor_heartbeats": {
    "executor_1": [
      {"timestamp": 1685858400, "status": "alive"}
    ]
  }
}

3. `new_token()`

Route: /new_token
Method: POST
Authentication: Required

Description:
Generates a new API token for the current user’s tenant with the 'owner' role.

Parameters:

Optional query parameter name (string) — name of the token (not currently used in the implementation).

Returns:

HTTP 200 with JSON containing the newly created token data.
HTTP 400 with error if tenant is not found.
HTTP 500 on server error.

Token Data Fields:

tenant_id: ID of the tenant owning the token.
token: A confirmation token string generated for access authentication.
beta: An additional token string derived from a nested token generation, truncated to 32 characters.
create_time: Timestamp integer of creation.
create_date: Formatted datetime string.
update_time and update_date: Initially None, used for updates.

Implementation Details:

Queries user tenants via UserTenantService.query.
Selects the tenant where the user role is 'owner'.
Uses generate_confirmation_token() utility to create tokens.
Saves token info using APITokenService.save.
Handles exceptions and returns standardized error responses.

Usage Example:

POST /new_token
Authorization: Bearer <token>

Response Example:

{
  "tenant_id": "tenant-123",
  "token": "ragflow-abcdef123456",
  "beta": "bcdef1234567890abcdef1234567890",
  "create_time": 1685858400,
  "create_date": "2024-06-04 12:00:00",
  "update_time": null,
  "update_date": null
}

4. `token_list()`

Route: /token_list
Method: GET
Authentication: Required

Description:
Lists all API tokens associated with the current user's tenant that has 'owner' role.

Returns:

HTTP 200 with JSON array of token objects.
HTTP 400 if tenant not found.
HTTP 500 on server error.

Token Object Fields:

token: API token string.
name: (Not shown in current implementation but documented, may be optional or future feature).
create_time: Timestamp integer.
beta: Beta token string (added if missing).

Implementation Details:

Queries tenant and tokens similarly to new_token.
Ensures all tokens have a beta field, generating it if missing.
Updates tokens in the database if their beta field was missing.

Usage Example:

GET /token_list
Authorization: Bearer <token>

Response Example:

[
  {
    "token": "ragflow-abcdef123456",
    "name": "My Token",
    "create_time": 1685858400,
    "beta": "bcdef1234567890abcdef1234567890"
  },
  ...
]

5. `rm(token)`

Route: /token/<token>
Method: DELETE
Authentication: Required

Description:
Removes (deletes) the specified API token belonging to the current user.

Parameters:

token (path parameter, string): The API token to delete.

Returns:

HTTP 200 with JSON indicating success (boolean).

Implementation Details:

Uses APITokenService.filter_delete with filter conditions matching the current user's tenant ID and the token string.
No explicit error handling in the snippet (assumes service handles errors).

Usage Example:

DELETE /token/ragflow-abcdef123456
Authorization: Bearer <token>

Response Example:

true

6. `get_config()`

Route: /config
Method: GET
Authentication: None (public endpoint)

Description:
Returns system configuration flags, currently exposing whether user registration is enabled.

Returns:

HTTP 200 with JSON object containing configuration flags.

Returned Fields:

registerEnabled: Integer (0 or 1), indicating if user registration is enabled.

Usage Example:

GET /config

Response Example:

{
  "registerEnabled": 1
}

Important Implementation Details and Algorithms

Health Checks: Each component health check is wrapped in try-except blocks to isolate failures and provide detailed status including error messages and elapsed time in milliseconds.
Task Executor Heartbeats: Redis sorted sets are used to store timestamped heartbeat JSON objects per task executor. The status endpoint fetches heartbeat entries from the last 30 minutes for each executor.
API Token Generation: Tokens are generated using a confirmation token utility, with a nested token generation step to produce a beta token variant (possibly for feature flagging or phased rollout).
User-Tenant Model: The API token management heavily relies on the user-tenant relationship, ensuring tokens are created and listed only for tenants where the user holds an 'owner' role.
Response Wrapping: All endpoints return data wrapped with helper functions like get_json_result or error wrappers for consistent API responses.

Interaction with Other Components

Flask-Login: Ensures that routes are accessible only to authenticated users (login_required).
Database Models and Services: Uses APIToken, APITokenService, KnowledgebaseService, and UserTenantService to perform CRUD operations on persistent data.
Settings: Reads configuration values (e.g., REGISTER_ENABLED, DATABASE_TYPE) from centralized settings.
Storage Implementations: Uses STORAGE_IMPL and STORAGE_IMPL_TYPE from rag.utils.storage_factory to check storage backend health.
Redis: Uses REDIS_CONN to check Redis health and to query task executor heartbeat data.
Versioning: Gets application version from api.versions.
Utilities: Uses various utility functions for timestamps, JSON response formatting, and token generation.

Mermaid Class Diagram

classDiagram
    class system_app {
        +version()
        +status()
        +new_token()
        +token_list()
        +rm(token)
        +get_config()
    }

Note: This module is primarily a collection of Flask route functions, not classes. The diagram shows the module as a container of these endpoint functions.

Summary

system_app.py is a crucial system API module that provides endpoints for:

Retrieving system version and status with detailed health checks.
Managing API tokens tied to user tenants and roles.
Accessing system configuration flags such as user registration enablement.

Its design emphasizes robust component health monitoring, secure API token lifecycle management, and consistent JSON-based API responses. It integrates tightly with core services, databases, Redis cache, and authentication mechanisms to deliver system-level insights and controls to authorized users.

system_app.py

Overview

Detailed Description of Endpoints and Functions

1. version()

2. status()

3. new_token()

4. token_list()

5. rm(token)

6. get_config()

Important Implementation Details and Algorithms

Interaction with Other Components

Mermaid Class Diagram

Summary

1. `version()`

2. `status()`

3. `new_token()`

4. `token_list()`

5. `rm(token)`

6. `get_config()`