From 694414e0684acc6d7471661940bf214b041a59be Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Tue, 12 May 2026 15:05:58 +0800 Subject: [PATCH] :memo: Add file state export API docs --- docs/api/file-sink-policy-to-json.md | 74 +++++++++++++++++++++++ docs/api/file-sink-state-to-json.md | 74 +++++++++++++++++++++++ docs/api/runtime-file-state-to-json.md | 74 +++++++++++++++++++++++ docs/api/stringify-file-sink-policy.md | 75 ++++++++++++++++++++++++ docs/api/stringify-file-sink-state.md | 75 ++++++++++++++++++++++++ docs/api/stringify-runtime-file-state.md | 75 ++++++++++++++++++++++++ 6 files changed, 447 insertions(+) create mode 100644 docs/api/file-sink-policy-to-json.md create mode 100644 docs/api/file-sink-state-to-json.md create mode 100644 docs/api/runtime-file-state-to-json.md create mode 100644 docs/api/stringify-file-sink-policy.md create mode 100644 docs/api/stringify-file-sink-state.md create mode 100644 docs/api/stringify-runtime-file-state.md diff --git a/docs/api/file-sink-policy-to-json.md b/docs/api/file-sink-policy-to-json.md new file mode 100644 index 0000000..e8456e7 --- /dev/null +++ b/docs/api/file-sink-policy-to-json.md @@ -0,0 +1,74 @@ +--- +name: file-sink-policy-to-json +group: api +category: runtime +update-time: 20260512 +description: Convert FileSinkPolicy into a JSON value for runtime diagnostics, policy snapshots, or transport. +key-word: + - file + - policy + - json + - public +--- + +## File-sink-policy-to-json + +Convert `FileSinkPolicy` into a `JsonValue`. This helper exports append mode, auto-flush, and optional rotation as a structured runtime policy snapshot. + +### Interface + +```moonbit +pub fn file_sink_policy_to_json(policy : FileSinkPolicy) -> @json_parser.JsonValue {} +``` + +#### input + +- `policy : FileSinkPolicy` - File sink runtime policy to export. + +#### output + +- `JsonValue` - Structured JSON representation of the file policy. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- The output includes `append`, `auto_flush`, and `rotation`. +- `rotation` is exported as `null` when rotation is disabled. +- This helper exports runtime file policy, not current file health counters or availability. +- The JSON value is useful for policy snapshots, comparisons, and diagnostics payloads. + +### How to Use + +Here are some specific examples provided. + +#### When Need Structured Policy Snapshots + +When file sink policy should be embedded into a larger JSON payload: +```moonbit +let value = file_sink_policy_to_json(sink.policy()) +``` + +In this example, the runtime file policy becomes a reusable structured value. + +#### When Need Policy Comparison Data + +When current and default policy should be exported separately: +```moonbit +let current = file_sink_policy_to_json(sink.policy()) +``` + +In this example, callers can compare policy snapshots without formatting text first. + +### Error Case + +e.g.: +- If rotation is disabled, the exported `rotation` field is `null` rather than omitted. + +- If callers need direct text output, `stringify_file_sink_policy(...)` is the better API. + +### Notes + +1. Use this helper when downstream code expects `JsonValue` rather than text. + +2. It pairs naturally with `policy()` and `default_policy()` runtime accessors. diff --git a/docs/api/file-sink-state-to-json.md b/docs/api/file-sink-state-to-json.md new file mode 100644 index 0000000..ea3a297 --- /dev/null +++ b/docs/api/file-sink-state-to-json.md @@ -0,0 +1,74 @@ +--- +name: file-sink-state-to-json +group: api +category: runtime +update-time: 20260512 +description: Convert FileSinkState into a JSON value for file sink diagnostics and state transport. +key-word: + - file + - state + - json + - public +--- + +## File-sink-state-to-json + +Convert `FileSinkState` into a `JsonValue`. This helper exports file path, availability, policy flags, rotation config, and failure counters in a structured form. + +### Interface + +```moonbit +pub fn file_sink_state_to_json(state : FileSinkState) -> @json_parser.JsonValue {} +``` + +#### input + +- `state : FileSinkState` - File sink state snapshot to export. + +#### output + +- `JsonValue` - Structured JSON representation of the file sink state. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- The output includes `path`, `available`, `append`, `auto_flush`, failure counters, and `rotation`. +- `rotation` is exported as `null` when rotation is disabled. +- This helper exports state snapshots, not mutable runtime control handles. +- It is useful when file sink state should be embedded into larger diagnostics payloads. + +### How to Use + +Here are some specific examples provided. + +#### When Need Structured File Diagnostics + +When file sink status should be composed into a larger JSON object: +```moonbit +let value = file_sink_state_to_json(sink.state()) +``` + +In this example, callers receive a structured file-state snapshot instead of plain text. + +#### When Need Runtime State Snapshots For Tooling + +When support tooling should ingest file sink state programmatically: +```moonbit +let snapshot = file_sink_state_to_json(state) +``` + +In this example, the helper exposes all major file-state fields in machine-readable form. + +### Error Case + +e.g.: +- If the file is unavailable, the exported snapshot still serializes normally with `available=false`. + +- If callers need direct text output, `stringify_file_sink_state(...)` is the better API. + +### Notes + +1. Use this helper when diagnostics consumers expect `JsonValue`. + +2. It pairs naturally with `FileSink::state()` and `ConfiguredLogger::file_state()`. diff --git a/docs/api/runtime-file-state-to-json.md b/docs/api/runtime-file-state-to-json.md new file mode 100644 index 0000000..f1861f6 --- /dev/null +++ b/docs/api/runtime-file-state-to-json.md @@ -0,0 +1,74 @@ +--- +name: runtime-file-state-to-json +group: api +category: runtime +update-time: 20260512 +description: Convert RuntimeFileState into a JSON value that combines file status with outer queue runtime metrics. +key-word: + - runtime + - file + - state + - public +--- + +## Runtime-file-state-to-json + +Convert `RuntimeFileState` into a `JsonValue`. This helper exports both file sink status and outer queue metrics for queued file runtime diagnostics. + +### Interface + +```moonbit +pub fn runtime_file_state_to_json(state : RuntimeFileState) -> @json_parser.JsonValue {} +``` + +#### input + +- `state : RuntimeFileState` - Combined file and queue runtime snapshot. + +#### output + +- `JsonValue` - Structured JSON representation of the runtime file state. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- The output includes `file`, `queued`, `pending_count`, and `dropped_count`. +- `file` is itself exported as a nested file sink state object. +- This helper is richer than `file_sink_state_to_json(...)` because it also carries queue wrapping context. +- It is useful for `ConfiguredLogger::file_runtime_state()` and similar queued-file diagnostics flows. + +### How to Use + +Here are some specific examples provided. + +#### When Need Structured Queued-file Diagnostics + +When file and queue status should be exported together: +```moonbit +let value = runtime_file_state_to_json(snapshot) +``` + +In this example, callers receive a machine-readable combined runtime snapshot. + +#### When Need Support Payload Composition + +When queued file runtime data should be embedded into a larger JSON object: +```moonbit +let payload = runtime_file_state_to_json(state) +``` + +In this example, the helper keeps file-plus-queue diagnostics in one reusable JSON value. + +### Error Case + +e.g.: +- If `queued=false`, the state still serializes normally with queue counters present. + +- If callers need direct text output, `stringify_runtime_file_state(...)` is the better API. + +### Notes + +1. Use this helper when file and queue runtime context should stay together. + +2. It is especially useful for configured queued file loggers. diff --git a/docs/api/stringify-file-sink-policy.md b/docs/api/stringify-file-sink-policy.md new file mode 100644 index 0000000..6bb3ba0 --- /dev/null +++ b/docs/api/stringify-file-sink-policy.md @@ -0,0 +1,75 @@ +--- +name: stringify-file-sink-policy +group: api +category: runtime +update-time: 20260512 +description: Serialize FileSinkPolicy into compact or pretty JSON text for diagnostics and policy snapshots. +key-word: + - file + - policy + - stringify + - public +--- + +## Stringify-file-sink-policy + +Serialize `FileSinkPolicy` into JSON text. This helper is the most direct export path for runtime file policy snapshots. + +### Interface + +```moonbit +pub fn stringify_file_sink_policy(policy : FileSinkPolicy, pretty~ : Bool = false) -> String {} +``` + +#### input + +- `policy : FileSinkPolicy` - File sink runtime policy to serialize. +- `pretty : Bool` - Whether JSON should be pretty-printed. + +#### output + +- `String` - Serialized JSON text for the file policy. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- `pretty=false` returns compact JSON. +- `pretty=true` returns indented JSON for human inspection. +- This helper builds on top of `file_sink_policy_to_json(...)`. +- The output is suited for support dumps, policy snapshots, and generated diagnostics text. + +### How to Use + +Here are some specific examples provided. + +#### When Need Human-readable Policy Output + +When current file policy should be printed for diagnostics: +```moonbit +println(stringify_file_sink_policy(sink.policy(), pretty=true)) +``` + +In this example, the runtime file policy is rendered in readable JSON. + +#### When Need Compact Policy Export + +When a file policy snapshot should stay small: +```moonbit +let text = stringify_file_sink_policy(sink.policy()) +``` + +In this example, compact JSON is produced without extra formatting logic. + +### Error Case + +e.g.: +- If callers need a `JsonValue` for composition rather than text, `file_sink_policy_to_json(...)` is the better API. + +- If rotation is disabled, the output still includes `rotation` as `null`. + +### Notes + +1. Use this helper for direct textual policy snapshots. + +2. `pretty=true` is useful when operators or support tooling are the audience. diff --git a/docs/api/stringify-file-sink-state.md b/docs/api/stringify-file-sink-state.md new file mode 100644 index 0000000..38d03f9 --- /dev/null +++ b/docs/api/stringify-file-sink-state.md @@ -0,0 +1,75 @@ +--- +name: stringify-file-sink-state +group: api +category: runtime +update-time: 20260512 +description: Serialize FileSinkState into compact or pretty JSON text for diagnostics and support output. +key-word: + - file + - state + - stringify + - public +--- + +## Stringify-file-sink-state + +Serialize `FileSinkState` into JSON text. This helper is the most direct export path for file sink diagnostics snapshots. + +### Interface + +```moonbit +pub fn stringify_file_sink_state(state : FileSinkState, pretty~ : Bool = false) -> String {} +``` + +#### input + +- `state : FileSinkState` - File sink state snapshot to serialize. +- `pretty : Bool` - Whether JSON should be pretty-printed. + +#### output + +- `String` - Serialized JSON text for the file sink state. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- `pretty=false` returns compact JSON. +- `pretty=true` returns indented JSON for human diagnostics. +- This helper builds on top of `file_sink_state_to_json(...)`. +- The output is well-suited for support dumps, incident reports, and log snapshots. + +### How to Use + +Here are some specific examples provided. + +#### When Need Human-readable File Diagnostics + +When file sink status should be printed for operators: +```moonbit +println(stringify_file_sink_state(sink.state(), pretty=true)) +``` + +In this example, the full file-state snapshot is rendered in readable JSON. + +#### When Need Compact State Export + +When a snapshot should stay small: +```moonbit +let text = stringify_file_sink_state(sink.state()) +``` + +In this example, compact JSON is returned without extra formatting logic. + +### Error Case + +e.g.: +- If the file is unavailable, the output still serializes normally with `available=false`. + +- If callers need structured composition instead of text, `file_sink_state_to_json(...)` is the better API. + +### Notes + +1. Use this helper for direct textual file-state snapshots. + +2. `pretty=true` is useful for operator-facing diagnostics and support output. diff --git a/docs/api/stringify-runtime-file-state.md b/docs/api/stringify-runtime-file-state.md new file mode 100644 index 0000000..315e231 --- /dev/null +++ b/docs/api/stringify-runtime-file-state.md @@ -0,0 +1,75 @@ +--- +name: stringify-runtime-file-state +group: api +category: runtime +update-time: 20260512 +description: Serialize RuntimeFileState into compact or pretty JSON text for queued-file diagnostics and support output. +key-word: + - runtime + - file + - state + - public +--- + +## Stringify-runtime-file-state + +Serialize `RuntimeFileState` into JSON text. This helper is the most direct export path for combined file-and-queue runtime diagnostics. + +### Interface + +```moonbit +pub fn stringify_runtime_file_state(state : RuntimeFileState, pretty~ : Bool = false) -> String {} +``` + +#### input + +- `state : RuntimeFileState` - Combined file and queue runtime snapshot to serialize. +- `pretty : Bool` - Whether JSON should be pretty-printed. + +#### output + +- `String` - Serialized JSON text for the runtime file state. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- `pretty=false` returns compact JSON. +- `pretty=true` returns indented JSON for human diagnostics. +- This helper builds on top of `runtime_file_state_to_json(...)`. +- The output is useful when queued file runtime state should be printed directly during support or incident handling. + +### How to Use + +Here are some specific examples provided. + +#### When Need Human-readable Queued-file Diagnostics + +When a queued file runtime snapshot should be printed directly: +```moonbit +println(stringify_runtime_file_state(snapshot, pretty=true)) +``` + +In this example, both file state and queue metrics are shown in one readable JSON payload. + +#### When Need Compact Runtime Snapshot Export + +When a combined file-and-queue snapshot should stay small: +```moonbit +let text = stringify_runtime_file_state(snapshot) +``` + +In this example, compact JSON is returned without extra formatting logic. + +### Error Case + +e.g.: +- If callers need a `JsonValue` rather than text, `runtime_file_state_to_json(...)` is the better API. + +- If queue wrapping is not relevant, `stringify_file_sink_state(...)` may be the simpler API. + +### Notes + +1. Use this helper when queued-file diagnostics should be emitted as one JSON string. + +2. `pretty=true` is useful for support output and manual inspection.