BitLogger/docs/changes/0.3.0.md

BitLogger Update Changes

version 0.3.0

Feature

• feat: add config.mbt as a minimal JSON-backed logger configuration layer
• feat: add TextFormatterConfig, QueueConfig, and LoggerConfig public config types
• feat: add TextFormatterConfig::new(...), QueueConfig::new(...), and LoggerConfig::new(...) constructors for explicit config assembly
• feat: add SinkKind and SinkConfig for sink-specific configuration
• feat: add TextFormatterConfig::to_formatter() for bridging parsed config into runtime formatter setup
• feat: add parse_logger_config_text(...) for JSON config parsing
• feat: add logger_config_to_json(...) and stringify_logger_config(...) for config serialization
• feat: add RuntimeSink, ConfiguredLogger, build_logger(...), and parse_and_build_logger(...) for config-driven logger assembly
• feat: add ConfiguredLogger::drain(...), ConfiguredLogger::pending_count(), and ConfiguredLogger::dropped_count() queue observability helpers
• feat: add bitlogger_async/ as a separate native-target async adapter package
• feat: add AsyncLogger, async_logger(...), run(), wait_idle(), close(), pending_count(), and dropped_count() on top of moonbitlang/async
• feat: add async logger composition helpers with_context_fields(...), with_filter(...), with_patch(...), with_target(...), child(...), and with_timestamp(...)
• feat: add AsyncLoggerBuildConfig, parse_async_logger_build_config_text(...), and build_async_logger(...) for config-driven async logger assembly
• feat: add async lifecycle helpers shutdown(), is_closed(), is_running(), has_failed(), and last_error() for safer worker teardown and observability
• feat: add parse_async_logger_config_text(...), stringify_async_logger_config(...), and build-config serialization helpers for async config roundtrip support
• feat: add async batching controls max_batch and flush=Never|Batch|Shutdown for queue draining and flush timing
• feat: expose Record::new(...) for adapter and integration layers
• fix: repair native file backend FFI declarations so native target checks succeed again
• feat: support config keys min_level, target, timestamp, sink.kind, sink.path, sink.append, sink.auto_flush, sink.text_formatter, and queue
• feat: support config-driven sink assembly for console, json_console, text_console, and file
• feat: use maria/json_parser as the first external dependency for practical config loading
• feat: add TextFormatter.template and TextFormatterConfig.template for template-driven text rendering
• 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: forward file sink reopen and failure-counter helpers through RuntimeSink and ConfiguredLogger
• feat: add explicit file_flush() and file_close() helpers for config-built file sinks, including queued file sink drain-before-close behavior
• feat: make file append mode queryable via append_mode() / file_append_mode() and persist explicit reopen(append=...) mode updates for later reopen calls
• feat: add path() / auto_flush_enabled() on FileSink and file_path() / file_auto_flush() on ConfiguredLogger for basic file-policy introspection
• feat: add rotation_enabled() / rotation_config() on FileSink and file_rotation_enabled() / file_rotation_config() on ConfiguredLogger for rotation-policy introspection
• feat: add runtime file-policy mutators set_auto_flush(...), set_rotation(...), clear_rotation() and corresponding configured-logger forwarding helpers
• feat: add explicit append-policy setter set_append_mode(...) / file_set_append_mode(...) so append strategy can be updated without piggybacking on reopen(...)
• feat: add explicit reopen_with_current_policy() / file_reopen_with_current_policy() helpers so stored append-policy reopen is discoverable instead of implicit
• feat: add reopen_append() / reopen_truncate() and configured-logger forwarding helpers so common append-vs-truncate reopen flows do not need raw Some(true/false) calls
• feat: add FileSinkState, FileSink::state(), and file_state() helpers so file-sink runtime policy and failure counters can be read as one snapshot
• feat: add RuntimeFileState and file_runtime_state() so config-built queued file sinks can expose outer queue backlog/drop state together with inner file state
• feat: add JSON export helpers for FileSinkState and RuntimeFileState so runtime file snapshots can be dumped directly for diagnostics
• feat: add reset_failure_counters() / file_reset_failure_counters() so file failure counters can be cleared after diagnostics or recovery handling
• feat: add reset_policy() / file_reset_policy() so runtime append, auto-flush, and rotation settings can be restored to their initial defaults
• feat: add policy() / default_policy() and configured-logger forwarding helpers so current runtime file policy and original defaults can be read explicitly
• feat: add set_policy() / file_set_policy() so bundled append, auto-flush, and rotation policy can be applied in one runtime operation
• 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

Test

• test: cover parsing of core logger config fields
• test: cover nested formatter and queue config parsing
• test: cover config stringify and parse roundtrip behavior
• test: cover config-built queued text logger flushing and pending count behavior
• test: cover partial drain behavior for config-built queued logger
• 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 config-built file logger reopen and failure-counter helper access
• test: cover config-built file logger flush/close helpers and queued-file drain semantics
• test: cover append-mode observability and reopen-mode persistence for direct and config-built file sinks
• test: cover path and auto-flush introspection for direct and config-built file sinks
• test: cover rotation introspection for direct and config-built file sinks with and without configured rotation
• test: cover runtime auto-flush and rotation policy mutation for direct and config-built file sinks
• test: cover append-policy setter behavior and confirm subsequent reopen calls inherit the updated append mode
• 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
• build: verify bitlogger_async --target native and examples/async_basic --target native compile successfully

Example

• docs: update examples/basic with JSON config loading example
• docs: update examples/basic to use parse_and_build_logger(...) with explicit error handling in main
• docs: add examples/async_basic to show async worker startup and queue-backed logging flow
• docs: update examples/async_basic to use unified JSON-driven async logger config
• 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: clarify that config-built file loggers keep file control and observability helpers
• docs: document explicit file flush/close helpers for config-built file loggers
• docs: clarify append-mode observability and reopen append-policy semantics
• docs: document file path and auto-flush introspection helpers
• docs: document rotation introspection helpers for direct and config-built file sinks
• docs: document runtime file-policy setter helpers for direct and config-built file sinks
• docs: clarify explicit append-policy setter semantics for direct and config-built file sinks
• 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
• chore: ignore local .mooncakes/ cache directory in git

Notes

• 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