今日のひとこと

Fess 15.7.0をリリースしました。今回は、ヘッドレス用途やSPA（シングルページアプリケーション）フロントエンドを意識した新しい/api/v2 REST APIと、HTML/CSS/JavaScriptだけで検索画面を作れる静的テーマの仕組みが目玉になっています。マイルストーンを見てもらうと分かりますが、フロントエンドとAPIまわりを大きく作り直した、ボリュームのあるリリースになりました。

まず一番大きいのが、/api/v2に統一したREST APIです。これまで機能ごとにバラバラだったREST managerを、一貫したJSONエンベロープ（status、schema、data / error）にまとめました。検索やスクロール（NDJSON）、関連クエリ・関連コンテンツ、ドキュメントキャッシュ、お気に入り、クリックログ、認証（ログイン / ログアウト / me / パスワード変更）、CSRFトークン、ログインのレート制限、UI設定、そしてチャット（POSTおよびSSEストリーミング）まで、ひととおりカバーしています。OpenAPIの定義も同梱していて、入力値の上限チェック、状態を変更するリクエストへのCSRF必須化、IP単位・ユーザー単位のレート制限といったセキュリティ面の強化も合わせて入れています。

このAPI刷新にともなって、従来のv1 JSON検索API・チャットAPIは削除されました。もし既存のv1検索APIに依存している場合は、新しく用意したfess-webapp-v1-apiプラグインをインストールすると、これまでどおりの検索APIを使えるようになります。アップグレード時はこの点に注意してください。

次に、静的テーマ（Static Theme System）の仕組みを追加しました。検索画面を、JSPやActionを経由せずにWeb層から直接配信できる、自己完結したHTML/CSS/JavaScriptのバンドルとして提供できるようになっています。テーマはtheme.ymlのマニフェストでバリデーションされ、事前圧縮したアセットやキャッシュヘッダーにも対応します。ZIPアップロードでインストールでき、パストラバーサルやzip-bomb、サイズ上限といったセキュリティガードもしっかり入れてあります。管理画面には新しく「Admin → Theme」を追加して、アップロード・有効化・デフォルト設定・削除がそこから行えるようにしました。

その静的テーマを実際に動かすリファレンス実装として、Bootstrap 5ベースのテーマも同梱しています。素のES2022モジュールで作られていて、ホーム、ファセット付きの検索、詳細検索、キャッシュ表示、AIチャット、プロフィール、ヘルプといった既存の検索UIを、16言語で再現しています。そのまま使ってもいいですし、独自の検索フロントエンドを作るときの出発点としても使えるようにしています。

検索エンジン側では、OpenSearch 3.7に対応しました。バンドルしているkopfプラグインも15.7.0に合わせて更新しています。

セキュリティ周りもまとめて強化しています。状態を変更するv2リクエストにはCSRFを無条件で必須化し、ログインのスロットリングは（クライアントIP、ユーザー名）の単位に、匿名チャットのスロットリングはクライアントIP単位にスコープを切るようにしました。認証情報付きのCORSは許可リストに載せたオリジンだけに制限し、関連コンテンツのプレースホルダーでは検索クエリをエンコードして反射型XSSを防いでいます。セッションCookieにSecure属性を付けるためのsession.cookie.secureオプションも追加しました。このほか、匿名のヘルスレスポンスからcluster_nameを出さないようにしたり、v2レスポンスをデフォルトでCache-Control: no-storeにしたり、クリックのquery_idの妥当性を検証してランクの値を範囲内に収めたりと、細かいところを地道に固めています。

AI Search Mode（RAGチャット）も改善しました。大きなドキュメントから回答を生成するときに、ハイライトされたパッセージを使うようにしています。スマートサマリーは「Minimal Trail」として作り直し、フェーズごとに履歴を持つ形に見直しました。LLMのリトライ・待機・フォールバック・警告といった状態や、検索ヒット件数をブラウザに通知できるようにし、RAGのインテント処理では途中で切れたLLMレスポンスをフォールバックとして扱うようにしています。

クロール・インデックス周りでは、失敗URLとして扱うステータスコードのデフォルトにHTTP 403と410を追加しました。あわせてFessCrawlerThreadのホットパスを引き締め、API・クローラー・LLMのコード全体で正規表現パターンを事前コンパイルするようにして、処理を軽くしています。

そのほか、不具合修正として、デフォルトのGoogle Cloud Storageエンドポイントを使ったときにストレージ機能が正しく有効化されるよう直しています。

今回もコード修正からリリースノート作成、多言語ドキュメントの更新まで、Claude Codeにかなり助けてもらいました。/api/v2への統一と静的テーマの仕組みで、フロントエンドの自由度がぐっと上がっているので、ぜひ新しいFessを使ってみてください。

Fessの検索画面は、これまでJSPベースで提供してきました。デザインを大きく変えようとするとJSPやアクションに手を入れる必要があり、フロントエンドだけで完結させるのが難しい構成でした。

そこでFess 15.7で、統一されたWeb API /api/v2 と、HTML/CSS/JSだけで検索画面を構築できる静的テーマ機能を追加しました。これにより、Fessをバックエンドとして扱い、検索画面をシングルページアプリケーション（SPA）として自由に作れるようになります。

API v2 について

/api/v2 は、これまで機能ごとに分かれていたREST APIを単一のディスパッチャに統合したものです。検索・サジェスト・ラベル・お気に入り・クリックログ・認証・RAGチャットなど、検索画面を作るのに必要なエンドポイントがひと通り揃っています。

統一されたレスポンス形式

すべてのレスポンスは以下のように response でラップされた形で返ってきます。

{
  "response": {
    "status": 0,
    "...": "..."
  }
}

エラー時は以下のようになります。

{
  "response": {
    "status": 1,
    "error": {
      "code": "invalid_request",
      "message": "..."
    }
  }
}

status は 0（成功）、1（クライアントエラー）、9（システムエラー）の3種類です。error.code は invalid_request auth_required forbidden not_found rate_limited などの安定したコードになっており、クライアント側はメッセージ文字列ではなくこのコードで分岐・ローカライズします。JSONのキーはリクエスト・レスポンスともにすべてスネークケースで統一しています。

主なエンドポイント

代表的なものを挙げると以下の通りです。

検索の例は以下のような感じです。

$ curl "http://localhost:8080/api/v2/search?q=fess&num=20"

GET /api/v2/search は q（クエリ）、start / num（ページング）、sort、lang、facet.field などのパラメータを受け取り、data（ドキュメント配列）、record_count、page_count、facet_field、related_query などをまとめて返します。

UI初期化とCSRF

SPAはまず GET /api/v2/ui/config を匿名で呼び出します。ここでサイト名・機能フラグ・ソートやページサイズの選択肢・テーマ情報、そしてCSRFトークンを取得します。

状態を変更するPOST/PUT/DELETEには X-Fess-CSRF-Token ヘッダーが必須です（/auth/login のみ例外）。トークンはログイン・ログアウト・パスワード変更のたびにローテーションされます。CSRF検証は認証より前に走るため、トークンなしの更新系リクエストは401ではなく403になります。

静的テーマ機能

検索画面は「テーマ」としてファイルシステムから直接配信されます。JSPやアクションを経由しないため、ブラウザのアドレスバーのURLもそのまま保持されます。

テーマは theme.yml というマニフェストを持ちます。

apiVersion: fess.codelibs.org/v1
kind: StaticTheme
name: bootstrap
displayName: "Bootstrap"
version: "1.0.0"
author: "CodeLibs Project"
minFessVersion: "15.7"
supportedLocales: [en, ja, de, es, fr, ko, pt-BR, zh-CN]
entry: index.html
spaFallback: true
type: static
thumbnail: thumbnail.png

/themes/{name}/... でアセットが配信され、/search /help /profile /cache /chat などのSPA用パスではエントリの index.html が返されます。一方で /admin/ や /api/ などはこれまで通りFess側のルートに渡されるため、管理画面やAPIがSPAに飲み込まれることはありません。

テーマは管理画面に追加された /admin/theme/ から、ZIPでアップロードして管理します。アップロード時にはZipSlipやzip爆弾などへの対策が入っています。有効化は管理画面で theme.default にテーマ名を設定するか、バーチャルホストに紐付けて行います。

Bootstrapリファレンステーマ

標準で、Bootstrap 5ベースのリファレンステーマを同梱しています。これは既存のJSP検索画面をそのまま再現したもので、バニラのES2022モジュールで書かれています。独自テーマを作る場合は、このテーマをコピーして始めるのがおすすめです。

中心となるのが api.js で、これがそのまま使い回せるAPIラッパーになっています。

• init() … GET /ui/config を呼び、設定とCSRFトークンをキャッシュ
• get(path, params) / post(path, body) … エンベロープを検証し、status !== 0 なら ApiError を投げる。POST時はCSRFトークンを自動付与
• sseStream(path, body, onEvent, onError) … /chat/stream 向けのfetchベースのSSE（標準の EventSource はGET限定でCSRFヘッダーを送れないため独自実装）

チャットのストリーミングはこんな感じで使えます。

import * as api from "./api.js";

const ctrl = api.sseStream("/chat/stream", { q: "質問内容" }, (event) => {
  if (event.type === "chunk") bubble.textContent += event.data.content ?? "";
  if (event.type === "done")  ctrl.abort();
}, (err) => console.error(err));

なお、テーマ内では動的な文字列の innerHTML を使わず、検索結果カードやファセット、ページネーションなどはすべて document.createElement と textContent で組み立てています。XSS対策として、独自テーマでもこの方針を踏襲することをおすすめします。

検索画面を自作する流れ

独自の検索画面を作る場合は、ざっくり以下の流れになります。

1. 同梱の bootstrap テーマのディレクトリをコピーし、theme.yml の name を変更する
2. index.html（Bootstrap 5 + セマンティックなHTML）と styles.css、各JSモジュールを編集する。エンベロープ・CSRF・SSEの処理は api.js をそのまま使い回せる
3. ZIPにまとめて /admin/theme/ からアップロードし、有効化する
4. SPAは api.init() → GET /ui/config（匿名）で起動し、機能フラグとCSRFトークンを読み込んでから /api/v2 を通して検索・認証・お気に入り・チャットを動かす

v1 APIについての注意

今回の変更にあわせて、従来の /api/v1 のJSON検索APIとチャットAPIはFess本体から削除し、fess-webapp-v1-api という別プラグインに切り出しました。これは破壊的変更になります。新規の連携は /api/v2 を対象にしてください。

まとめ

API v2と静的テーマ機能により、FessをヘッドレスなバックエンドとしてHTML/CSS/JSだけで検索画面を構築できるようになりました。同梱のBootstrapテーマをベースに、自分のサイトに合わせた検索画面を作ってみてください。