feat: added `/xrpc/_health` endpoint

* disk usage

* database and backup status checks.

PDSharp.Core/Health.fs

···
+namespace PDSharp.Core
+
+open System
+open System.IO
+open System.Runtime.InteropServices
+
+/// Health monitoring module for guardrails and uptime checks
+module Health =
+
+  /// Health status response
+  type HealthStatus = {
+    /// Version of the PDS
+    Version : string
+    /// Uptime in seconds
+    UptimeSeconds : int64
+    /// Server start time in ISO8601
+    StartTime : string
+    /// Database status
+    DatabaseStatus : DatabaseStatus
+    /// Disk usage information
+    DiskUsage : DiskUsage option
+    /// Backup status
+    BackupStatus : BackupStatus option
+  }
+
+  /// Database connectivity status
+  and DatabaseStatus = {
+    /// Whether the database is reachable
+    IsHealthy : bool
+    /// Optional error message
+    Message : string option
+  }
+
+  /// Disk usage metrics
+  and DiskUsage = {
+    /// Total disk space in bytes
+    TotalBytes : int64
+    /// Free disk space in bytes
+    FreeBytes : int64
+    /// Used disk space in bytes
+    UsedBytes : int64
+    /// Percentage of disk used
+    UsedPercent : float
+    /// Whether disk pressure is critical (>90%)
+    IsCritical : bool
+  }
+
+  /// Backup status tracking
+  and BackupStatus = {
+    /// Timestamp of last successful backup
+    LastBackupTime : DateTimeOffset option
+    /// Age of last backup in hours
+    BackupAgeHours : float option
+    /// Whether backup is too old (>24 hours)
+    IsStale : bool
+  }
+
+  /// Get disk usage for a given path
+  let getDiskUsage (path : string) : DiskUsage option =
+    try
+      let driveInfo =
+        if RuntimeInformation.IsOSPlatform OSPlatform.Windows then
+          let driveLetter = Path.GetPathRoot path
+          DriveInfo driveLetter
+        else
+          DriveInfo(if Directory.Exists path then path else "/")
+
+      if driveInfo.IsReady then
+        let total = driveInfo.TotalSize
+        let free = driveInfo.TotalFreeSpace
+        let used = total - free
+        let usedPercent = float used / float total * 100.0
+
+        Some {
+          TotalBytes = total
+          FreeBytes = free
+          UsedBytes = used
+          UsedPercent = Math.Round(usedPercent, 2)
+          IsCritical = usedPercent >= 90.0
+        }
+      else
+        None
+    with _ ->
+      None
+
+
+
+  /// Check if a SQLite database file is accessible
+  let checkDatabaseHealth (connectionString : string) : DatabaseStatus =
+    try
+      let dbPath =
+        connectionString.Split ';'
+        |> Array.tryFind (fun s -> s.Trim().StartsWith("Data Source=", StringComparison.OrdinalIgnoreCase))
+        |> Option.map (fun s -> s.Split('=').[1].Trim())
+
+      match dbPath with
+      | Some path when File.Exists path -> { IsHealthy = true; Message = None }
+      | Some path -> {
+          IsHealthy = false
+          Message = Some $"Database file not found: {path}"
+        }
+      | None -> {
+          IsHealthy = false
+          Message = Some "Could not parse connection string"
+        }
+    with ex -> { IsHealthy = false; Message = Some ex.Message }
+
+  /// Calculate backup status from last backup time
+  let getBackupStatus (lastBackupTime : DateTimeOffset option) : BackupStatus =
+    match lastBackupTime with
+    | Some time ->
+      let age = DateTimeOffset.UtcNow - time
+      let ageHours = age.TotalHours
+
+      {
+        LastBackupTime = Some time
+        BackupAgeHours = Some(Math.Round(ageHours, 2))
+        IsStale = ageHours > 24.0
+      }
+    | None -> {
+        LastBackupTime = None
+        BackupAgeHours = None
+        IsStale = true
+      }
+
+  /// Mutable state for tracking server state
+  type HealthState() =
+    let mutable startTime = DateTimeOffset.UtcNow
+    let mutable lastBackupTime : DateTimeOffset option = None
+
+    member _.StartTime = startTime
+    member _.SetStartTime(time : DateTimeOffset) = startTime <- time
+    member _.LastBackupTime = lastBackupTime
+
+    member _.RecordBackup() =
+      lastBackupTime <- Some DateTimeOffset.UtcNow
+
+    member _.RecordBackup(time : DateTimeOffset) = lastBackupTime <- Some time
+
+    member _.GetUptime() : int64 =
+      int64 (DateTimeOffset.UtcNow - startTime).TotalSeconds
+
+  /// Build a complete health status
+  let buildHealthStatus
+    (version : string)
+    (healthState : HealthState)
+    (connectionString : string)
+    (dataPath : string)
+    : HealthStatus =
+    {
+      Version = version
+      UptimeSeconds = healthState.GetUptime()
+      StartTime = healthState.StartTime.ToString("o")
+      DatabaseStatus = checkDatabaseHealth connectionString
+      DiskUsage = getDiskUsage dataPath
+      BackupStatus = Some(getBackupStatus healthState.LastBackupTime)
+    }

PDSharp.Core/PDSharp.Core.fsproj

···
         <Compile Include="Firehose.fs" />
         <Compile Include="DidResolver.fs" />
         <Compile Include="Lexicon.fs" />
+        <Compile Include="Health.fs" />
         <Compile Include="Library.fs" />
     </ItemGroup>
 

PDSharp.Core/SqliteStore.fs

···
 
   type BlockRow = { cid : string; data : byte[] }
 
+  /// DTO for account rows with nullable email
+  [<CLIMutable>]
+  type AccountRow = {
+    did : string
+    handle : string
+    password_hash : string
+    email : string // Nullable in DB, null becomes null here
+    created_at : string
+  }
+
+  let private toAccount (row : AccountRow) : Account = {
+    Did = row.did
+    Handle = row.handle
+    PasswordHash = row.password_hash
+    Email = if isNull row.email then None else Some row.email
+    CreatedAt = DateTimeOffset.Parse row.created_at
+  }
+
   type IRepoStore =
     abstract member GetRepo : string -> Async<RepoRow option>
     abstract member SaveRepo : RepoRow -> Async<unit>
···
         use conn = new SqliteConnection(connectionString)
 
         try
+          let emailValue = account.Email |> Option.toObj
+          let createdAtStr = account.CreatedAt.ToString "o"
+
           let! _ =
             conn.ExecuteAsync(
               """
                 INSERT INTO accounts (did, handle, password_hash, email, created_at)
                 VALUES (@Did, @Handle, @PasswordHash, @Email, @CreatedAt)
             """,
-              account
+              {|
+                Did = account.Did
+                Handle = account.Handle
+                PasswordHash = account.PasswordHash
+                Email = emailValue
+                CreatedAt = createdAtStr
+              |}
             )
             |> Async.AwaitTask
 
···
         use conn = new SqliteConnection(connectionString)
 
         let! result =
-          conn.QuerySingleOrDefaultAsync<Account>(
+          conn.QuerySingleOrDefaultAsync<AccountRow>(
             "SELECT * FROM accounts WHERE handle = @handle",
             {| handle = handle |}
           )
···
         if isNull (box result) then
           return None
         else
-          return Some result
+          return Some(toAccount result)
       }
 
       member _.GetAccountByDid(did : string) = async {
         use conn = new SqliteConnection(connectionString)
 
         let! result =
-          conn.QuerySingleOrDefaultAsync<Account>("SELECT * FROM accounts WHERE did = @did", {| did = did |})
+          conn.QuerySingleOrDefaultAsync<AccountRow>("SELECT * FROM accounts WHERE did = @did", {| did = did |})
           |> Async.AwaitTask
 
         if isNull (box result) then
           return None
         else
-          return Some result
+          return Some(toAccount result)
       }
 
   type SqliteRepoStore(connectionString : string) =

PDSharp.Tests/Health.Tests.fs

···
+module PDSharp.Tests.Health
+
+open System
+open Xunit
+open PDSharp.Core.Health
+
+[<Fact>]
+let ``getDiskUsage returns disk info for valid path`` () =
+  let result = getDiskUsage "."
+
+  match result with
+  | Some usage ->
+    Assert.True(usage.TotalBytes > 0L)
+    Assert.True(usage.FreeBytes >= 0L)
+    Assert.True(usage.UsedBytes >= 0L)
+    Assert.True(usage.UsedPercent >= 0.0 && usage.UsedPercent <= 100.0)
+  | None -> Assert.True(true)
+
+[<Fact>]
+let ``getDiskUsage UsedPercent is calculated correctly`` () =
+  let result = getDiskUsage "."
+
+  match result with
+  | Some usage ->
+    let expectedUsed = usage.TotalBytes - usage.FreeBytes
+    Assert.Equal(expectedUsed, usage.UsedBytes)
+    let expectedPercent = float usage.UsedBytes / float usage.TotalBytes * 100.0
+    Assert.True(abs (usage.UsedPercent - expectedPercent) < 0.1)
+  | None -> Assert.True(true)
+
+[<Fact>]
+let ``getDiskUsage IsCritical is true when usage > 90 percent`` () =
+  let result = getDiskUsage "."
+
+  match result with
+  | Some usage -> Assert.Equal(usage.UsedPercent >= 90.0, usage.IsCritical)
+  | None -> Assert.True(true)
+
+[<Fact>]
+let ``checkDatabaseHealth returns healthy for existing file`` () =
+  let tempPath = System.IO.Path.GetTempFileName()
+
+  try
+    let connStr = $"Data Source={tempPath}"
+    let result = checkDatabaseHealth connStr
+    Assert.True result.IsHealthy
+    Assert.True result.Message.IsNone
+  finally
+    System.IO.File.Delete tempPath
+
+[<Fact>]
+let ``checkDatabaseHealth returns unhealthy for missing file`` () =
+  let connStr = "Data Source=/nonexistent/path/to/database.db"
+  let result = checkDatabaseHealth connStr
+  Assert.False result.IsHealthy
+  Assert.True result.Message.IsSome
+
+[<Fact>]
+let ``checkDatabaseHealth handles invalid connection string`` () =
+  let connStr = "invalid"
+  let result = checkDatabaseHealth connStr
+  Assert.False result.IsHealthy
+  Assert.True result.Message.IsSome
+
+[<Fact>]
+let ``getBackupStatus returns stale when no backup`` () =
+  let result = getBackupStatus None
+  Assert.True result.IsStale
+  Assert.True result.LastBackupTime.IsNone
+  Assert.True result.BackupAgeHours.IsNone
+
+[<Fact>]
+let ``getBackupStatus returns not stale for recent backup`` () =
+  let recentTime = DateTimeOffset.UtcNow.AddHours(-1.0)
+  let result = getBackupStatus (Some recentTime)
+  Assert.False result.IsStale
+  Assert.True result.LastBackupTime.IsSome
+  Assert.True result.BackupAgeHours.IsSome
+  Assert.True(result.BackupAgeHours.Value < 24.0)
+
+[<Fact>]
+let ``getBackupStatus returns stale for old backup`` () =
+  let oldTime = DateTimeOffset.UtcNow.AddHours(-25.0)
+  let result = getBackupStatus (Some oldTime)
+  Assert.True result.IsStale
+  Assert.True(result.BackupAgeHours.Value > 24.0)
+
+[<Fact>]
+let ``HealthState tracks uptime correctly`` () =
+  let state = HealthState()
+  state.SetStartTime(DateTimeOffset.UtcNow.AddSeconds(-10.0))
+  let uptime = state.GetUptime()
+  Assert.True(uptime >= 9L && uptime <= 12L)
+
+[<Fact>]
+let ``HealthState records backup time`` () =
+  let state = HealthState()
+  Assert.True state.LastBackupTime.IsNone
+  state.RecordBackup()
+  Assert.True state.LastBackupTime.IsSome
+
+[<Fact>]
+let ``buildHealthStatus constructs complete status`` () =
+  let state = HealthState()
+  let tempPath = System.IO.Path.GetTempFileName()
+
+  try
+    let connStr = $"Data Source={tempPath}"
+    let status = buildHealthStatus "1.0.0" state connStr "."
+
+    Assert.Equal("1.0.0", status.Version)
+    Assert.True(status.UptimeSeconds >= 0L)
+    Assert.True status.DatabaseStatus.IsHealthy
+    Assert.True status.BackupStatus.IsSome
+  finally
+    System.IO.File.Delete tempPath

PDSharp.Tests/PDSharp.Tests.fsproj

···
     <Compile Include="Auth.Tests.fs" />
     <Compile Include="Conformance.Tests.fs" />
     <Compile Include="Handlers.Tests.fs" />
+    <Compile Include="Health.Tests.fs" />
     <Compile Include="Program.fs" />
   </ItemGroup>
 

PDSharp/Handlers/Health.fs

···
+namespace PDSharp.Handlers
+
+open System.Text.Json
+open Microsoft.AspNetCore.Http
+open Giraffe
+open PDSharp.Core.Health
+open PDSharp.Core.Config
+
+module HealthHandler =
+  /// PDS version (could be read from assembly info)
+  let private version = "0.1.0"
+
+  /// JSON serialization options with camelCase naming
+  let private jsonOptions =
+    JsonSerializerOptions(PropertyNamingPolicy = JsonNamingPolicy.CamelCase, WriteIndented = true)
+
+  /// Health check handler for /xrpc/_health endpoint
+  let healthHandler : HttpHandler =
+    fun next ctx -> task {
+      let config = ctx.GetService<AppConfig>()
+      let healthState = ctx.GetService<HealthState>()
+      let status = buildHealthStatus version healthState config.SqliteConnectionString "." // Check disk of current working directory
+
+      if status.DatabaseStatus.IsHealthy then
+        ctx.SetStatusCode 200
+      else
+        ctx.SetStatusCode 503
+
+      let json = JsonSerializer.Serialize(status, jsonOptions)
+      ctx.SetContentType "application/json"
+      return! text json next ctx
+    }

PDSharp/PDSharp.fsproj

···
     <Compile Include="Handlers/Auth.fs" />
     <Compile Include="Handlers/Repo.fs" />
     <Compile Include="Handlers/Sync.fs" />
+    <Compile Include="Handlers/Health.fs" />
     <Compile Include="Program.fs" />
     </ItemGroup>
 

PDSharp/Program.fs

···
 open PDSharp.Core.SqliteStore
 open PDSharp.Core.BlobStore
 open PDSharp.Core.Config
+open PDSharp.Core.Health
 open PDSharp.Handlers
 
 let getConfig () =
···
       >=> choose [
         route "/" >=> Server.indexHandler
         route "/xrpc/com.atproto.server.describeServer" >=> Server.describeServerHandler
+        route "/xrpc/_health" >=> HealthHandler.healthHandler
       ]
       POST
       >=> route "/xrpc/com.atproto.server.createAccount"
···
     services.AddSingleton<IBlobStore> blobStore |> ignore
     services.AddSingleton<FirehoseState>(new FirehoseState()) |> ignore
     services.AddSingleton<SigningKeyStore>(new SigningKeyStore()) |> ignore
+    services.AddSingleton<HealthState>(new HealthState()) |> ignore
 
   [<EntryPoint>]
   let main args =

roadmap.txt

···
     - [ ] Databases (Litestream or raw copy) + /pds/actors backup
     - [ ] Local disk blobs (if applicable)
 - [ ] Guardrails & Monitoring:
-    - [ ] Uptime check endpoint: /xrpc/_health with JSON status
-    - [ ] Alerts: "Latest backup" too old, Disk pressure > 90%
+    - [x] Uptime check endpoint: /xrpc/_health with JSON status
+    - [x] Alerts: "Latest backup" too old, Disk pressure > 90%
     - [ ] Log retention policies
 DoD:
   - Backups run automatically and report status
···
 [x] CAR export + sync endpoints
 [x] subscribeRepos firehose
 [x] Authentication (createAccount, createSession)
-[ ] Lexicon validation
+[x] Lexicon validation
 [ ] Domain + TLS configured
 [ ] PDS deployed and reachable
 [ ] Account created, session works
 [ ] Writes + blobs verified
-[ ] Backups + monitoring in place
+[/] Backups + monitoring in place (health endpoint done, backup automation pending)
 ================================================================================
 REFERENCES
 ================================================================================