
# セッション

セッションは、ショッピングカートやログイン中のユーザーのように、一つのクライアントのデータをリクエストをまたいで保持します。データはサーバーに残り、クライアントが持つのは Cookie (デフォルトでは `JSESSIONID`) の中のランダムな ID だけで、それを各リクエストで送り返します。リクエストを持つコードは、`request.getSession()` でセッションを取得します。

## 使う理由

HTTP は二つのリクエストの間ですべてを忘れます。ブラウザーには、自分が誰かをサーバーに覚えてもらう必要があります。セッションは、ユーザーが読んだり変更したりできるブラウザーにデータを置かずに、これを実現します。

セッションはブラウザー向けに使います。カート、複数ページにわたるウィザード、フォームによるログインなどです。プログラムから呼ばれる API は通常、各リクエストでトークン (Bearer トークン) を送るので、セッションは不要です。セキュリティスターターは、フォームや OAuth2 によるログインの後にログイン中のユーザーをセッションに保持し、セッションを作るのはログイン時だけです。

## 例

```dart
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

@RestController()
@RequestMapping('/cart')
class CartController {
  // 訪問者ごとに、セッションと同じだけ存続するカートを持つ。
  @PostMapping('/items')
  List<String> add(ServerHttpRequest request, @RequestParam() String item) {
    final session = request.getSession()!;
    final cart = session.getAttribute('cart') as List<String>? ?? [];
    final updated = [...cart, item];
    session.setAttribute('cart', updated);
    return updated;
  }

  // セッションを作らずに見る: セッションのない訪問者にはカートがない。
  @GetMapping('/items')
  List<String> items(ServerHttpRequest request) =>
      request.getSession(create: false)?.getAttribute('cart') as List<String>? ??
      const [];

  // カートを空にして訪問者を忘れる。
  @PostMapping('/clear')
  void clear(ServerHttpRequest request) =>
      request.getSession(create: false)?.invalidate();
}

@RestController()
class LoginController {
  @PostMapping('/login')
  Future<void> login(ServerHttpRequest request, @RequestParam() String user) async {
    // ... パスワードを確認する ...
    // ログイン後に新しい ID にする: 以前に誰かが見た ID は使えなくなる。
    if (request.getSession(create: false) != null) {
      await request.changeSessionId();
    }
    request.getSession()!.setAttribute('user', user);
  }
}
```

```yaml
# lib/resources/application.yaml
server:
  session:
    timeout: 15m             # リクエストがない場合。デフォルトは 30m
    max-sessions: 50000      # デフォルトは 10000。-1: 上限なし
    cookie:
      name: SHOPSESSION      # デフォルトは JSESSIONID
      same-site: strict      # デフォルトは lax
      secure: true           # デフォルト: リクエストがセキュアならセキュア
```

最初に `getSession()` を呼んだリクエストは、次のものを受け取ります。

```text
Set-Cookie: SHOPSESSION=k3Jx...; Path=/; Secure; HttpOnly; SameSite=Strict
```

## セッションの取得

`request.getSession()` と以下の他のメンバーは、`ServerHttpRequest` の拡張です。リクエストを持つどのコードでも動きます。コントローラー (`ServerHttpRequest` パラメーターを受け取る)、セッションフィルターの後に実行されるフィルター、インターセプター、または `RequestContextHolder.currentRequest` を通してどこからでも使えます。

| メンバー | 意味 |
|---|---|
| `HttpSession? getSession({bool create = true})` | リクエストのセッション。セッションがない場合、`create: true` (デフォルト) なら新しいセッションを作り、その Cookie をレスポンスで送る。`create: false` なら `null` を返す。インメモリのリポジトリのように即座に応答するリポジトリで動く。 |
| `Future<HttpSession?> getSessionAsync({bool create = true})` | 同じものを、`Future` で応答するリポジトリも含め、どのリポジトリでも使える形で。 |
| `Future<String> changeSessionId()` | セッションに新しい ID を与え、値は保ち、新しい ID を Cookie で送り、それを返す。リクエストにセッションがなければ `StateError` を投げる。 |
| `String? requestedSessionId` | クライアントが Cookie で送った ID。有効かどうかは問わない。Cookie がなければ `null`。 |
| `bool isRequestedSessionIdValid` | その ID が、このリクエストが使うセッションを指しているかどうか。未知、期限切れ、無効化済み、またはこのリクエスト中に変更された場合は `false`。 |

ルール:

- ハンドラーは `HttpSession` パラメーターを受け取れません。`ServerHttpRequest` を受け取って `getSession()` を呼んでください。
- スターターのセッションフィルターがない場合 (ディスパッチャーの外で手作りしたリクエスト)、これらのメンバーは `StateError` を投げます。
- `Future` で応答するリポジトリでは、セッションを作る必要がある場合に `getSession()` が `StateError` を投げます。`getSessionAsync()` を使ってください。
- **Cookie はレスポンスヘッダーと一緒に送られます。** レスポンスが始まる前、つまりストリームや `StreamingResponseBody` が最初のバイトを書く前にセッションを作ってください。その後に作られたセッションには Cookie が付きません (警告がログに記録されます)。
- **ID をクライアントが選ぶことはありません。** Cookie の未知の ID は無視され、後で作られるセッションには新しいランダムな ID が付きます。そのため、攻撃者が被害者のブラウザーに ID を仕込むこと (セッション固定) はできません。128 文字を超える ID は検索せずに無視されます。

## `HttpSession`

| メンバー | 意味 |
|---|---|
| `id` | Cookie が運ぶ ID。256 ビットのランダム値を base64url で表したもの (43 文字)。`changeSessionId()` で変わる。 |
| `creationTime` | セッションが作られた時刻。 |
| `lastAccessedTime` | このセッションで最後にリクエストが来た時刻。タイムアウトはここから数える。 |
| `maxInactiveInterval` | リクエストがない状態でセッションが存続する時間 (`server.session.timeout`)。このセッションだけのタイムアウトを変えるには設定する。ゼロまたは負の値なら期限切れにならない。 |
| `isNew` | このリクエストがセッションを作ったかどうか。つまり、クライアントがまだそれを知らないかどうか。 |
| `getAttribute(name)` | `name` に保存された値、または `null`。 |
| `setAttribute(name, value)` | `value` を保存する。`null` なら名前を削除する。インメモリのリポジトリはコピーではなくオブジェクトそのものを保持する。 |
| `removeAttribute(name)` | 値を削除する。 |
| `attributeNames` | 保存された値の名前 (コピー)。 |
| `invalidate()` | ログアウトと同じようにセッションを終える。値は破棄され、その ID は二度と受け付けられない。 |
| `isInvalidated` | セッションが終わっているかどうか (無効化済みまたは期限切れ)。 |

- 無効化されたセッションを使う (`getAttribute`、`setAttribute`、`removeAttribute`、`attributeNames`、`invalidate`) と `StateError` が投げられます。
- `invalidate()` の後も Cookie はブラウザーに残ります。次のリクエストには単にセッションがありません。同じリクエストでの `getSession()` は新しいセッションを作ります。
- リポジトリが保持できる値を保存してください。インメモリなら何でも動きます。データベースに書き込むリポジトリには、シリアライズできる値が必要です。

## ログイン後: `changeSessionId`

ログイン前のセッション ID は、共有のコンピューター、ログ、ページ上のスクリプトなどを通じて、他の誰かに見られているかもしれません。ログイン後、セッションはユーザーを保持します。ログインに成功したらすぐに `await request.changeSessionId()` を呼んでください。セッションはデータを保ちます (カートは残ります) が、古い ID は使えなくなり、レスポンスで新しい ID が送られます。セキュリティスターターは、`sessionFixation(changeSessionId: false)` で無効にしない限り、自身のログインでこれを行います。

## 期限切れとセッションの上限

- セッションは、リクエストがないまま `maxInactiveInterval` が過ぎると期限切れになります。期限切れのセッションは、リクエストがそれを見つけたときに削除されます。また、セッションが作られるときに、期限切れのものすべてが最大で 1 分に 1 回削除されます。
- 保持されるセッションは最大 `server.session.max-sessions` 個です。上限に達すると、新しいセッションはまず期限切れのものをすべて削除します。それでもストアが満杯なら、新しいセッションは **拒否されます**。`getSession()` は `TooManyActiveSessionsException` を投げ、リクエストは `503 Service Unavailable` になり、警告がログに記録されます (`Session limit 10000 reached: refused a new session (raise server.session.max-sessions)`)。警告は最大で 1 分に 1 回です。有効なセッションが場所を空けるために削除されることはありません。
- この上限は、クライアントがセッションを開いてメモリを使い果たすことを防ぎます。セキュリティスターターでは、匿名のリクエストはセッションを作りません。ログイン中のユーザーだけで上限に達する場合は、上限を引き上げてください。

## プロパティ

### `server.session.timeout`

| 型 | デフォルト |
|---|---|
| `Duration` | `30m` |

リクエストがない状態でセッションが存続する時間です。単なる数値は **秒** (`1800`) で、単位も使えます (`15m`、`8h`)。セッションを伴う各リクエストで時間が最初から数え直されます。機密性の高いアプリケーションでは短くし (銀行: `5m`)、長い中断の後も残すべきカートでは長くします。ゼロまたは負の値なら、セッションは期限切れになりません (その場合は `invalidate()` でしか削除されず、ずっと `max-sessions` に数えられます)。

```yaml
server:
  session:
    timeout: 15m
```

### `server.session.max-sessions`

| 型 | デフォルト |
|---|---|
| `int` | `10000` |

インメモリのリポジトリが同時に保持するセッションの最大数です。`-1` で上限なし。上限に達したときの動作は前述のとおりです。同時にログインするユーザーが多い場合は引き上げてください。メモリの見積もりも必要です。各セッションは自身の属性を保持します。独自のリポジトリ Bean は、独自に数を管理します。

```yaml
server:
  session:
    max-sessions: 50000
```

### `server.session.cookie.name`

| 型 | デフォルト |
|---|---|
| `String` | `JSESSIONID` |

セッション Cookie の名前です。同じホスト上の二つのアプリケーションが同じ名前を共有してしまう場合や、サイトを動かす技術を外部に知らせたくない場合に変更します。空の値はデフォルトになります。

### `server.session.cookie.domain`

| 型 | デフォルト |
|---|---|
| `String` | なし |

Cookie の `Domain` です。指定しなければ、ブラウザーは Cookie を設定したホストにだけ送り返します。これが最も安全な選択です。同じセッションストアで提供されるサブドメイン (`shop.example.com`、`account.example.com`) の間でセッションを共有するには設定します (`example.com`)。

### `server.session.cookie.path`

| 型 | デフォルト |
|---|---|
| `String` | コンテキストパス、または `/` |

Cookie の `Path`、つまりブラウザーが Cookie を送るパスです。デフォルトは `server.context-path` (`/shop`) または `/` です。サイトの一部だけがセッションを使う場合は狭めてください。

### `server.session.cookie.http-only`

| 型 | デフォルト |
|---|---|
| `bool` | `true` |

Cookie を `HttpOnly` にして、ページのスクリプトから隠すかどうかです。`true` のままにしてください。そうすれば、ページに注入されたスクリプト (XSS) がセッション ID を盗めません。

### `server.session.cookie.secure`

| 型 | デフォルト |
|---|---|
| `bool` | 未設定 |

Cookie を `Secure` にして、HTTPS でだけ送り返させるかどうかです。未設定の場合はリクエストごとに決まり、リクエストが HTTPS で来たならセキュアになります。TLS を終端するリバースプロキシの背後では、サーバーには `http` に見えます。`server.forward-headers-strategy` を設定してリクエストが HTTPS だったことを分かるようにする ([リバースプロキシの背後で](server/reverse-proxy.md) を参照) か、このキーを `true` にしてください。`false` にするのは、平文の HTTP によるローカル開発のときだけにしてください。その場合はそもそも必要ありません。

### `server.session.cookie.same-site`

| 型 | デフォルト |
|---|---|
| `lax`、`strict`、`none`、`unset` | `lax` |

Cookie の `SameSite` 属性です。他のサイトから来るリクエストにブラウザーが Cookie を付けるかどうかを決めます。

| 値 | ヘッダー | 意味 |
|---|---|---|
| `lax` | `SameSite=Lax` | サイト内のリクエストと、他のサイトからのトップレベルのナビゲーション (リンク) で送られる。クロスサイトの `POST` や `fetch` では送られない。ほとんどの CSRF を防ぐ。 |
| `strict` | `SameSite=Strict` | サイト内のリクエストでだけ送られる。他のサイトからのリンクは、セッションなしで到着する。 |
| `none` | `SameSite=None` | クロスサイトも含め、すべてのリクエストで送られる。ブラウザーは同時に `Secure` を要求する。他のサイトがあなたのサイトを埋め込む (iframe) 場合や、認証情報付きで呼ぶ場合に必要。 |
| `unset` | なし | 属性なし。ブラウザーのデフォルト (現在のブラウザーでは Lax)。 |

それ以外の値では起動が止まります。

```yaml
server:
  session:
    cookie:
      same-site: none
      secure: true
```

## セッションの保存場所

スターターは三つの Bean を宣言します。

| Bean | 型 | 役割 |
|---|---|---|
| `httpSessionRepository` | `InMemoryHttpSessionRepository` | アプリケーションが `HttpSessionRepository` を宣言しない限り、セッションを保持する。 |
| `httpSessionManager` | `HttpSessionManager` | Cookie を読み、セッションを見つけ、Cookie を書く。 |
| `httpSessionFilter` | `HttpSessionFilter` | 各リクエストにセッションを結び付ける。順序 `-1000` で、セキュリティのフィルターチェーン (`-100`) の前。 |

メモリ上のセッションは、プロセスが止まると失われ、アプリケーションの複数のインスタンス間で共有されません。再起動後も残すため、またはロードバランサーの背後で共有するために、データベースや Redis に保持するには、独自の `HttpSessionRepository` Bean を宣言します。インメモリのものは身を引きます。

| `HttpSessionRepository` | 意味 |
|---|---|
| `createSession()` | 新しいランダムな ID を持つ、新しい空の `StoredHttpSession` (`newSessionId()` で ID を作れる)。スターターはその後、`server.session.timeout` からタイムアウトを設定する。 |
| `findById(id)` | この ID を持つ有効なセッション。未知、無効化済み、期限切れなら `null`。Cookie を持つリクエストごとに一回呼ばれる。 |
| `changeSessionId(session)` | 値を保ったまま、セッションに新しい ID を与え、古い ID を忘れる。 |
| `deleteById(id)` | セッションを削除する。 |

各メソッドは値または `Future` を返せます (`FutureOr`)。`Future` を返す場合、コードは `getSessionAsync()` を使う必要があります。

`StoredHttpSession` は、リポジトリに必要なものを備えた `HttpSession` です。`touch(now)` はリクエストを記録し (`lastAccessedTime`)、`isNew` はマネージャーが設定し、`isExpired(now)` はセッションが `maxInactiveInterval` より長く使われていないかどうかを返します。

```dart
@Configuration()
class SessionConfig {
  // アプリケーションのデータベースにセッションを置き、すべてのインスタンスで共有する。
  // DatabaseSessions はアプリケーション独自の実装。
  @Bean()
  HttpSessionRepository httpSessionRepository(Database database) =>
      DatabaseSessions(database);
}
```

`InMemoryHttpSessionRepository({timeout, maxSessions, clock})` は、時間を制御するテストのために `clock` を受け取ります。

```dart
var now = DateTime(2026);
final repository = InMemoryHttpSessionRepository(
  timeout: const Duration(minutes: 5),
  clock: () => now,
);
final session = repository.createSession();
now = now.add(const Duration(minutes: 6));
expect(repository.findById(session.id), isNull);
```

## isolate のプールがある場合

`server.isolates.count` が 1 より大きいと、すべての isolate がアプリケーション全体を実行するので、すべての isolate が自分の `InMemoryHttpSessionRepository` を持ちます。リクエストはどの isolate にも届く可能性があります。

- **ある isolate が作ったセッションを、他の isolate は知りません。** ユーザーは、あるリクエストではログインしていて、別のリクエストではしていません。カートは、いっぱいだったのに空になります。
- **ID を知らない isolate は、それを未知の ID と同じように扱います。** ID は無視され、その isolate がセッションを作ると、その新しい Cookie がブラウザーの古いものを置き換えます。
- **`server.session.max-sessions` は isolate ごとに数えます。**
- **一つの接続でのテストでは、これは現れません。** キープアライブされた接続のリクエストは、それを受け取った isolate にとどまります。ブラウザーは複数の接続を開きます。

プールは、最初に isolate を追加するときに、一度だけ次のように知らせます。

```text
Each isolate keeps its own sessions in memory, and a request may reach any isolate: what one keeps the others do not see. Keep it where all of them do (a database, a shared store), or accept one copy per isolate.
```

セッションは、isolate ごとに一つのコピーでは成り立ちません。すべての isolate から見える場所にセッションを保つ `HttpSessionRepository` Bean を、[上](#セッションの保存場所) のように宣言してください。インメモリのものは身を引き、警告はセッションを挙げなくなります。[isolate のプール](server/isolates.md#isolate-が複数になると変わること) を参照してください。

## Spring (Java) との対応

```java
@PostMapping("/cart/items")
void add(HttpSession session, @RequestParam String item) {
  List<String> cart = (List<String>) session.getAttribute("cart");
  ...
  session.setAttribute("cart", cart);
}
```

```properties
server.servlet.session.timeout=15m
server.servlet.session.cookie.name=SHOPSESSION
```

重要な違い:

- キーは `server.servlet.session.*` ではなく `server.session.*` です。サーブレットコンテナーはありません。
- `HttpSession` パラメーターはありません。`request.getSession()` を呼んでください。
- Cookie はデフォルトで `SameSite=Lax` です。Spring Boot は `SameSite` を未設定のままにします。
- セッションの数には上限があります (`max-sessions`、10000)。Spring Boot にはそのようなキーはなく、Tomcat の `maxActiveSessions` はデフォルトで無制限です。上限に達すると、期限切れのセッションが削除され、それでも新しいセッションは `503` で拒否されます。WebFlux の `InMemoryWebSessionStore` と同じ動作です。
- 独自のリポジトリは `HttpSessionRepository` Bean です。Spring ではそのために Spring Session を使います。

## 関連項目

- [ヘッダーとクッキー](controllers/headers-and-cookies.md)
- [フィルター](filters.md)
- [リバースプロキシの背後で](server/reverse-proxy.md)
- [isolate のプール](server/isolates.md)
- [Durations](../spring-core-dart/conversion/durations.md)
- [すべてのプロパティ](properties.md)
