Web 開発サーバー

spring_flutter_web ビルダーは、lib/resources/ の spring.flutter.web.dev-server.* プロパティから、flutter run -d chrome と flutter run -d web-server が読むファイル web_dev_config.yaml を書き出します。ポート、ホスト、HTTPS、ヘッダー、プロキシのルールを、アプリの他の設定と同じ場所で設定すると、Flutter のツールがそれらを使います。

使う理由

設定がなければ、Flutter のツールは Web 版をランダムなポートで配信します。固定のオリジンを必要とするものはたくさんあります。サーバーの CORS のリスト、SSO ログイン後のリダイレクト、ブックマークです。Flutter 3.38 以降、開発サーバーはプロジェクトのディレクトリの web_dev_config.yaml を読み、それ以外にそれを設定するものはありません。そのコマンドラインのフラグ (--web-port、--web-hostname) は引き続きファイルより優先されます。

そのファイルを手で書くと、アプリの設定がすでに知っている値のための第二の場所ができてしまいます。ビルダーはそれを代わりに書き、プロパティと同期させ、プロパティがなくなると削除します。

アプリ自身はこれらのキーを読まず、flutter build web もそれらを使いません。それらが設定するのは開発サーバーだけです。

例

# lib/resources/application-web.yaml
spring:
  flutter:
    web:
      dev-server:
        host: localhost
        port: 5050
        base-href: /shop/
        headers:
          Cross-Origin-Opener-Policy: same-origin
        proxy:
          - prefix: /api/
            target: http://localhost:8080
          - regex: ^/auth/(.*)
            target: http://localhost:9000
            replace: /$1

dart run build_runner build は、pubspec.yaml の隣に次のように書き出します。

# GENERATED FILE - DO NOT MODIFY BY HAND.
#
# Written by spring_core_dart_generator from the
# spring.flutter.web.dev-server.* properties in lib/resources/
# (application.yaml, application-web.yaml,
# ...). Change those properties instead: this file is rewritten on
# every build, and deleted when the properties are removed.
# The Flutter tool reads it when it runs the web version
# (flutter run -d chrome / -d web-server); --web-port and the other
# flags still win over it.
server:
  host: "localhost"
  port: 5050
  headers:
    - name: "Cross-Origin-Opener-Policy"
      value: "same-origin"
  proxy:
    - prefix: "/api/"
      target: "http://localhost:8080"
    - regex: "^/auth/(.*)"
      target: "http://localhost:9000"
      replace: "/$1"
  base-href: "/shop/"

セクションは常に host、port、https、headers、proxy、base-href の順に並びます。テキストは JSON 文字列として書かれるので、値が YAML を壊すことはありません。値のないセクションは省略されます。

このサイトはポートだけを application.yml で設定しています (プロファイルのないファイルはブラウザーでも読まれます)。

# neon_farum_azula: lib/resources/application.yml
spring:
  flutter:
    web:
      dev-server:
        port: 5110

そして、上のヘッダーと次の内容を持つファイルを受け取ります。

server:
  port: 5110

/api/ をサーバーに転送するのは、開発中に CORS やサードパーティー Cookie のトラブルを避ける最も簡単な方法です。ページと API が一つのオリジンを共有するので、セッションのログインがどのブラウザーでも動きます。

ビルダーが書き出すとき、何もしないとき

ビルダーは、純粋な Dart サーバーも含め、ジェネレーターに依存するすべてのパッケージで動きます。そのため、開発サーバーを使わないパッケージで失敗したり何かを言ったりしてはなりません。四つの段階で判断します。

  1. 設定を読み込まずに、さっと見る。 lib/resources/ のすべての .properties、.yml、.yaml ファイルを、どのプロファイルに属するかにかかわらず、すべてのドキュメントについて解析します。resources:dev.conf[.yaml] や resources:web.properties[encoding=iso-8859-1] のように、インポートがファイルのヒント付きで指定するファイルも、その形式とエンコーディングで解析します (UTF-8 でないファイルはこの方法でだけ読まれます)。そのようなインポートの中のプレースホルダーは、デフォルトか、ファイルの値で解決されます (resources:${ENV:dev}.conf[.yaml])。実行中のアプリだけが知るもの (resources:${ENV}.conf[.yaml]) はたどれないので、そのファイルでだけ設定されたキーは数えられません。
  2. 古いキーはビルドを失敗させる。 spring.flutter.web. の下で、dev-server、seo、page の下にないキーは、バージョン 0.7.1 より前の開発サーバーのキーです。ビルドは失敗し、それを示します: spring.flutter.web.port (lib/resources/application-web.yaml): the dev server's keys moved under spring.flutter.web.dev-server; write spring.flutter.web.dev-server.port.
  3. 何もすることがない。 どのファイルも spring.flutter.web.dev-server.* キーも spring.flutter.security.web.mode も設定していなければ、設定はまったく読み込まれません。何も書き出されず、ビルダーが以前に生成したファイルは削除され、設定の他の何か (インポート、プレースホルダー、解析できないファイル) はビルダーの関知するところではありません。アプリ自身の起動がそれを報告します。例外が一つあります。生成された web_dev_config.yaml が存在する間は、解析できない設定ファイルがキーを持っていたものかもしれないので、設定が読み込まれ、アプリがそのファイルを読むなら、ビルドは失敗し、生成ファイルは残されます。
  4. 本当の読み込み。 それ以外では、アプリがブラウザーで読み込むのと同じように設定が読み込まれ (次の節)、その結果から spring.flutter.web.dev-server.* の値が取られます。読み込まれた設定にそれらが一つもなく (たとえば、アクティブでないプロファイルのファイルにだけある)、アプリが spa モードでもなければ、書くものはなく、生成ファイルは削除されます。

設定の読み方

ビルダーは、web プラットフォームのプロファイルを有効にして、アプリケーションと同じ設定ローダーを使います。

ビルドが知りえないものは、意図的に除外されます。

ケース ビルダーが行うこと
環境変数と --dart-define の値 読まない。ビルドは実行されるマシンに依存してはならない
spring.profiles.active、.include、.default、.group.* の中の、それらだけが解決するプレースホルダーを含むプロファイル名 名前が他に何を含んでいても除外し (dev,${ENV}-eu は dev として読まれる)、警告する。デフォルト (${APP_PROFILE:dev}) は使われる
そのようなプレースホルダーを含む spring.profiles.validate や spring.main.cloud-platform 未設定として読み、警告する
そのようなプレースホルダーを含むインポートの場所 読まない (その ; グループの他のエントリーは読む)。警告する
spring.config.activate.on-profile や .on-cloud-platform にそのようなプレースホルダーを含むドキュメント スキップし、警告する
ワイルドカードの有無にかかわらず、file:、configtree:、package: のインポート、または絶対パス optional: かどうかにかかわらずスキップする。ブラウザーにはファイルシステムがないため。書き出すファイルがある場合、Web 版がそれで起動に失敗するので、最初の必須のものを示して警告する
asset:、http:、https: のインポート、または lib/resources/ にない resources: のファイル 必須のものでも黙ってスキップする。実行時には存在するかもしれないため

キーを置ける場所は引き続きチェックされます。application-web.yaml の spring.profiles.active は、アプリの起動を失敗させるのと同じく、値にかかわらずビルドを失敗させます。spring.flutter.web.dev-server.* の値や spring.flutter.security.web.mode の中のプレースホルダーは、ビルド時に解決できなければならず、そうでなければビルドは失敗します。

spring.flutter.web.dev-server.port (in lib/resources/application-web.yaml): '${PORT}' cannot be
resolved at build time (...). The dev server is configured when the app is built, so only config
files count, not --dart-define or environment variables.

同じキーが複数のファイルで設定されている場合、アプリで優先されるファイルがここでも優先されます。application-web.yaml は application.yaml より、プロファイルのファイルは両方より優先されます。ヘッダーはファイル間でマージされ、各ヘッダーは優先されるファイルが決めます (名前は大文字小文字を区別せずに比較)。proxy のリストは、Spring Boot のリストと同じく、それを持つ優先されるファイルから丸ごと来ます。

手で書いたファイル

web_dev_config.yaml は宣言されたビルドの出力ではありません。もしそうなら、build_runner は同名の手書きのファイルを上書きし、ビルダーが書き出すのをやめるたびにそのファイルを削除してしまいます。そこでビルダーは自分でファイルを管理し、最初の行が # GENERATED FILE - DO NOT MODIFY BY HAND. であるファイルだけを変更します。

プロパティ ディスク上のファイル 結果
設定あり なし、または生成されたもの ファイルが書き出される。テキストが変わったときにだけ書き直される
設定あり 手で書いたもの ビルドは失敗し、どちらかを取り除くよう求める。ファイルはそのまま
なし 生成されたもの ファイルは削除される
なし 手で書いたもの 何も起きない
不正な値 任意 ビルドは失敗し、プロパティを示す。ファイルはそのまま
アプリが読む設定ファイルを解析できない 任意 ビルドは失敗する。ファイルはそのまま

手書きのファイルからプロパティに切り替えるには、ファイルを削除し、dart run build_runner clean を実行するか、lib/resources/ のファイルを変更します。

再び動くとき

build_runner は、lib/resources/ のファイルが変わるとビルダーを再び実行します。ビルドのソースではない web_dev_config.yaml は監視しません。ファイルを削除すると、dart run build_runner clean か lib/resources/ の変更の後にだけ戻ってきます。

プロパティ

すべてのキーは省略可能です。表は spring.flutter.web.dev-server. の下のキーを示します。

キー 型 デフォルト 書かれる形 意味
host 空でないテキスト Flutter のツールのもの server.host 待ち受けるアドレス: localhost、またはネットワーク上の他のデバイス向けの 0.0.0.0
port 整数、0 から 65535 空いているポート server.port ポート。0 は空いているポートを選ぶ
base-href / で始まり / で終わるパス / server.base-href アプリが配信されるパス (/shop/)
https.cert-path ファイルパス なし (HTTP) server.https.cert-path TLS 証明書 (PEM)。cert-key-path と一緒に設定するか、どちらも設定しない
https.cert-key-path ファイルパス なし server.https.cert-key-path 証明書の秘密鍵 (PEM)
headers.<Name> テキスト なし server.headers すべての応答に追加されるヘッダー
proxy[n].target 絶対 URL なし server.proxy[n].target ルール n のリクエストの行き先 (http://localhost:8080)。すべてのルールで必須
proxy[n].prefix パス なし server.proxy[n].prefix ルール n は、それで始まるパスに一致する (/api/)
proxy[n].regex 正規表現 なし server.proxy[n].regex または、それに一致するパス。各ルールは prefix と regex のちょうど一つを設定する
proxy[n].replace テキスト パスはそのまま server.proxy[n].replace 転送されるパス: 一致した部分が置き換えられる。$1 は最初のグループ
content-security-policy 空でないテキスト なし。spa モードでは既製のポリシー ヘッダー ページの Content Security Policy。Content-Security-Policy として送られる
content-security-policy-report-only true / false false ヘッダーの名前 ポリシーを Content-Security-Policy-Report-Only として送る: 違反はコンソールにログが出るだけで、何もブロックされない
content-security-policy-connect-src オリジンのリスト なし ポリシーの中 spa モードの既製のポリシーの connect-src に追加されるオリジン

ビルダーは、spring.flutter.security.web.mode (spa モード。下記)、spring.security.oauth2.client.* キー (spa モードのポリシーのオリジン)、そして spring_boot_starter_flutter に依存するアプリではテーマの splash (ページローダーのスクリプトを許可するため) も読みます。

チェック

問題 結果
https.cert-key-path なしの https.cert-path、またはその逆 ビルドエラー: HTTPS needs both https.cert-path and https.cert-key-path
host が空 ビルドエラー
port が 0 から 65535 の整数でない ビルドエラー
ブラウザーが拒否する port (ERR_UNSAFE_PORT: 1、22、25、5060、6000、6665 から 6669、10080、その他 Fetch 標準のリストにあるもの) 警告: アプリはブラウザーで開かない
/ で始まり / で終わらない base-href ビルドエラー
target のない、または target が絶対 URL でないプロキシのルール ビルドエラー
prefix と regex の両方、またはどちらもないプロキシのルール ビルドエラー
有効な正規表現でない regex パーサーのメッセージとともにビルドエラー
content-security-policy が空 ビルドエラー
content-security-policy と headers.Content-Security-Policy (または -Report-Only) の両方が設定されている ビルドエラー: 一つを残す
content-security-policy-report-only が true でも false でもない ビルドエラー
オリジンでないエントリー (https://api.example.com、wss://api.example.com の形でないもの) を含む content-security-policy-connect-src ビルドエラー
独自のポリシーと並んだ content-security-policy-connect-src ビルドエラー: オリジンはそのポリシーに入れる
spa モードなしの content-security-policy-connect-src 警告: 無視される
未知の spring.flutter.web.dev-server.* キー (prot) 既知のキーを列挙する警告。他は何も変わらない

Content Security Policy

Content Security Policy は、ページがどのスクリプト、スタイル、接続を使えるかをブラウザーに伝えるので、ページに注入されたスクリプトは拒否されます。content-security-policy を設定すると、flutter run のすべての応答がそれを持つので、開発は本番が送るポリシーの下で行われます。

ブラウザーが自分でログインするアプリ (spring.flutter.security.web.mode: spa) で、ポリシーを設定していないものは、既製のポリシーを受け取ります。ビルダーは、dev-server キーが一つもなくても、そのためのファイルを書き出します。

# lib/resources/application-web.yaml
spring:
  flutter:
    security:
      web:
        mode: spa
server:
  headers:
    - name: "Content-Security-Policy"
      value: "default-src 'self'; script-src 'self' 'wasm-unsafe-eval' https://www.gstatic.com; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' https://fonts.gstatic.com; connect-src 'self' https://www.gstatic.com https://fonts.gstatic.com; worker-src 'self' blob:; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'"

各部分は Flutter の Web エンジンのためにあり、それ以上のものはありません。

ディレクティブ 理由
script-src 'self' 'wasm-unsafe-eval' https://www.gstatic.com アプリのスクリプトと、Flutter の CDN からの CanvasKit。'wasm-unsafe-eval' は CanvasKit と Skwasm の WebAssembly をコンパイルする。JavaScript の eval もインラインスクリプトもない
style-src 'self' 'unsafe-inline' Flutter のエンジンが <style> 要素を書く
https://fonts.gstatic.com を含む font-src と connect-src エンジンが取得するフォールバックのフォント
worker-src 'self' blob: Skwasm のワーカー
img-src 'self' data: blob: アプリの画像
object-src 'none'、base-uri 'self'、form-action 'self'、frame-ancestors 'none' プラグインなし、外部の <base> やフォームの送信先なし、他のサイトによるフレーム化なし

connect-src は、ビルドが知りうる、ログインが fetch するオリジンも受け取ります。

認可エンドポイントはリストにありません。ページはそこへ遷移するのであって、fetch はしないからです。その他の issuer のディスカバリードキュメントは実行時に読まれるので、それが別のホストで指定するエンドポイントはビルドからはわかりません。そのホストを、アプリが呼ぶ API とともに content-security-policy-connect-src に列挙してください。

# lib/resources/application-web.yaml
spring:
  flutter:
    web:
      dev-server:
        content-security-policy-connect-src:
          - https://api.neon.books
          - wss://api.neon.books

アプリが spring_boot_starter_flutter に依存し、そのアクティブなテーマに splash がある場合、web/index.html は ページローダー のインラインスクリプトを持ちます。その場合、既製のポリシーはそのスクリプトのハッシュを script-src に追加します。spring.flutter.web.page.swipe-to-close: false と spring.flutter.web.page.max-pixel-ratio がページに書き込むインラインスクリプトのハッシュも、設定されていれば追加します。各スクリプトはタグの間に他に何もなく書かれるので、ブラウザーが計算するハッシュは一致します。独自のポリシーでは、ハッシュを自分で追加してください (WebPageLoader.scriptHash、WebPageHead.hashOf)。

ホットリロードはデバッグ実行でコードを評価しますが、厳しいポリシーはそれを禁じます。それが邪魔になる場合は、開発用のプロファイルで content-security-policy-report-only: true を使ってください。開発サーバーは本番ではありません。build/web を配信するサーバーや CDN から同じポリシーを送ってください。

Spring (Java) との対応

Spring には相当するものがありません。Spring Boot の Web アプリケーションはそれ自体がサーバー (server.port) であり、その開発ツールに別のファイルは必要ありません。このビルダーが存在するのは、開発中の Flutter Web アプリがアプリではなく Flutter のツールによって配信されるからです。

関連項目