# turnbase-session - Complete API Documentation

> The Session port for Turnbase: in-memory and file-backed hosts behind one request/response interface

**Version:** 0.0.0
**Authors:** Matan Lurey <matan@lurey.org>
**License:** MIT OR Apache-2.0
**Repository:** https://github.com/crates-lurey-io/turnbase
**Keywords:** game-engine, turn-based, deterministic, gamedev, ai

Generated: 2026-07-25 17:07:54 UTC  
Created by: [cargo-llms-txt](https://github.com/masinc/cargo-llms-txt)

## Table of Contents

### src/lib.rs

- pub use file::{Error, FileSession}
- pub use local::LocalSession
- pub trait Session

### src/local.rs

- pub struct LocalSession
- impl LocalSession
- impl Session for LocalSession
- impl Game for tests::Secret
- impl Game for tests::RevealOnce

### src/file.rs

- pub struct FileSession
- impl FileSession
- pub enum Error
- impl fmt::Display for Error
- impl std::error::Error for Error
- impl Game for tests::CountToThree
- impl Game for tests::Reveal

---

## README.md

### turnbase-session

The Session port for Turnbase: in-memory and file-backed hosts behind one request/response interface

Part of the [turnbase](https://github.com/crates-lurey-io/turnbase) workspace.

---

## src/lib.rs

### file::{Error, FileSession}

```rust
pub use file::{Error, FileSession};
```


### local::LocalSession

```rust
pub use local::LocalSession;
```


### Session

```rust
pub trait Session<G> {
    fn submit(&mut self, player: PlayerId, request: Request<G::Action>) -> Response<G::View>;
}
```

A running game, reachable in-process or (later) over a transport.


## src/local.rs

### LocalSession

```rust
pub struct LocalSession<G> {
}
```

An in-memory game: owns a [`Game`] and its state, and applies requests to
them directly. No file, socket, or other I/O, and no serialization: the
typed [`Request`]/[`Response`] pass straight through.

This is the authority. A [`crate::FileSession`] is a thin wrapper that
loads one of these, submits a single request, and saves it back; a
long-lived server would hold one across many requests.

A committed chance node ([`PlayerId::CHANCE`] active) is resolved
automatically from `chance`, so `submit` only ever returns control at a
player decision or a terminal state, never stuck on a deck deal a client
cannot make. `chance` is seeded from the match seed but offset, so it does
not share a stream with the game's own in-state generator.

### impl LocalSession

```rust
impl<G> LocalSession {
    pub fn new(game: G, state: G::State, seed: u64) -> Self;
    pub fn resume(game: G, state: G::State, version: u64, chance: Prng) -> Self;
    pub fn game(&self) -> &G;
    pub fn state(&self) -> &G::State;
    pub fn version(&self) -> u64;
    pub fn into_parts(self) -> (G, G::State, u64, Prng);
}
```


### impl Session<G> for LocalSession

```rust
impl<G> Session<G> for LocalSession {
}
```


### impl Game for Secret

```rust
impl Game for Secret {
}
```


### impl Game for RevealOnce

```rust
impl Game for RevealOnce {
}
```



## src/file.rs

### FileSession

```rust
pub struct FileSession;
```

A stateless, file-backed adapter over [`LocalSession`]: create a save, then
query or drive it across separate process invocations.

### impl FileSession

```rust
impl FileSession {
    pub fn create<G>(game: G, path: Option<PathBuf>, state: G::State, seed: u64) -> Result<PathBuf, Error>
    where
        G: Game + Serialize,
    G::State: Serialize;
    pub fn handle<G>(path: &Path, player: PlayerId, request: Request<G::Action>) -> Result<Response<G::View>, Error>
    where
        G: Game + Serialize + DeserializeOwned,
    G::State: Serialize + DeserializeOwned;
}
```


### Error

```rust
#[derive(Debug)]
pub enum Error {
    AlreadyExists(PathBuf),
    NotFound(PathBuf),
    ProtocolMismatch { found: u32, expected: u32 },
    Io(io::Error),
    Serde(serde_json::Error),
}
```

Errors from the file adapter itself.

Distinct from [`Response::Error`]: that is the *game* rejecting a request
(illegal action); these are the *file* misbehaving (missing, already
exists, unreadable, wrong protocol version).

### impl fmt::Display for Error

```rust
impl fmt::Display for Error {
}
```


### impl std::error::Error for Error

```rust
impl std::error::Error for Error {
}
```


### impl Game for CountToThree

```rust
impl Game for CountToThree {
}
```


### impl Game for Reveal

```rust
impl Game for Reveal {
}
```