📝 Add configured logger file control API docs

2026-05-30 15:42:25 +00:00 · 2026-05-12 14:52:23 +08:00
parent 87cf651c4c
commit cfde700526
11 changed files with 828 additions and 0 deletions
@@ -0,0 +1,75 @@
+---
+name: configured-logger-file-append-mode
+group: api
+category: runtime
+update-time: 20260512
+description: Read the current append-mode policy used by the configured runtime file sink.
+key-word:
+    - logger
+    - runtime
+    - file
+    - public
+---
+
+## Configured-logger-file-append-mode
+
+Read the current append-mode policy used by a `ConfiguredLogger` file sink. This helper exposes whether future reopen behavior is currently append-oriented.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_append_mode(self : ConfiguredLogger) -> Bool {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose append-mode policy should be inspected.
+
+#### output
+
+- `Bool` - Current append-mode policy for the file sink.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- File-backed sinks report their current append policy.
+- Queued file sinks forward the policy from the wrapped file sink.
+- Non-file sinks return `false`.
+- This helper reports runtime file policy, not whether a file is currently writable.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Runtime Append-policy Visibility
+
+When diagnostics should show how future reopen behavior is configured:
+```moonbit
+let append = logger.file_append_mode()
+```
+
+In this example, the configured logger exposes current reopen policy directly.
+
+#### When Validate Runtime Policy Changes
+
+When policy mutation should be observable after a setter call:
+```moonbit
+ignore(logger.file_set_append_mode(true))
+ignore(logger.file_append_mode())
+```
+
+In this example, callers verify the updated append-mode policy.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns `false`.
+
+- If callers need the full current file policy rather than just append mode, `file_policy()` is the better API.
+
+### Notes
+
+1. Use this helper when append policy is the only file setting you need to inspect.
+
+2. Pair it with reopen helpers when debugging runtime file behavior.
@@ -0,0 +1,75 @@
+---
+name: configured-logger-file-auto-flush
+group: api
+category: runtime
+update-time: 20260512
+description: Read whether the configured runtime file sink currently has auto-flush enabled.
+key-word:
+    - logger
+    - runtime
+    - file
+    - public
+---
+
+## Configured-logger-file-auto-flush
+
+Read whether auto-flush is currently enabled on a `ConfiguredLogger` file sink. This helper exposes one important runtime durability policy flag.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_auto_flush(self : ConfiguredLogger) -> Bool {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose auto-flush policy should be inspected.
+
+#### output
+
+- `Bool` - Whether auto-flush is currently enabled.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- File-backed sinks report their current auto-flush policy.
+- Queued file sinks forward the policy from the wrapped file sink.
+- Non-file sinks return `false`.
+- This helper exposes policy state only and does not force any flush action.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Runtime Durability Visibility
+
+When diagnostics should expose whether each write auto-flushes:
+```moonbit
+let enabled = logger.file_auto_flush()
+```
+
+In this example, runtime file durability policy is surfaced directly.
+
+#### When Validate Policy Updates
+
+When code should observe auto-flush after a setter call:
+```moonbit
+ignore(logger.file_set_auto_flush(true))
+ignore(logger.file_auto_flush())
+```
+
+In this example, callers verify the updated policy.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns `false`.
+
+- If callers need to actually flush the file, `file_flush()` is the operational API.
+
+### Notes
+
+1. Use this helper to inspect runtime durability policy.
+
+2. It complements `file_set_auto_flush(...)` rather than replacing real flush actions.
@@ -0,0 +1,74 @@
+---
+name: configured-logger-file-clear-rotation
+group: api
+category: runtime
+update-time: 20260512
+description: Disable runtime rotation on the configured file-backed logger sink.
+key-word:
+    - logger
+    - runtime
+    - file
+    - public
+---
+
+## Configured-logger-file-clear-rotation
+
+Disable runtime rotation on a `ConfiguredLogger` file sink. This helper is the direct shortcut for clearing rotation policy.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_clear_rotation(self : ConfiguredLogger) -> Bool {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose rotation policy should be cleared.
+
+#### output
+
+- `Bool` - Whether the policy update was applied.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- File-backed sinks clear their runtime rotation policy.
+- Queued file sinks forward the update to the wrapped file sink.
+- Non-file sinks return `false`.
+- This helper is equivalent in intent to setting rotation to `None`, but is clearer at the call site.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need To Disable Rotation Explicitly
+
+When runtime file rotation should be turned off:
+```moonbit
+ignore(logger.file_clear_rotation())
+```
+
+In this example, rotation policy is removed directly.
+
+#### When Need A Clear Intent Shortcut
+
+When code should make the disable-rotation intent obvious:
+```moonbit
+let ok = logger.file_clear_rotation()
+```
+
+In this example, the call site reads more clearly than a generic config setter.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns `false`.
+
+- If callers need to switch to another rotation config rather than disable rotation, `file_set_rotation(...)` is the better API.
+
+### Notes
+
+1. Use this helper when the desired effect is simply “rotation off”.
+
+2. It is clearer than passing `None` through a broader setter when intent matters.
@@ -0,0 +1,74 @@
+---
+name: configured-logger-file-reopen-append
+group: api
+category: runtime
+update-time: 20260512
+description: Reopen the file sink behind a configured runtime logger in append mode.
+key-word:
+    - logger
+    - runtime
+    - file
+    - public
+---
+
+## Configured-logger-file-reopen-append
+
+Reopen the file sink behind a `ConfiguredLogger` in append mode. This helper is the explicit append-oriented recovery shortcut.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_reopen_append(self : ConfiguredLogger) -> Bool {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose file sink should be reopened in append mode.
+
+#### output
+
+- `Bool` - Whether reopen succeeded.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- Plain file sinks reopen in append mode.
+- Queued file sinks forward reopen behavior to the wrapped file sink.
+- This helper is a specialized shortcut for a common reopen mode.
+- Non-file sinks return `false`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Append-preserving Recovery
+
+When file logging should continue appending after a reopen:
+```moonbit
+ignore(logger.file_reopen_append())
+```
+
+In this example, reopen behavior is fixed to append mode.
+
+#### When Want An Explicit Append Shortcut
+
+When code should avoid manually setting append overrides:
+```moonbit
+let ok = logger.file_reopen_append()
+```
+
+In this example, the call site states append intent directly.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns `false`.
+
+- If callers need truncate behavior instead, `file_reopen_truncate()` is the correct API.
+
+### Notes
+
+1. Use this helper for explicit append-mode reopen flows.
+
+2. It is especially useful after transient file availability issues.
@@ -0,0 +1,74 @@
+---
+name: configured-logger-file-reopen-truncate
+group: api
+category: runtime
+update-time: 20260512
+description: Reopen the file sink behind a configured runtime logger in truncate mode.
+key-word:
+    - logger
+    - runtime
+    - file
+    - public
+---
+
+## Configured-logger-file-reopen-truncate
+
+Reopen the file sink behind a `ConfiguredLogger` in truncate mode. This helper is the explicit truncate-oriented recovery or reset shortcut.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_reopen_truncate(self : ConfiguredLogger) -> Bool {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose file sink should be reopened in truncate mode.
+
+#### output
+
+- `Bool` - Whether reopen succeeded.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- Plain file sinks reopen in truncate mode.
+- Queued file sinks forward reopen behavior to the wrapped file sink.
+- This helper is a specialized shortcut for a common reset-style reopen mode.
+- Non-file sinks return `false`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Fresh Output File
+
+When a runtime file should be reopened from an empty state:
+```moonbit
+ignore(logger.file_reopen_truncate())
+```
+
+In this example, reopen behavior truncates the file before future writes continue.
+
+#### When Want An Explicit Truncate Shortcut
+
+When code should make destructive reopen intent obvious:
+```moonbit
+let ok = logger.file_reopen_truncate()
+```
+
+In this example, the call site expresses reset-style reopen behavior directly.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns `false`.
+
+- If callers want to preserve existing file content, `file_reopen_append()` is the correct API.
+
+### Notes
+
+1. Use this helper when starting from a fresh file is intentional.
+
+2. Truncate-mode reopen is a stronger action than generic reopen recovery.
@@ -0,0 +1,74 @@
+---
+name: configured-logger-file-reopen-with-current-policy
+group: api
+category: runtime
+update-time: 20260512
+description: Reopen the file sink behind a configured runtime logger using its currently stored runtime policy.
+key-word:
+    - logger
+    - runtime
+    - file
+    - public
+---
+
+## Configured-logger-file-reopen-with-current-policy
+
+Reopen the file sink behind a `ConfiguredLogger` using the currently stored runtime policy. This helper is useful when callers want recovery behavior without supplying a one-off append override.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_reopen_with_current_policy(self : ConfiguredLogger) -> Bool {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose file sink should be reopened with current policy.
+
+#### output
+
+- `Bool` - Whether reopen succeeded.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- Plain file sinks reuse their current stored reopen policy.
+- Queued file sinks forward reopen behavior to the wrapped file sink.
+- This helper differs from `file_reopen(...)` because it does not accept a per-call append override.
+- Non-file sinks return `false`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Policy-preserving Recovery
+
+When a file sink should be reopened without changing runtime append behavior:
+```moonbit
+ignore(logger.file_reopen_with_current_policy())
+```
+
+In this example, recovery reuses the runtime policy already stored on the sink.
+
+#### When Separate Recovery From Policy Mutation
+
+When append mode should be controlled elsewhere:
+```moonbit
+let ok = logger.file_reopen_with_current_policy()
+```
+
+In this example, reopen is explicit while policy mutation stays separate.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns `false`.
+
+- If callers want to change append behavior during reopen, `file_reopen(...)` or `file_reopen_append()` / `file_reopen_truncate()` are better APIs.
+
+### Notes
+
+1. Use this helper when recovery should respect the currently stored runtime policy.
+
+2. It is clearer than passing no override through a more general reopen API.
@@ -0,0 +1,77 @@
+---
+name: configured-logger-file-rotation-config
+group: api
+category: runtime
+update-time: 20260512
+description: Read the current rotation configuration used by the configured runtime file sink.
+key-word:
+    - logger
+    - runtime
+    - file
+    - public
+---
+
+## Configured-logger-file-rotation-config
+
+Read the current rotation configuration used by a `ConfiguredLogger` file sink. This helper exposes the active runtime rotation parameters when rotation is enabled.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_rotation_config(self : ConfiguredLogger) -> FileRotation? {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose rotation config should be inspected.
+
+#### output
+
+- `FileRotation?` - Current rotation config, or `None` if rotation is disabled or the sink is not file-backed.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- File-backed sinks return their current rotation configuration when enabled.
+- Queued file sinks forward the config from the wrapped file sink.
+- Non-file sinks return `None`.
+- This helper is useful when callers need active runtime rotation parameters rather than only a boolean flag.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Runtime Rotation Parameters
+
+When support output should include the active rotation policy:
+```moonbit
+let rotation = logger.file_rotation_config()
+```
+
+In this example, the configured logger exposes live runtime rotation parameters directly.
+
+#### When Branch On Optional Rotation Presence
+
+When code should react differently for rotating file sinks:
+```moonbit
+match logger.file_rotation_config() {
+  Some(cfg) => ignore(cfg)
+  None => ()
+}
+```
+
+In this example, optional return shape reflects whether rotation is active.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns `None`.
+
+- If callers only need to know whether rotation is enabled, `file_rotation_enabled()` is the simpler API.
+
+### Notes
+
+1. Use this helper when current runtime rotation parameters matter.
+
+2. It is useful after policy updates or recovery flows.
@@ -0,0 +1,76 @@
+---
+name: configured-logger-file-rotation-enabled
+group: api
+category: runtime
+update-time: 20260512
+description: Read whether rotation is currently enabled on the configured runtime file sink.
+key-word:
+    - logger
+    - runtime
+    - file
+    - public
+---
+
+## Configured-logger-file-rotation-enabled
+
+Read whether rotation is currently enabled on a `ConfiguredLogger` file sink. This helper exposes whether runtime rotation policy is active.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_rotation_enabled(self : ConfiguredLogger) -> Bool {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose rotation state should be inspected.
+
+#### output
+
+- `Bool` - Whether rotation is currently enabled.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- File-backed sinks report whether a rotation config is active.
+- Queued file sinks forward the state from the wrapped file sink.
+- Non-file sinks return `false`.
+- This helper is narrower than `file_rotation_config()` when only a yes/no check is needed.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Runtime Rotation Visibility
+
+When support output should expose whether rotation is active:
+```moonbit
+let rotating = logger.file_rotation_enabled()
+```
+
+In this example, callers get a direct boolean answer without inspecting config objects.
+
+#### When Guard Rotation-specific Behavior
+
+When logic should only run for rotating file sinks:
+```moonbit
+if logger.file_rotation_enabled() {
+  println("rotation active")
+}
+```
+
+In this example, runtime policy can drive control flow.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns `false`.
+
+- If callers need the actual rotation parameters, `file_rotation_config()` is the better API.
+
+### Notes
+
+1. Use this helper for simple runtime rotation checks.
+
+2. Pair it with `file_rotation_config()` when parameters also matter.
@@ -0,0 +1,76 @@
+---
+name: configured-logger-file-set-append-mode
+group: api
+category: runtime
+update-time: 20260512
+description: Update the append-mode policy used by the configured runtime file sink for later reopen behavior.
+key-word:
+    - logger
+    - runtime
+    - file
+    - public
+---
+
+## Configured-logger-file-set-append-mode
+
+Update the append-mode policy used by a `ConfiguredLogger` file sink. This helper changes future reopen behavior without forcing an immediate reopen.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_set_append_mode(self : ConfiguredLogger, append : Bool) -> Bool {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose append-mode policy should change.
+- `append : Bool` - New append-mode policy.
+
+#### output
+
+- `Bool` - Whether the policy update was applied.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- File-backed sinks update their stored append policy.
+- Queued file sinks forward the policy update to the wrapped file sink.
+- This helper updates policy only; it does not force immediate reopen.
+- Non-file sinks return `false`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need To Change Future Reopen Behavior
+
+When runtime recovery should later prefer append mode explicitly:
+```moonbit
+ignore(logger.file_set_append_mode(true))
+```
+
+In this example, later reopen operations will use the updated append policy.
+
+#### When Want To Separate Policy Mutation From Reopen Timing
+
+When code should update policy now and reopen later:
+```moonbit
+ignore(logger.file_set_append_mode(false))
+ignore(logger.file_reopen_with_current_policy())
+```
+
+In this example, policy mutation and reopen timing remain separate decisions.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns `false`.
+
+- If callers need an immediate reopen as part of the same operation, one of the reopen helpers should be used afterward.
+
+### Notes
+
+1. This helper changes stored policy, not live file-handle state by itself.
+
+2. It is useful when recovery logic wants to stage reopen behavior in advance.
@@ -0,0 +1,75 @@
+---
+name: configured-logger-file-set-auto-flush
+group: api
+category: runtime
+update-time: 20260512
+description: Update the auto-flush policy used by the configured runtime file sink.
+key-word:
+    - logger
+    - runtime
+    - file
+    - public
+---
+
+## Configured-logger-file-set-auto-flush
+
+Update the auto-flush policy used by a `ConfiguredLogger` file sink. This helper changes runtime durability behavior without rebuilding the logger.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_set_auto_flush(self : ConfiguredLogger, enabled : Bool) -> Bool {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose auto-flush policy should change.
+- `enabled : Bool` - New auto-flush setting.
+
+#### output
+
+- `Bool` - Whether the policy update was applied.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- File-backed sinks update their runtime auto-flush policy.
+- Queued file sinks forward the update to the wrapped file sink.
+- Non-file sinks return `false`.
+- This helper changes policy only; it does not itself flush pending data.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Runtime Durability Tuning
+
+When a file sink should start flushing each write automatically:
+```moonbit
+ignore(logger.file_set_auto_flush(true))
+```
+
+In this example, runtime policy is updated without rebuilding the configured logger.
+
+#### When Need To Relax Flush Pressure
+
+When a file sink should stop auto-flushing for throughput reasons:
+```moonbit
+let ok = logger.file_set_auto_flush(false)
+```
+
+In this example, the call site updates policy explicitly and can inspect the result.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns `false`.
+
+- If callers need an immediate flush action, `file_flush()` is the operational API.
+
+### Notes
+
+1. Use this helper for runtime durability tuning.
+
+2. Pair it with `file_auto_flush()` to verify the active policy.
@@ -0,0 +1,78 @@
+---
+name: configured-logger-file-set-rotation
+group: api
+category: runtime
+update-time: 20260512
+description: Update the rotation configuration used by the configured runtime file sink.
+key-word:
+    - logger
+    - runtime
+    - file
+    - public
+---
+
+## Configured-logger-file-set-rotation
+
+Update the rotation configuration used by a `ConfiguredLogger` file sink. This helper changes runtime file rotation behavior without rebuilding the logger.
+
+### Interface
+
+```moonbit
+pub fn ConfiguredLogger::file_set_rotation(
+  self : ConfiguredLogger,
+  rotation : FileRotation?,
+) -> Bool {}
+```
+
+#### input
+
+- `self : ConfiguredLogger` - Config-driven runtime logger whose rotation policy should change.
+- `rotation : FileRotation?` - New rotation config, or `None` to disable rotation.
+
+#### output
+
+- `Bool` - Whether the policy update was applied.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- File-backed sinks update their runtime rotation policy.
+- Queued file sinks forward the update to the wrapped file sink.
+- Passing `None` disables rotation.
+- Non-file sinks return `false`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Runtime Rotation Tuning
+
+When a file sink should enable or change rotation dynamically:
+```moonbit
+ignore(logger.file_set_rotation(Some(file_rotation(1024, max_backups=3))))
+```
+
+In this example, runtime rotation behavior is updated without rebuilding the logger.
+
+#### When Need To Disable Rotation
+
+When the file sink should stop rotating:
+```moonbit
+let ok = logger.file_set_rotation(None)
+```
+
+In this example, the runtime file sink has its rotation policy cleared explicitly.
+
+### Error Case
+
+e.g.:
+- If the configured sink is not file-backed, the method returns `false`.
+
+- If callers only want to remove rotation, `file_clear_rotation()` is the more direct API.
+
+### Notes
+
+1. Use this helper when setting a full runtime rotation config.
+
+2. It is useful for operational tuning without rebuilding the logger.