diff --git a/docs/api/file-sink-default-policy.md b/docs/api/file-sink-default-policy.md new file mode 100644 index 0000000..5930f65 --- /dev/null +++ b/docs/api/file-sink-default-policy.md @@ -0,0 +1,73 @@ +--- +name: file-sink-default-policy +group: api +category: sink +update-time: 20260613 +description: Read the initial default file policy captured by a FileSink. +key-word: + - file + - sink + - policy + - public +--- + +## File-sink-default-policy + +Read the initial default file policy captured by a `FileSink`. This helper exposes the baseline file policy recorded when the sink was created. + +### Interface + +```moonbit +pub fn FileSink::default_policy(self : FileSink) -> FileSinkPolicy { +``` + +#### input + +- `self : FileSink` - File sink whose default file policy should be inspected. + +#### output + +- `FileSinkPolicy` - Initial default file policy. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- The returned policy is built from the sink's stored default append, auto-flush, and rotation values. +- This helper is useful when callers need to compare runtime drift or restore defaults later. +- It is observation-only and does not mutate sink state. + +### How to Use + +Here are some specific examples provided. + +#### When Need Baseline Policy Visibility + +When diagnostics should show the original file policy separately from the live one: +```moonbit +let defaults = sink.default_policy() +``` + +In this example, the direct file sink exposes its original file policy snapshot. + +#### When Prepare For Policy Reset Logic + +When tooling should capture or compare default settings explicitly: +```moonbit +let original = sink.default_policy() +``` + +In this example, callers can reason about factory policy separately from runtime changes. + +### Error Case + +e.g.: +- If callers only need to know whether runtime drift exists, `policy_matches_default()` is the simpler API. + +- This helper does not say whether the current sink handle is available. + +### Notes + +1. Use this helper when the original file policy matters operationally. + +2. It complements `policy()` and `reset_policy()`. diff --git a/docs/api/file-sink-policy-matches-default.md b/docs/api/file-sink-policy-matches-default.md new file mode 100644 index 0000000..04f5f96 --- /dev/null +++ b/docs/api/file-sink-policy-matches-default.md @@ -0,0 +1,76 @@ +--- +name: file-sink-policy-matches-default +group: api +category: sink +update-time: 20260613 +description: Read whether the current FileSink policy still matches its default policy. +key-word: + - file + - sink + - policy + - public +--- + +## File-sink-policy-matches-default + +Read whether the current runtime file policy of a `FileSink` still matches its default policy. This helper is useful for detecting direct policy drift on the sink. + +### Interface + +```moonbit +pub fn FileSink::policy_matches_default(self : FileSink) -> Bool { +``` + +#### input + +- `self : FileSink` - File sink whose runtime policy drift should be checked. + +#### output + +- `Bool` - Whether the current runtime file policy still matches the default. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- The method compares current append and auto-flush settings directly. +- Rotation drift is checked structurally, comparing `max_bytes` and `max_backups` when both sides are present. +- This helper is a compact drift signal when callers do not need to compare full policy objects directly. +- It does not mutate sink state. + +### How to Use + +Here are some specific examples provided. + +#### When Need Drift Detection + +When diagnostics should report whether file policy changed after startup: +```moonbit +let unchanged = sink.policy_matches_default() +``` + +In this example, the direct sink exposes whether runtime file policy still matches the baseline. + +#### When Gate Reset Logic + +When code should only reset policy if drift exists: +```moonbit +if !sink.policy_matches_default() { + sink.reset_policy() +} +``` + +In this example, policy reset only happens when runtime state diverged from defaults. + +### Error Case + +e.g.: +- If callers need the exact differences instead of a boolean drift signal, they should inspect both `policy()` and `default_policy()`. + +- This helper only compares policy state; it does not report open, write, or flush failures. + +### Notes + +1. Use this helper for compact direct policy drift checks. + +2. It is especially useful before calling reset-style operations. diff --git a/docs/api/file-sink-policy-method.md b/docs/api/file-sink-policy-method.md new file mode 100644 index 0000000..e92a6ca --- /dev/null +++ b/docs/api/file-sink-policy-method.md @@ -0,0 +1,74 @@ +--- +name: file-sink-policy-method +group: api +category: sink +update-time: 20260613 +description: Read the current runtime file policy from a FileSink. +key-word: + - file + - sink + - policy + - public +--- + +## File-sink-policy-method + +Read the current runtime file policy from a `FileSink`. This helper exposes the active append, auto-flush, and rotation settings as one policy object on the concrete sink. + +### Interface + +```moonbit +pub fn FileSink::policy(self : FileSink) -> FileSinkPolicy { +``` + +#### input + +- `self : FileSink` - File sink whose current file policy should be inspected. + +#### output + +- `FileSinkPolicy` - Current runtime file policy. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- The returned policy is constructed from the sink's current append, auto-flush, and rotation settings. +- This helper is broader than `append_mode()` or `auto_flush_enabled()` because it returns the whole policy object. +- It is observation-only and does not mutate sink state. + +### How to Use + +Here are some specific examples provided. + +#### When Need Full Runtime Policy Visibility + +When diagnostics should inspect the active file policy as one object: +```moonbit +let policy = sink.policy() +``` + +In this example, append, flush, and rotation settings are read together from the direct sink. + +#### When Compare Current And Default Policy + +When runtime drift from defaults should be inspected explicitly: +```moonbit +let current = sink.policy() +let defaults = sink.default_policy() +``` + +In this example, callers can compare current runtime settings with the initial policy snapshot. + +### Error Case + +e.g.: +- If callers only need one field from the policy, a narrower helper may be simpler. + +- This helper describes policy state, not whether the sink is currently available. + +### Notes + +1. Use this helper when file policy should be handled as one object. + +2. Pair it with `set_policy(...)` for roundtrip-style policy management. diff --git a/docs/api/file-sink-set-rotation.md b/docs/api/file-sink-set-rotation.md new file mode 100644 index 0000000..268c378 --- /dev/null +++ b/docs/api/file-sink-set-rotation.md @@ -0,0 +1,71 @@ +--- +name: file-sink-set-rotation +group: api +category: sink +update-time: 20260613 +description: Update the rotation configuration used by a FileSink. +key-word: + - file + - sink + - rotation + - public +--- + +## File-sink-set-rotation + +Update the rotation configuration used by a `FileSink`. This helper changes direct runtime file rotation behavior without rebuilding or reopening the sink. + +### Interface + +```moonbit +pub fn FileSink::set_rotation(self : FileSink, rotation : FileRotation?) -> Unit { +``` + +#### input + +- `self : FileSink` - File sink whose rotation policy should change. +- `rotation : FileRotation?` - New rotation config, or `None` to disable rotation. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This method updates runtime rotation policy only. +- Passing `None` disables rotation. +- It does not reopen the sink or rotate immediately by itself. +- Append and auto-flush settings are left unchanged. + +### How to Use + +Here are some specific examples provided. + +#### When Need Runtime Rotation Tuning + +When a concrete file sink should enable or change rotation dynamically: +```moonbit +sink.set_rotation(Some(file_rotation(1024, max_backups=3))) +``` + +In this example, direct runtime rotation behavior is updated without rebuilding the sink. + +#### When Need To Disable Rotation + +When the file sink should stop rotating: +```moonbit +sink.set_rotation(None) +``` + +In this example, the sink has its rotation policy cleared explicitly. + +### Error Case + +e.g.: +- If callers only want to remove rotation, `clear_rotation()` is the more direct API. + +- This helper does not report past rotation failures; use `rotation_failures()` or `state()` for diagnostics. + +### Notes + +1. Use this helper when setting a full runtime rotation config. + +2. It is useful for operational tuning on a concrete file sink without rebuilding it. diff --git a/docs/api/file-sink-state-method.md b/docs/api/file-sink-state-method.md new file mode 100644 index 0000000..f900bd3 --- /dev/null +++ b/docs/api/file-sink-state-method.md @@ -0,0 +1,74 @@ +--- +name: file-sink-state-method +group: api +category: sink +update-time: 20260613 +description: Read the current file sink snapshot from a FileSink. +key-word: + - file + - sink + - state + - public +--- + +## File-sink-state-method + +Read the current file sink snapshot from a `FileSink`. This helper exposes path, availability, policy flags, rotation config, and failure counters as one object on the direct sink. + +### Interface + +```moonbit +pub fn FileSink::state(self : FileSink) -> FileSinkState { +``` + +#### input + +- `self : FileSink` - File sink whose file state snapshot should be inspected. + +#### output + +- `FileSinkState` - Current file sink snapshot. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- The snapshot includes path, availability, append policy, auto-flush policy, rotation config, and failure counters. +- `available` is derived from `is_available()`. +- This helper is broader than individual counters or policy accessors because it aggregates core file status into one read. +- It does not mutate sink state. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Full File Health Snapshot + +When diagnostics should inspect direct file state as one object: +```moonbit +let state = sink.state() +``` + +In this example, callers receive a single file-state snapshot instead of querying each property separately. + +#### When Need To Export File Diagnostics + +When a support path should serialize current file state: +```moonbit +println(stringify_file_sink_state(sink.state(), pretty=true)) +``` + +In this example, the direct sink snapshot can be exported through the existing JSON helpers. + +### Error Case + +e.g.: +- If callers only need one small part of direct file state, a narrower accessor may be simpler. + +- This helper is a snapshot read, not an operational repair action. + +### Notes + +1. Use this helper for the main one-shot file status snapshot. + +2. Prefer it over individual counters when broader direct file diagnostics are needed. diff --git a/docs/api/index.md b/docs/api/index.md index e95e0e0..3eebef9 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -149,6 +149,11 @@ BitLogger API navigation. - [file-sink-set-append-mode.md](./file-sink-set-append-mode.md) - [file-sink-set-auto-flush.md](./file-sink-set-auto-flush.md) - [file-sink-clear-rotation.md](./file-sink-clear-rotation.md) +- [file-sink-set-rotation.md](./file-sink-set-rotation.md) +- [file-sink-policy-method.md](./file-sink-policy-method.md) +- [file-sink-default-policy.md](./file-sink-default-policy.md) +- [file-sink-policy-matches-default.md](./file-sink-policy-matches-default.md) +- [file-sink-state-method.md](./file-sink-state-method.md) - [file-sink-type.md](./file-sink-type.md) - [native-files-supported.md](./native-files-supported.md) - [file-rotation.md](./file-rotation.md)