180 Advanced

PhantomData for API Safety

Functional Programming

Tutorial

The Problem

Database connections, file handles, and network sockets have a lifecycle: they must be opened before use and closed after use. Calling query methods on a closed connection causes runtime errors. PhantomData-based typestate encodes the connection state in the type: Connection<Closed> and Connection<Open> are different types, with query methods available only on Connection<Open>. Opening a closed connection returns Connection<Open>; closing an open connection returns Connection<Closed>.

🎯 Learning Outcomes

• Apply the typestate pattern to a real-world resource lifecycle (database connection)

• Understand how phantom types prevent use-after-close and use-before-open bugs at compile time

• See how the same pattern applies to file handles, sockets, and other OS resources

• Appreciate zero-cost typestate: PhantomData<State> adds no runtime overhead

Code Example

struct Connection<State> { host: String, _state: PhantomData<State> }

impl Connection<Closed> {
    fn open(self) -> Connection<Open> { /* ... */ }
}
impl Connection<Open> {
    fn query(&self, sql: &str) -> String { /* ... */ }
    fn close(self) -> Connection<Closed> { /* ... */ }
}

type _ connection =
  | Closed : string -> closed_state connection
  | Open   : string * int -> open_state connection

let connect (Closed host) : open_state connection = Open (host, 42)
let query (Open (host, _)) sql = "result: " ^ sql
let close (Open (host, _)) : closed_state connection = Closed host

Key Differences

Move semantics: Rust's open(self) consumes the closed connection — the old binding cannot be used; OCaml retains the old value in scope.

Compile-time prevention: Rust: using the old closed connection after open is a compile error ("value used after move"); OCaml: same value remains accessible.

Linear types: Rust's ownership system provides a subset of linear types; true linear type languages (Idris, Linear Haskell) are stricter still.

RAII: Rust can combine typestate with Drop to auto-close on drop; OCaml uses finalizers (unreliable for deterministic resource cleanup).

OCaml Approach

OCaml's phantom type approach:

type closed = Closed
type open_ = Open
type 'state connection = { host: string }
let open_conn (c: closed connection) : open_ connection = c
let close_conn (c: open_ connection) : closed connection = c
let query (c: open_ connection) : string = "result"

This works but does not prevent using the old closed connection after calling open_conn — OCaml's GC keeps the old value alive, so the programmer can accidentally use it. Rust's move semantics make this impossible.

Full Source

#![allow(clippy::all)]
// Example 180: PhantomData for API Safety
// Connection<Closed> vs Connection<Open> — can't query a closed connection

use std::marker::PhantomData;

// === Approach 1: Type-state pattern with PhantomData ===

struct Closed;
struct Open;

struct Connection<State> {
    host: String,
    _state: PhantomData<State>,
}

impl Connection<Closed> {
    fn new(host: &str) -> Self {
        Connection {
            host: host.to_string(),
            _state: PhantomData,
        }
    }

    fn open(self) -> Connection<Open> {
        println!("Connecting to {}...", self.host);
        Connection {
            host: self.host,
            _state: PhantomData,
        }
    }
}

impl Connection<Open> {
    fn query(&self, sql: &str) -> String {
        format!("result({}): {}", self.host, sql)
    }

    fn execute(&self, sql: &str) -> usize {
        println!("Execute on {}: {}", self.host, sql);
        1 // rows affected
    }

    fn close(self) -> Connection<Closed> {
        println!("Closing {}", self.host);
        Connection {
            host: self.host,
            _state: PhantomData,
        }
    }
}

// host() available in any state
impl<S> Connection<S> {
    fn host(&self) -> &str {
        &self.host
    }
}

// === Approach 2: Builder pattern with type states ===

struct Disconnected;
struct Connected;
struct InTransaction;

struct DbSession<State> {
    url: String,
    _state: PhantomData<State>,
}

impl DbSession<Disconnected> {
    fn new(url: &str) -> Self {
        DbSession {
            url: url.to_string(),
            _state: PhantomData,
        }
    }

    fn connect(self) -> DbSession<Connected> {
        DbSession {
            url: self.url,
            _state: PhantomData,
        }
    }
}

impl DbSession<Connected> {
    fn begin_transaction(self) -> DbSession<InTransaction> {
        DbSession {
            url: self.url,
            _state: PhantomData,
        }
    }

    fn query(&self, sql: &str) -> String {
        format!("query({}): {}", self.url, sql)
    }

    fn disconnect(self) -> DbSession<Disconnected> {
        DbSession {
            url: self.url,
            _state: PhantomData,
        }
    }
}

impl DbSession<InTransaction> {
    fn query(&self, sql: &str) -> String {
        format!("tx_query({}): {}", self.url, sql)
    }

    fn commit(self) -> DbSession<Connected> {
        println!("COMMIT");
        DbSession {
            url: self.url,
            _state: PhantomData,
        }
    }

    fn rollback(self) -> DbSession<Connected> {
        println!("ROLLBACK");
        DbSession {
            url: self.url,
            _state: PhantomData,
        }
    }
}

// === Approach 3: File handle safety ===

struct Unopened;
struct Opened;

struct SafeFile<State> {
    path: String,
    content: Option<String>,
    _state: PhantomData<State>,
}

impl SafeFile<Unopened> {
    fn new(path: &str) -> Self {
        SafeFile {
            path: path.to_string(),
            content: None,
            _state: PhantomData,
        }
    }

    fn open(self) -> SafeFile<Opened> {
        SafeFile {
            path: self.path,
            content: Some(String::new()),
            _state: PhantomData,
        }
    }
}

impl SafeFile<Opened> {
    fn write(&mut self, data: &str) {
        if let Some(ref mut c) = self.content {
            c.push_str(data);
        }
    }

    fn read(&self) -> &str {
        self.content.as_deref().unwrap_or("")
    }

    fn close(self) -> SafeFile<Unopened> {
        SafeFile {
            path: self.path,
            content: None,
            _state: PhantomData,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_connection_lifecycle() {
        let conn = Connection::<Closed>::new("db.test");
        assert_eq!(conn.host(), "db.test");
        let conn = conn.open();
        assert_eq!(conn.query("SELECT 1"), "result(db.test): SELECT 1");
        let closed = conn.close();
        assert_eq!(closed.host(), "db.test");
    }

    #[test]
    fn test_db_session() {
        let s = DbSession::new("pg://localhost").connect();
        assert!(s.query("X").contains("query"));
        let tx = s.begin_transaction();
        assert!(tx.query("X").contains("tx_query"));
        let s = tx.commit();
        let _d = s.disconnect();
    }

    #[test]
    fn test_safe_file() {
        let f = SafeFile::<Unopened>::new("test.txt");
        let mut f = f.open();
        f.write("abc");
        f.write("def");
        assert_eq!(f.read(), "abcdef");
        let _closed = f.close();
    }
}

(* Example 180: PhantomData for API Safety *)
(* Connection<Closed> vs Connection<Open> — can't query closed connection *)

(* Approach 1: GADT connection states *)
type open_state = Open_tag
type closed_state = Closed_tag

type _ connection =
  | Closed : string -> closed_state connection
  | Open   : string * int -> open_state connection

let connect (Closed host) : open_state connection =
  Printf.printf "Connecting to %s...\n" host;
  Open (host, 42)  (* 42 = fake handle *)

let query (Open (host, _handle)) sql =
  Printf.printf "Query on %s: %s\n" host sql;
  "result: " ^ sql

let close (Open (host, _)) : closed_state connection =
  Printf.printf "Closing %s\n" host;
  Closed host

(* Approach 2: Module with abstract types *)
module SafeConn : sig
  type 'a conn
  type opened
  type closed
  val create : string -> closed conn
  val open_conn : closed conn -> opened conn
  val query : opened conn -> string -> string
  val close : opened conn -> closed conn
  val host : _ conn -> string
end = struct
  type opened = Open_t
  type closed = Closed_t
  type 'a conn = { host: string; handle: int option }
  let create host = { host; handle = None }
  let open_conn c = { c with handle = Some 1 }
  let query c sql = "result(" ^ c.host ^ "): " ^ sql
  let close c = { c with handle = None }
  let host c = c.host
end

(* Approach 3: Functor-based state machine *)
module type STATE = sig type t end
module Closed_s : STATE = struct type t = unit end
module Open_s : STATE = struct type t = unit end

module Connection (S : STATE) = struct
  type state = S.t
  type t = { host: string; port: int }
  let create host port = { host; port }
end

let () =
  (* Test Approach 1 *)
  let c = Closed "localhost" in
  let o = connect c in
  let result = query o "SELECT 1" in
  assert (result = "result: SELECT 1");
  let _c2 = close o in
  (* Can't do: query c "SELECT 1"  — type error! *)

  (* Test Approach 2 *)
  let c = SafeConn.create "db.example.com" in
  let o = SafeConn.open_conn c in
  let r = SafeConn.query o "SELECT * FROM users" in
  assert (String.length r > 0);
  let _c2 = SafeConn.close o in
  (* Can't do: SafeConn.query c "..."  — type error! *)

  print_endline "✓ All tests passed"

✓ Tests Rust test suite

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_connection_lifecycle() {
        let conn = Connection::<Closed>::new("db.test");
        assert_eq!(conn.host(), "db.test");
        let conn = conn.open();
        assert_eq!(conn.query("SELECT 1"), "result(db.test): SELECT 1");
        let closed = conn.close();
        assert_eq!(closed.host(), "db.test");
    }

    #[test]
    fn test_db_session() {
        let s = DbSession::new("pg://localhost").connect();
        assert!(s.query("X").contains("query"));
        let tx = s.begin_transaction();
        assert!(tx.query("X").contains("tx_query"));
        let s = tx.commit();
        let _d = s.disconnect();
    }

    #[test]
    fn test_safe_file() {
        let f = SafeFile::<Unopened>::new("test.txt");
        let mut f = f.open();
        f.write("abc");
        f.write("def");
        assert_eq!(f.read(), "abcdef");
        let _closed = f.close();
    }
}

Deep Comparison

Comparison: Example 180 — PhantomData for API Safety

Type-State Connection

OCaml

type _ connection =
  | Closed : string -> closed_state connection
  | Open   : string * int -> open_state connection

let connect (Closed host) : open_state connection = Open (host, 42)
let query (Open (host, _)) sql = "result: " ^ sql
let close (Open (host, _)) : closed_state connection = Closed host

Rust

struct Connection<State> { host: String, _state: PhantomData<State> }

impl Connection<Closed> {
    fn open(self) -> Connection<Open> { /* ... */ }
}
impl Connection<Open> {
    fn query(&self, sql: &str) -> String { /* ... */ }
    fn close(self) -> Connection<Closed> { /* ... */ }
}

Abstract Module vs Trait

OCaml

module SafeConn : sig
  type 'a conn
  type opened
  type closed
  val open_conn : closed conn -> opened conn
  val query : opened conn -> string -> string
  val close : opened conn -> closed conn
end

Rust

// No need for module abstraction — PhantomData + separate impls
// achieves the same: methods only exist on the right state type
impl Connection<Open> {
    fn query(&self, sql: &str) -> String { /* ... */ }
}
// Connection<Closed> simply has no query method

Exercises

Add an execute(&mut self, sql: &str) -> Result<(), String> method on Connection<Open> that simulates query execution.

Implement Connection<Open> → Connection<InTransaction> → Connection<Open> transitions with begin_transaction, commit, and rollback methods.

Combine typestate with Drop: auto-close the connection when Connection<Open> is dropped, logging a warning.

Open Source Repos

functional-rust

View the source for this example on GitHub — OCaml and Rust side by side in the repo.

Rust