feat(hunspell): Add ref_path support for package-based dictionary loading

- Add ref_path parameter to HunspellTokenFilterFactory for package-based dictionaries
- Load dictionaries from config/packages/{packageId}/hunspell/{locale}/
- Add cache key strategy: traditional (locale) vs package-based (packageId:locale)
- Add cache management methods in HunspellService (invalidate, invalidateAll, invalidateByPackage)
- Add security validation (path traversal, separator injection, null bytes)
- Add updateable flag for hot-reload via _reload_search_analyzers
- Use Strings.hasText() and Strings.isNullOrEmpty() for validation consistency
- Add comprehensive unit tests for HunspellService and HunspellTokenFilterFactory

Signed-off-by: Ayush Sharma <118544643+shayush622@users.noreply.github.com>
Signed-off-by: shayush622 <ayush5267@gmail.com>

Author: shayush622

CHANGELOG.md

@@ -39,6 +39,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Implement FieldMappingIngestionMessageMapper for pull-based ingestion ([#20729](https://github.com/opensearch-project/OpenSearch/pull/20729))
 - Added support of WarmerRefreshListener in NRTReplicationEngine to trigger warmer after replication on replica shards ([#20650](https://github.com/opensearch-project/OpenSearch/pull/20650))
 - WLM group custom search settings - groundwork and timeout ([#20536](https://github.com/opensearch-project/OpenSearch/issues/20536))
+- Add ref_path support for package-based hunspell dictionary loading ([#20840](https://github.com/opensearch-project/OpenSearch/pull/20840))
 
 ### Changed
 - Make telemetry `Tags` immutable ([#20788](https://github.com/opensearch-project/OpenSearch/pull/20788))

server/src/main/java/org/opensearch/index/analysis/HunspellTokenFilterFactory.java

@@ -43,25 +43,77 @@
 /**
  * The token filter factory for the hunspell analyzer
  *
+ * Supports hot-reload when used with {@code updateable: true} setting.
+ * The dictionary is loaded from either:
+ * <ul>
+ *   <li>A ref_path (package ID, e.g., "pkg-1234") combined with locale for package-based dictionaries</li>
+ *   <li>A locale (e.g., "en_US") for traditional hunspell dictionaries from config/hunspell/</li>
+ * </ul>
+ *
+ * <h2>Usage Examples:</h2>
+ * <pre>
+ * // Traditional locale-based (loads from config/hunspell/en_US/)
+ * {
+ *   "type": "hunspell",
+ *   "locale": "en_US"
+ * }
+ *
+ * // Package-based (loads from config/packages/pkg-1234/hunspell/en_US/)
+ * {
+ *   "type": "hunspell",
+ *   "ref_path": "pkg-1234",
+ *   "locale": "en_US"
+ * }
+ * </pre>
+ *
+ *
  * @opensearch.internal
  */
 public class HunspellTokenFilterFactory extends AbstractTokenFilterFactory {
 
     private final Dictionary dictionary;
     private final boolean dedup;
     private final boolean longestOnly;
+    private final AnalysisMode analysisMode;
 
     public HunspellTokenFilterFactory(IndexSettings indexSettings, String name, Settings settings, HunspellService hunspellService) {
         super(indexSettings, name, settings);
+        // Check for updateable flag - enables hot-reload support (same pattern as SynonymTokenFilterFactory)
+        boolean updateable = settings.getAsBoolean("updateable", false);
+        this.analysisMode = updateable ? AnalysisMode.SEARCH_TIME : AnalysisMode.ALL;
 
+        // Get both ref_path and locale parameters
+        String refPath = settings.get("ref_path");  // Package ID only (optional)
         String locale = settings.get("locale", settings.get("language", settings.get("lang", null)));
-        if (locale == null) {
-            throw new IllegalArgumentException("missing [locale | language | lang] configuration for hunspell token filter");
-        }
 
-        dictionary = hunspellService.getDictionary(locale);
-        if (dictionary == null) {
-            throw new IllegalArgumentException(String.format(Locale.ROOT, "Unknown hunspell dictionary for locale [%s]", locale));
+        if (refPath != null) {
+            // Package-based loading: ref_path (package ID) + locale (required)
+            if (locale == null) {
+                throw new IllegalArgumentException("When using ref_path, the 'locale' parameter is required for hunspell token filter");
+            }
+
+            // Validate ref_path and locale are safe package/locale identifiers
+            validatePackageIdentifier(refPath, "ref_path");
+            validatePackageIdentifier(locale, "locale");
+
+            // Load from package directory: config/packages/{ref_path}/hunspell/{locale}/
+            dictionary = hunspellService.getDictionaryFromPackage(refPath, locale);
+            if (dictionary == null) {
+                throw new IllegalArgumentException(
+                    String.format(Locale.ROOT, "Could not find hunspell dictionary for locale [%s] in package [%s]", locale, refPath)
+                );
+            }
+        } else if (locale != null) {
+            // Traditional locale-based loading (backward compatible)
+            // Loads from config/hunspell/{locale}/
+            // Validate locale to prevent path traversal and cache key ambiguity
+            validatePackageIdentifier(locale, "locale");
+            dictionary = hunspellService.getDictionary(locale);
+            if (dictionary == null) {
+                throw new IllegalArgumentException(String.format(Locale.ROOT, "Unknown hunspell dictionary for locale [%s]", locale));
+            }
+        } else {
+            throw new IllegalArgumentException("missing [locale | language | lang] configuration for hunspell token filter");
         }
 
         dedup = settings.getAsBoolean("dedup", true);
@@ -73,6 +125,16 @@ public TokenStream create(TokenStream tokenStream) {
         return new HunspellStemFilter(tokenStream, dictionary, dedup, longestOnly);
     }
 
+    /**
+     * Returns the analysis mode for this filter.
+     * When {@code updateable: true} is set, returns {@code SEARCH_TIME} which enables hot-reload
+     * via the _reload_search_analyzers API.
+     */
+    @Override
+    public AnalysisMode getAnalysisMode() {
+        return this.analysisMode;
+    }
+
     public boolean dedup() {
         return dedup;
     }
@@ -81,4 +143,64 @@ public boolean longestOnly() {
         return longestOnly;
     }
 
+    /**
+     * Validates that a package identifier or locale is safe and doesn't contain
+     * path traversal sequences, separators, or other dangerous characters.
+     *
+     * @param value The value to validate (package ID or locale)
+     * @param paramName The parameter name for error messages
+     * @throws IllegalArgumentException if validation fails
+     */
+    private static void validatePackageIdentifier(String value, String paramName) {
+        if (value == null || value.isEmpty()) {
+            return; // Null/empty handled elsewhere
+        }
+
+        // Reject path traversal attempts
+        if (value.equals(".")
+            || value.equals("..")
+            || value.contains("./")
+            || value.contains("../")
+            || value.contains("\\.")
+            || value.contains("\\..")
+            || value.startsWith(".")
+            || value.endsWith(".")) {
+            throw new IllegalArgumentException(
+                String.format(Locale.ROOT, "Invalid %s: [%s]. Path traversal sequences (., ..) are not allowed.", paramName, value)
+            );
+        }
+
+        // Reject any path separators (Unix and Windows)
+        if (value.contains("/") || value.contains("\\")) {
+            throw new IllegalArgumentException(
+                String.format(
+                    Locale.ROOT,
+                    "Invalid %s: [%s]. Path separators (/, \\) are not allowed. "
+                        + "Use ref_path for package ID and locale for dictionary locale.",
+                    paramName,
+                    value
+                )
+            );
+        }
+
+        // Reject cache key separator to prevent cache key injection
+        if (value.contains(":")) {
+            throw new IllegalArgumentException(
+                String.format(
+                    Locale.ROOT,
+                    "Invalid %s: [%s]. Colon (:) is not allowed as it is used as cache key separator.",
+                    paramName,
+                    value
+                )
+            );
+        }
+
+        // Reject null bytes (security)
+        if (value.contains("\0")) {
+            throw new IllegalArgumentException(
+                String.format(Locale.ROOT, "Invalid %s: [%s]. Null bytes are not allowed.", paramName, value)
+            );
+        }
+    }
+
 }

server/src/main/java/org/opensearch/indices/analysis/AnalysisModule.java

@@ -119,7 +119,7 @@ public AnalysisModule(Environment environment, List<AnalysisPlugin> plugins) thr
         );
     }
 
-    HunspellService getHunspellService() {
+    public HunspellService getHunspellService() {
         return hunspellService;
     }