✨ Add file sink reopen and failure counters

README.md

@@ -26,7 +26,7 @@ BitLogger 是一个基于 MoonBit 编写的结构化日志库。
 - 🧷 可绑定上下文：支持 `bind(...)` 与 `fields(...)`，更方便地封装复用字段上下文。
 - 📮 显式队列：支持 `queued_sink(...)` / `with_queue(...)`、有界积压与溢出策略，作为后续 async sink 的 runtime-safe 基础。
 - 🧾 可配置文本格式：支持 `text_formatter(...)`、`format_text(...)`、`text_console_sink(...)`、`formatted_callback_sink(...)` 与模板化 `template` 输出。
-- 💾 Native 文件输出：支持 `file_sink(...)`，并已提供基础 size rotation / backup retention；当前仅保证 `native/llvm` backend 可用。
+- 💾 Native 文件输出：支持 `file_sink(...)`、基础 size rotation / backup retention、显式 `reopen()` 与失败计数；当前仅保证 `native/llvm` backend 可用。
 - 📦 面向 MoonBit：API 和工程结构围绕 MoonBit 的 package / visibility / toolchain 现实约束设计。
 
 ## 🚀 快速开始
@@ -221,6 +221,7 @@ if native_files_supported() {
 - 当前提供 JSON 配置层：`parse_logger_config_text(...)`、`stringify_logger_config(...)`、`build_logger(...)`
 - 已支持字段：`min_level`、`target`、`timestamp`、`sink.kind`、`sink.path`、`sink.append`、`sink.auto_flush`、`sink.rotation`、`sink.text_formatter`、`queue`
 - `sink.rotation` 当前支持 `max_bytes` 与 `max_backups`，提供基础 size-based rotation 和 backup retention
+- `file_sink(...)` 还提供 `reopen()`、`open_failures()`、`write_failures()`、`flush_failures()`、`rotation_failures()`，用于基础可观测性
 - `sink.text_formatter.template` 当前支持固定 token：`{timestamp}`、`{timestamp_ms}`、`{level}`、`{target}`、`{message}`、`{fields}`
 - 当前可由配置直接组装的 sink 类型：`console`、`json_console`、`text_console`、`file`
 - `queue` 会作为显式包装层附着在最终 sink 外侧；这仍然是同步 drain 模型，不是 async runtime

bitlogger/BitLogger_wbtest.mbt

@@ -90,6 +90,9 @@ test "native file support flag is queryable" {
 test "file sink availability reflects backend support" {
   let sink = file_sink("bitlogger-test.log")
   inspect(sink.is_available() == native_files_supported(), content="true")
+  inspect(sink.open_failures(), content=if sink.is_available() { "0" } else { "1" })
+  inspect(sink.write_failures(), content="0")
+  inspect(sink.flush_failures(), content="0")
   if sink.is_available() {
     inspect(sink.flush(), content="true")
     inspect(sink.close(), content="true")
@@ -110,9 +113,34 @@ test "file sink tracks rotation failures on unavailable backend" {
   sink.write(record(Level::Info, "a"))
   if sink.is_available() {
     inspect(sink.rotation_failures(), content="0")
+    inspect(sink.write_failures(), content="0")
     ignore(sink.close())
   } else {
     inspect(sink.rotation_failures(), content="0")
+    inspect(sink.write_failures(), content="1")
+  }
+}
+
+test "file sink reopen and failure counters reflect backend state" {
+  let sink = file_sink("bitlogger-reopen.log")
+  if sink.is_available() {
+    inspect(sink.open_failures(), content="0")
+    inspect(sink.close(), content="true")
+    inspect(sink.reopen(), content="true")
+    inspect(sink.is_available(), content="true")
+    inspect(sink.open_failures(), content="0")
+    sink.write(record(Level::Info, "reopened"))
+    inspect(sink.write_failures(), content="0")
+    inspect(sink.flush_failures(), content="0")
+    inspect(sink.close(), content="true")
+    ignore(remove_file_internal("bitlogger-reopen.log"))
+  } else {
+    inspect(sink.open_failures(), content="1")
+    sink.write(record(Level::Info, "dropped"))
+    inspect(sink.write_failures(), content="1")
+    inspect(sink.reopen(), content="false")
+    inspect(sink.open_failures(), content="2")
+    inspect(sink.flush_failures(), content="0")
   }
 }
 

bitlogger/README.mbt.md

@@ -46,8 +46,8 @@ BitLogger 是一个基于 MoonBit 的结构化日志库。
 - 支持 `parse_logger_config_text(...)`、`stringify_logger_config(...)` 进行最小 JSON 配置读写
 - config-driven logger assembly via `build_logger(...)`
 - 支持 `build_logger(...)` 将配置组装为可直接使用的 logger
-- native-only file output via `file_sink(...)`, with basic size rotation and backup retention
+- native-only file output via `file_sink(...)`, with basic size rotation, backup retention, explicit `reopen()`, and failure counters
-- 支持 `file_sink(...)`、基础 size rotation 与 backup retention，但当前仅保证 `native/llvm` backend 可用
+- 支持 `file_sink(...)`、基础 size rotation / backup retention、显式 `reopen()` 与失败计数，但当前仅保证 `native/llvm` backend 可用
 
 ## Example / 示例
 
@@ -220,3 +220,6 @@ test {
 - basic rotation is size-based / 当前基础轮转为按文件大小触发
 - `file_rotation(max_bytes, max_backups=...)` controls threshold and retained backups / `file_rotation(max_bytes, max_backups=...)` 控制触发阈值和保留备份数
 - JSON config uses `sink.rotation.max_bytes` and `sink.rotation.max_backups` / JSON 配置使用 `sink.rotation.max_bytes` 与 `sink.rotation.max_backups`
+- `FileSink::reopen()` can explicitly reopen the current file handle / `FileSink::reopen()` 可显式重开当前文件句柄
+- `open_failures()`、`write_failures()`、`flush_failures()`、`rotation_failures()` expose basic sink health counters / `open_failures()`、`write_failures()`、`flush_failures()`、`rotation_failures()` 可用于观察基础 sink 健康状态
+- current scope is observability-first, not a full self-healing sink runtime / 当前定位仍以可观测性优先，不是完整自愈型 sink runtime

bitlogger/sinks.mbt

@@ -51,6 +51,9 @@ pub struct FileSink {
   formatter : RecordFormatter
   auto_flush : Bool
   rotation : FileRotation?
+  open_failures : Ref[Int]
+  write_failures : Ref[Int]
+  flush_failures : Ref[Int]
   rotation_failures : Ref[Int]
 }
 
@@ -79,13 +82,17 @@ pub fn file_sink(
     format_text(rec)
   },
 ) -> FileSink {
+  let handle = open_file_handle_internal(path, append)
   {
     path,
     append,
-    handle: Ref::new(open_file_handle_internal(path, append)),
+    handle: Ref::new(handle),
     formatter,
     auto_flush,
     rotation,
+    open_failures: Ref::new(if handle is Some(_) { 0 } else { 1 }),
+    write_failures: Ref::new(0),
+    flush_failures: Ref::new(0),
     rotation_failures: Ref::new(0),
   }
 }
@@ -97,7 +104,13 @@ pub fn FileSink::is_available(self : FileSink) -> Bool {
 pub fn FileSink::flush(self : FileSink) -> Bool {
   match self.handle.val {
     None => false
-    Some(handle) => flush_file_handle_internal(handle)
+    Some(handle) => {
+      let ok = flush_file_handle_internal(handle)
+      if !ok {
+        self.flush_failures.val += 1
+      }
+      ok
+    }
   }
 }
 
@@ -116,6 +129,37 @@ pub fn FileSink::rotation_failures(self : FileSink) -> Int {
   self.rotation_failures.val
 }
 
+pub fn FileSink::open_failures(self : FileSink) -> Int {
+  self.open_failures.val
+}
+
+pub fn FileSink::write_failures(self : FileSink) -> Int {
+  self.write_failures.val
+}
+
+pub fn FileSink::flush_failures(self : FileSink) -> Int {
+  self.flush_failures.val
+}
+
+pub fn FileSink::reopen(self : FileSink, append~ : Bool? = None) -> Bool {
+  let append_mode = append.unwrap_or(self.append)
+  match self.handle.val {
+    None => ()
+    Some(handle) => {
+      ignore(close_file_handle_internal(handle))
+      self.handle.val = None
+    }
+  }
+  let reopened = open_file_handle_internal(self.path, append_mode)
+  self.handle.val = reopened
+  if reopened is Some(_) {
+    true
+  } else {
+    self.open_failures.val += 1
+    false
+  }
+}
+
 fn rotated_file_path(path : String, index : Int) -> String {
   "\{path}.\{index}"
 }
@@ -171,20 +215,33 @@ fn rotate_if_needed_internal(sink : FileSink, next_line_bytes : Int) -> Bool {
 
 pub impl Sink for FileSink with write(self, rec) {
   match self.handle.val {
-    None => ()
+    None => {
+      self.write_failures.val += 1
+    }
     Some(_) => {
       let line = "\{(self.formatter)(rec)}\n"
       let can_write = rotate_if_needed_internal(self, string_byte_length_internal(line))
       if can_write {
         match self.handle.val {
-          None => ()
+          None => {
+            self.write_failures.val += 1
+          }
           Some(active) => {
-            ignore(write_file_handle_internal(active, line))
+            let wrote = write_file_handle_internal(active, line)
-            if self.auto_flush {
+            if wrote {
-              ignore(flush_file_handle_internal(active))
+              if self.auto_flush {
+                let flushed = flush_file_handle_internal(active)
+                if !flushed {
+                  self.flush_failures.val += 1
+                }
+              }
+            } else {
+              self.write_failures.val += 1
             }
           }
         }
+      } else {
+        self.write_failures.val += 1
       }
     }
   }

docs/README-en.md

@@ -26,7 +26,7 @@ BitLogger currently provides:
 - bounded backlog with `QueueOverflowPolicy::DropNewest` and `QueueOverflowPolicy::DropOldest`
 - configurable text formatting via `text_formatter(...)`, `format_text(...)`, `text_console_sink(...)`, and template-driven `template` output
 - formatter-based callback integration via `formatted_callback_sink(...)`
-- native-only file output via `file_sink(...)`, with basic size rotation and backup retention
+- native-only file output via `file_sink(...)`, with basic size rotation, backup retention, explicit `reopen()`, and failure counters
 - `native_files_supported()` for backend capability detection
 - default global logger helpers
 
@@ -206,6 +206,7 @@ if native_files_supported() {
 - BitLogger now includes a JSON config layer via `parse_logger_config_text(...)`, `stringify_logger_config(...)`, and `build_logger(...)`.
 - Supported keys include `min_level`, `target`, `timestamp`, `sink.kind`, `sink.path`, `sink.append`, `sink.auto_flush`, `sink.rotation`, `sink.text_formatter`, and `queue`.
 - `sink.rotation` currently supports `max_bytes` and `max_backups` for basic size-based rotation and backup retention.
+- `file_sink(...)` also exposes `reopen()`, `open_failures()`, `write_failures()`, `flush_failures()`, and `rotation_failures()` for basic observability.
 - `sink.text_formatter.template` currently supports fixed tokens: `{timestamp}`, `{timestamp_ms}`, `{level}`, `{target}`, `{message}`, and `{fields}`.
 - Config-driven sink assembly currently supports `console`, `json_console`, `text_console`, and `file`.
 - `queue` remains a synchronous bounded wrapper around the final sink, not an async runtime.

docs/changes/0.3.0.md

@@ -29,6 +29,7 @@ version 0.3.0
 - feat: support formatter tokens `{timestamp}`, `{timestamp_ms}`, `{level}`, `{target}`, `{message}`, and `{fields}` in both runtime and JSON config paths
 - feat: add `FileRotation`, `file_rotation(...)`, and size-based file rotation with retained backups for `file_sink(...)`
 - feat: support `sink.rotation.max_bytes` and `sink.rotation.max_backups` in JSON logger config
+- feat: add `FileSink::reopen()` and basic file sink failure counters via `open_failures()`, `write_failures()`, and `flush_failures()`
 - feat: add `SplitSink`, `split_sink(...)`, and `split_by_level(...)` for routing records into different sinks by predicate or level
 - feat: add `Logger::bind(...)` as an ergonomic context-binding alias and `fields(...)` helper for tuple-based field construction
 
@@ -42,6 +43,7 @@ version 0.3.0
 - test: cover dropped-count reporting for bounded config-built queue
 - test: cover template-based formatter rendering and disabled token behavior
 - test: cover file rotation config parsing, config roundtrip, and native rotation behavior
+- test: cover file sink reopen behavior and backend-dependent failure counter paths
 - test: cover split sink predicate routing and level-based routing behavior
 - test: cover `bind(...)` context composition and `fields(...)` helper behavior
 - test: add async logger lifecycle, config roundtrip, and batching/flush policy test seeds
@@ -56,6 +58,7 @@ version 0.3.0
 - docs: update root README, English README, and Mooncake README with config usage notes
 - docs: update formatter examples to demonstrate template-based text rendering
 - docs: update file sink examples to demonstrate rotation and backup retention
+- docs: document file sink reopen and observability counters in README variants
 - docs: add split sink examples for level-based routing
 - docs: add `bind(...)` examples for reusable context binding
 - docs: update root README and English README with async adapter notes and current scope
@@ -66,5 +69,6 @@ version 0.3.0
 - current config scope is still intentionally constrained to stable built-in sink shapes
 - formatter templates are intentionally limited to simple token replacement and do not yet include conditional blocks or alignment/padding controls
 - current file rotation scope is intentionally limited to size-based rename retention and does not yet include time rotation or compression
+- file sink observability is currently counter-based and explicit; it does not yet attempt automatic recovery or background self-healing
 - queue wrapping remains synchronous drain-based delivery, not async runtime scheduling
 - async logging remains an isolated adapter layer and currently targets `native/llvm` only