Improve Web API implementation with enhanced security and thread-safety

API_IMPROVEMENTS.md

@@ -0,0 +1,190 @@
+# API Implementation Improvements
+
+## Overview
+This document summarizes the improvements made to the Fess API implementation in `src/main/java/org/codelibs/fess/api/`.
+
+## Improvements Made
+
+### 1. WebApiManagerFactory Refactoring
+**File:** `WebApiManagerFactory.java`
+
+**Changes:**
+- Replaced inefficient array-based storage with `CopyOnWriteArrayList`
+- Removed unnecessary array copying on each `add()` operation
+- Added null check validation in `add()` method
+- Added `size()` method for better introspection
+- Improved thread-safety for concurrent initialization
+- Enhanced JavaDoc documentation
+
+**Benefits:**
+- Better performance when adding API managers during initialization
+- Thread-safe operations
+- Cleaner, more maintainable code
+
+### 2. JSON Response Utility
+**File:** `api/json/JsonResponseUtil.java` (NEW)
+
+**Features:**
+- Centralized JSON response building using Jackson ObjectMapper
+- Consistent error response formatting
+- Exception-to-response conversion with error code generation
+- Stack trace handling with configurable verbosity
+- JSONP callback name sanitization
+- Reusable utility methods for success and error responses
+
+**Benefits:**
+- Eliminates manual JSON string building (error-prone StringBuilder usage)
+- Consistent response format across all API endpoints
+- Better error handling and logging
+- Easier to maintain and test
+
+### 3. Content Type Utility
+**File:** `ContentTypeUtil.java` (NEW)
+
+**Features:**
+- Map-based content type detection by file extension
+- Support for common web formats (HTML, CSS, JS, JSON, XML)
+- Support for font formats (EOT, OTF, TTF, WOFF, WOFF2)
+- Support for image formats (PNG, JPG, SVG, ICO, GIF, WEBP)
+- Support for document formats (PDF, ZIP, TAR, GZ)
+- Extensible design allowing custom type registration
+- Directory path handling
+
+**Benefits:**
+- Replaced long if-else chains in `SearchEngineApiManager`
+- Easier to add new content types
+- Centralized content type management
+- More maintainable and testable
+
+### 4. API Constants
+**File:** `ApiConstants.java` (NEW)
+
+**Features:**
+- Centralized API-related constants
+- Request attribute keys (API_FORMAT_TYPE, DOC_ID_FIELD)
+- Response field names (MESSAGE_FIELD, RESULT_FIELD, etc.)
+- HTTP method constants
+- MIME type constants
+- API path prefixes
+- Default values
+- Common error messages
+
+**Benefits:**
+- Eliminates magic strings throughout the codebase
+- Single source of truth for constants
+- Easier to maintain and update
+- Prevents typos and inconsistencies
+- Better IDE support with autocomplete
+
+### 5. BaseApiManager Improvements
+**File:** `BaseApiManager.java`
+
+**Changes:**
+- Replaced if-else chain with `FormatType.valueOf()` for format detection
+- Uses ApiConstants instead of local constant
+- More efficient enum-based type detection
+
+**Benefits:**
+- Cleaner, more maintainable code
+- Better performance (no string comparisons)
+- Automatic validation of format types
+
+### 6. SearchEngineApiManager Improvements
+**File:** `engine/SearchEngineApiManager.java`
+
+**Changes:**
+- Refactored `processPluginRequest()` to use `ContentTypeUtil`
+- Removed 13 if-else statements for content type detection
+- Simplified content type handling logic
+
+**Benefits:**
+- Much cleaner and more readable code
+- Reduced from ~30 lines to ~7 lines
+- Easier to add new content types
+- Better separation of concerns
+
+## Code Quality Improvements
+
+### Documentation
+- Added comprehensive JavaDoc to all new classes and methods
+- Improved existing JavaDoc documentation
+- Added usage examples in class-level documentation
+
+### Design Patterns
+- Factory pattern (WebApiManagerFactory)
+- Utility pattern (JsonResponseUtil, ContentTypeUtil, ApiConstants)
+- Template method pattern (BaseApiManager)
+
+### Thread Safety
+- `WebApiManagerFactory` now uses thread-safe `CopyOnWriteArrayList`
+- Safe for concurrent initialization
+
+### Maintainability
+- Reduced code duplication
+- Centralized common functionality
+- Clear separation of concerns
+- Easier to test and mock
+
+## Potential Future Improvements
+
+### 1. Split SearchApiManager
+The `SearchApiManager` class is still very large (1422 lines). Consider splitting into:
+- `SearchRequestHandler`
+- `LabelRequestHandler`
+- `PopularWordRequestHandler`
+- `FavoriteRequestHandler`
+- `PingRequestHandler`
+- `ScrollSearchRequestHandler`
+- `SuggestRequestHandler`
+
+Each handler could implement a common `ApiRequestHandler` interface.
+
+### 2. Further JSON Improvements
+- Consider using Jackson annotations on response DTOs
+- Create dedicated response DTO classes instead of building JSON manually
+- This would eliminate the remaining StringBuilder usage in SearchApiManager
+
+### 3. Request Validation
+- Add Bean Validation annotations
+- Create request DTO classes with validation
+- Centralize validation logic
+
+### 4. Error Handling
+- Create a centralized error handling mechanism
+- Use custom exception types
+- Implement proper HTTP status code mapping
+
+### 5. API Versioning
+- Better support for API version management
+- Version-specific handlers
+- Backward compatibility support
+
+## Testing Recommendations
+
+### Unit Tests
+- Test WebApiManagerFactory with concurrent additions
+- Test JsonResponseUtil error formatting
+- Test ContentTypeUtil with various file extensions
+- Test BaseApiManager format type detection
+
+### Integration Tests
+- Test complete API request/response cycles
+- Test error scenarios
+- Test content type negotiation
+- Test JSONP callback handling
+
+## Migration Notes
+
+The improvements are **backward compatible**:
+- Existing API endpoints continue to work
+- No breaking changes to public APIs
+- Internal refactoring only
+
+## Summary
+
+These improvements significantly enhance the maintainability, readability, and performance of the Fess API implementation while maintaining full backward compatibility. The code is now more modular, easier to test, and follows better software engineering practices.
+
+Total lines of code reduced: ~40 lines
+New utility classes: 3
+Improved classes: 3
+Constants centralized: 20+

src/main/java/org/codelibs/fess/api/ApiConstants.java

@@ -0,0 +1,131 @@
+/*
+ * Copyright 2012-2025 CodeLibs Project and the Others.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+ * either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+package org.codelibs.fess.api;
+
+/**
+ * Constants used across the API layer.
+ * Centralizes magic strings and configuration values for better maintainability.
+ */
+public final class ApiConstants {
+
+    /** Private constructor to prevent instantiation */
+    private ApiConstants() {
+        // Constants class
+    }
+
+    // Request attribute keys
+    /** Request attribute key for storing API format type */
+    public static final String API_FORMAT_TYPE = "apiFormatType";
+
+    /** Request attribute key for storing document ID */
+    public static final String DOC_ID_FIELD = "doc_id";
+
+    // Response field names
+    /** JSON response field name for messages */
+    public static final String MESSAGE_FIELD = "message";
+
+    /** JSON response field name for results */
+    public static final String RESULT_FIELD = "result";
+
+    /** JSON response field name for error codes */
+    public static final String ERROR_CODE_FIELD = "error_code";
+
+    /** JSON response field name for data */
+    public static final String DATA_FIELD = "data";
+
+    /** JSON response field name for record count */
+    public static final String RECORD_COUNT_FIELD = "record_count";
+
+    /** JSON response field name for query */
+    public static final String QUERY_FIELD = "q";
+
+    /** JSON response field name for query ID */
+    public static final String QUERY_ID_FIELD = "query_id";
+
+    // HTTP methods
+    /** HTTP GET method */
+    public static final String HTTP_METHOD_GET = "GET";
+
+    /** HTTP POST method */
+    public static final String HTTP_METHOD_POST = "POST";
+
+    /** HTTP PUT method */
+    public static final String HTTP_METHOD_PUT = "PUT";
+
+    /** HTTP DELETE method */
+    public static final String HTTP_METHOD_DELETE = "DELETE";
+
+    /** HTTP PATCH method */
+    public static final String HTTP_METHOD_PATCH = "PATCH";
+
+    // MIME types
+    /** MIME type for JSON */
+    public static final String MIME_TYPE_JSON = "application/json";
+
+    /** MIME type for JSONP */
+    public static final String MIME_TYPE_JAVASCRIPT = "application/javascript";
+
+    /** MIME type for NDJSON (newline-delimited JSON) */
+    public static final String MIME_TYPE_NDJSON = "application/x-ndjson";
+
+    /** MIME type for text */
+    public static final String MIME_TYPE_TEXT = "text/plain";
+
+    // API paths
+    /** API v1 path prefix */
+    public static final String API_V1_PREFIX = "/api/v1";
+
+    /** Admin server path prefix */
+    public static final String ADMIN_SERVER_PREFIX = "/admin/server_";
+
+    // Default values
+    /** Default number of suggestions to return */
+    public static final int DEFAULT_SUGGEST_NUM = 10;
+
+    /** Default result value for created resources */
+    public static final String RESULT_CREATED = "created";
+
+    /** Default result value for updated resources */
+    public static final String RESULT_UPDATED = "updated";
+
+    /** Default result value for deleted resources */
+    public static final String RESULT_DELETED = "deleted";
+
+    // Error messages
+    /** Error message for unsupported operations */
+    public static final String ERROR_UNSUPPORTED_OPERATION = "Unsupported operation.";
+
+    /** Error message for not found resources */
+    public static final String ERROR_NOT_FOUND = "Not found.";
+
+    /** Error message for invalid referer */
+    public static final String ERROR_INVALID_REFERER = "Referer is invalid.";
+
+    /** Error message for method not allowed */
+    public static final String ERROR_METHOD_NOT_ALLOWED = " is not allowed.";
+
+    /** Error message for no user session */
+    public static final String ERROR_NO_USER_SESSION = "No user session.";
+
+    /** Error message for invalid session */
+    public static final String ERROR_INVALID_SESSION = "Invalid session.";
+
+    /** Error message for invalid access token */
+    public static final String ERROR_INVALID_ACCESS_TOKEN = "Invalid access token.";
+
+    /** Error message for unauthorized access */
+    public static final String ERROR_UNAUTHORIZED_ACCESS = "Unauthorized access: ";
+}

src/main/java/org/codelibs/fess/api/BaseApiManager.java

@@ -34,8 +34,6 @@
  */
 public abstract class BaseApiManager implements WebApiManager {
 
-    private static final String API_FORMAT_TYPE = "apiFormatType";
-
     /** Path prefix for API endpoints. */
     protected String pathPrefix;
 
@@ -92,13 +90,13 @@ public void setPathPrefix(final String pathPrefix) {
      * @return The format type.
      */
     protected FormatType getFormatType(final HttpServletRequest request) {
-        FormatType formatType = (FormatType) request.getAttribute(API_FORMAT_TYPE);
+        FormatType formatType = (FormatType) request.getAttribute(ApiConstants.API_FORMAT_TYPE);
         if (formatType != null) {
             return formatType;
         }
 
         formatType = detectFormatType(request);
-        request.setAttribute(API_FORMAT_TYPE, formatType);
+        request.setAttribute(ApiConstants.API_FORMAT_TYPE, formatType);
         return formatType;
     }
 
@@ -120,33 +118,12 @@ protected FormatType detectFormatType(final HttpServletRequest request) {
             return FormatType.SEARCH;
         }
         final String type = value.toUpperCase(Locale.ROOT);
-        if (FormatType.SEARCH.name().equals(type)) {
-            return FormatType.SEARCH;
-        }
-        if (FormatType.LABEL.name().equals(type)) {
-            return FormatType.LABEL;
-        }
-        if (FormatType.POPULARWORD.name().equals(type)) {
-            return FormatType.POPULARWORD;
-        }
-        if (FormatType.FAVORITE.name().equals(type)) {
-            return FormatType.FAVORITE;
+        try {
+            return FormatType.valueOf(type);
+        } catch (final IllegalArgumentException e) {
+            // If the type is not recognized, return OTHER
+            return FormatType.OTHER;
         }
-        if (FormatType.FAVORITES.name().equals(type)) {
-            return FormatType.FAVORITES;
-        }
-        if (FormatType.PING.name().equals(type)) {
-            return FormatType.PING;
-        }
-        if (FormatType.SCROLL.name().equals(type)) {
-            return FormatType.SCROLL;
-        }
-        if (FormatType.SUGGEST.name().equals(type)) {
-            return FormatType.SUGGEST;
-        }
-
-        // default
-        return FormatType.OTHER;
     }
 
     /**