search_app.py

Overview

search_app.py is a Flask-based REST API endpoint module responsible for managing Search App entities within the InfiniFlow system. It exposes routes for creating, updating, retrieving details, listing, and deleting Search Apps. The module enforces authentication and authorization using Flask-Login and integrates tightly with backend services for data validation, persistence, and querying.

Key responsibilities include:

• Managing Search App lifecycle (CRUD operations).

• Validating input data and enforcing naming constraints.

• Handling tenant-based permissions and access controls.

• Coordinating with underlying database services (SearchService, TenantService, etc.).

• Providing JSON responses with standardized error handling.

Classes and Functions

This module does not define any classes; instead, it defines several Flask route handler functions that implement the API endpoints for Search App management.

1. create()

Purpose

Creates a new Search App record for the authenticated user (tenant).

Route and Method

• POST /create

Decorators

• @login_required: Ensures the user is authenticated.

• @validate_request("name"): Validates that the incoming JSON contains the "name" field.

Parameters

• Expects JSON body with:

  • name (string, required): Name of the Search App.

  • description (string, optional): Description of the Search App.

Workflow

• Validates name is a non-empty string and does not exceed 255 bytes in UTF-8.

• Checks that the current user's tenant exists.

• Sanitizes and deduplicates the search app name using duplicate_name.

• Generates a UUID for the new Search App.

• Saves the new Search App via SearchService.save.

• Returns JSON with the new search_id if successful.

Returns

• On success: JSON containing {"search_id": <UUID>}.

• On failure: JSON error message with appropriate HTTP status.

Usage Example (cURL)

curl -X POST /create \
  -H "Content-Type: application/json" \
  -d '{"name": "My Search App", "description": "A sample search app"}' \
  -b "session=<user_session_cookie>"

2. update()

Purpose

Updates an existing Search App's properties.

Route and Method

• POST /update

Decorators

• @login_required

• @validate_request("search_id", "name", "search_config", "tenant_id")

• @not_allowed_parameters("id", "created_by", "create_time", "update_time", "create_date", "update_date", "created_by")

Parameters

• JSON body must include:

  • search_id (string): Identifier of the Search App to update.

  • name (string): New name for the Search App.

  • search_config (dict): JSON object representing updated configuration.

  • tenant_id (string): Tenant owning the Search App.

Workflow

• Validates name length and format.

• Verifies tenant existence.

• Checks user authorization to perform update via SearchService.accessible4deletion.

• Fetches current Search App data.

• Checks for duplicate names within the tenant.

• Merges existing search_config with new values.

• Removes disallowed fields from request.

• Updates Search App via SearchService.update_by_id.

• Returns updated Search App data.

Returns

• On success: JSON with updated Search App data.

• On failure: JSON error message.

Usage Example (cURL)

curl -X POST /update \
  -H "Content-Type: application/json" \
  -d '{
        "search_id": "uuid-1234",
        "name": "Updated Search App",
        "search_config": {"setting": "new_value"},
        "tenant_id": "tenant-5678"
      }' \
  -b "session=<user_session_cookie>"

3. detail()

Purpose

Retrieves detailed information about a specific Search App if the user has permission.

Route and Method

• GET /detail

Decorators

• @login_required

Parameters

• Query string parameter:

  • search_id (string): Identifier of the Search App.

Workflow

• Retrieves all tenants associated with the current user.

• Checks if the Search App exists under any of these tenants.

• Returns detailed Search App info from SearchService.get_detail.

Returns

• On success: JSON with Search App detail.

• On failure or no permission: JSON error message.

Usage Example (cURL)

curl -X GET "/detail?search_id=uuid-1234" \
  -b "session=<user_session_cookie>"

4. list_search_app()

Purpose

Lists Search Apps filtered by owner IDs, keywords, pagination, and sorting options.

Route and Method

• POST /list

Decorators

• @login_required

Parameters

• Query string parameters:

  • keywords (string, optional): Search keyword filter.

  • page (int, optional): Page number for pagination.

  • page_size (int, optional): Number of items per page.

  • orderby (string, optional): Field to order by; defaults to "create_time".

  • desc (string, optional): Whether to sort descending; defaults to "true".

• JSON body:

  • owner_ids (list of tenant IDs, optional): Filter by tenant owners.

Workflow

• If no owner_ids provided, fetches Search Apps accessible to the user.

• Otherwise, filters Search Apps by provided tenant IDs.

• Applies pagination and sorting.

• Returns list and total count.

Returns

• JSON containing:

  • search_apps: List of Search App objects.

  • total: Total number of Search Apps matching criteria.

Usage Example (cURL)

curl -X POST "/list?page=1&page_size=10&orderby=create_time&desc=true" \
  -H "Content-Type: application/json" \
  -d '{"owner_ids": ["tenant-123", "tenant-456"]}' \
  -b "session=<user_session_cookie>"

5. rm()

Purpose

Deletes a Search App if the user is authorized.

Route and Method

• POST /rm

Decorators

• @login_required

• @validate_request("search_id")

Parameters

• JSON body:

  • search_id (string): Identifier of the Search App to delete.

Workflow

• Checks user authorization via SearchService.accessible4deletion.

• Calls SearchService.delete_by_id to remove the Search App.

• Returns success or failure response.

Returns

• On success: JSON { "data": true }.

• On failure: JSON error message.

Usage Example (cURL)

curl -X POST /rm \
  -H "Content-Type: application/json" \
  -d '{"search_id": "uuid-1234"}' \
  -b "session=<user_session_cookie>"

Important Implementation Details

• Authentication and Authorization: Every route requires a logged-in user (@login_required). Authorization is enforced via tenant membership checks and specific service calls like SearchService.accessible4deletion.

• Request Validation: The module uses decorators @validate_request and @not_allowed_parameters to ensure required fields are present and forbidden fields are excluded from requests.

• Duplicate Name Handling: When creating or updating a Search App, the system ensures the name is unique within the tenant scope by invoking duplicate_name and querying existing records.

• Atomic Database Transactions: Creation of new Search Apps is wrapped inside DB.atomic() to ensure transactional integrity.

• Error Handling: All exceptions are caught and transformed into server error responses to avoid leaking sensitive information.

• Search Config Merging: The update operation merges new search_config entries with existing ones rather than overwriting entirely, supporting partial updates.

• Pagination and Sorting: List operations support pagination and sorting parameters, improving scalability and user experience.

Interaction with Other System Components

• Flask Framework: The module defines HTTP endpoints using Flask routing mechanisms.

• Flask-Login: Manages user session and authentication.

• api.db.services Layer:

  • SearchService: Core service for CRUD operations on Search Apps.

  • TenantService & UserTenantService: Manage tenant and user-tenant relationships for access control.

  • duplicate_name: Utility for handling name collisions.

• api.utils.api_utils: Provides decorators for request validation, and functions to format JSON responses and error handling.

• api.constants and api.settings: Provide configurable constants like name length limits and return code definitions.

Mermaid Class Diagram

classDiagram
    class SearchService {
        +save(**kwargs) bool
        +update_by_id(search_id, data) bool
        +get_by_id(search_id) (bool, SearchApp)
        +query(**filters) list
        +accessible4deletion(search_id, user_id) bool
        +delete_by_id(search_id) bool
        +get_detail(search_id) dict
        +get_by_tenant_ids(tenant_ids, user_id, page, page_size, orderby, desc, keywords) (list, int)
    }

    class TenantService {
        +get_by_id(tenant_id) (bool, Tenant)
    }

    class UserTenantService {
        +query(user_id) list
    }

    class DB {
        +atomic() contextmanager
    }

    class Flask_Routes {
        +create()
        +update()
        +detail()
        +list_search_app()
        +rm()
    }

    Flask_Routes ..> SearchService : uses
    Flask_Routes ..> TenantService : uses
    Flask_Routes ..> UserTenantService : uses
    Flask_Routes ..> DB : uses

Summary

search_app.py is a critical API module in the InfiniFlow backend for managing Search Apps. It ensures robust validation, secure multi-tenant access, and consistent CRUD operations. By coordinating with multiple service layers and enforcing strict request contracts, it maintains data integrity and a seamless user experience for managing Search Apps.

This file is intended to be part of a larger system where Search Apps represent configurable search configurations or workflows owned by tenants in the InfiniFlow platform.