
# 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` もそれらを使いません。それらが設定するのは開発サーバーだけです。

## 例

```yaml
# 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` の隣に次のように書き出します。

```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` で設定しています (プロファイルのないファイルはブラウザーでも読まれます)。

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

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

```yaml
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` プラットフォームのプロファイルを有効にして、アプリケーションと同じ設定ローダーを使います。

- `application.*`、次に `application-web.*`。
- それらの中で `spring.profiles.active` が指定するプロファイルのファイル。`include`、`default`、`group` はアプリと同じように扱われます。
- `spring.config.import` が指定するファイル。`lib/resources/` からの相対パスと `resources:` の場所です。
- これらのファイルから解決されるプレースホルダー。緩い名前はアプリと同じように照合されます。

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

| ケース | ビルダーが行うこと |
|---|---|
| 環境変数と `--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` の中のプレースホルダーは、ビルド時に解決できなければならず、そうでなければビルドは失敗します。

```text
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` キーが一つもなくても、そのためのファイルを書き出します。

```yaml
# lib/resources/application-web.yaml
spring:
  flutter:
    security:
      web:
        mode: spa
```

```yaml
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 するオリジンも受け取ります。

- すべての `spring.security.oauth2.client.provider.<id>` の URI (issuer、token、user info、keys) のオリジン。
- 独自の provider セクションを持たない Google、GitHub、Facebook、Apple の登録の組み込みのエンドポイント (Google の `https://www.googleapis.com`)。ただし独自のセクションが置き換えるものを除く。セクションに `issuer-uri` があればなし。
- Google や Microsoft の issuer では、ディスカバリードキュメントが issuer の他に指定するホスト (`https://oauth2.googleapis.com`、`https://openidconnect.googleapis.com`、`https://www.googleapis.com`。`https://graph.microsoft.com`)。
- 続いて `content-security-policy-connect-src` のオリジン。

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

```yaml
# 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` は [ページローダー](page-loader.md) のインラインスクリプトを持ちます。その場合、既製のポリシーはそのスクリプトのハッシュを `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 のツールによって配信されるからです。

## 関連項目

- [ページローダー](page-loader.md)
- [検索エンジン向けのページ](seo.md)
- [ビルドが読むプロパティ](../build-properties.md)
- [プロファイル](../../spring-core-dart/config/profiles.md)
- [プレースホルダー](../../spring-core-dart/config/placeholders.md)
