From 041385712b6cebbc3c133ba00a29b78d4cfc36dc Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sat, 13 Jun 2026 21:27:21 +0800 Subject: [PATCH] :memo: document file capability and rotation json helpers --- docs/api/file-rotation-config-to-json.md | 75 ++++++++++++++++++++++++ docs/api/index.md | 2 + docs/api/native-files-supported.md | 74 +++++++++++++++++++++++ 3 files changed, 151 insertions(+) create mode 100644 docs/api/file-rotation-config-to-json.md create mode 100644 docs/api/native-files-supported.md diff --git a/docs/api/file-rotation-config-to-json.md b/docs/api/file-rotation-config-to-json.md new file mode 100644 index 0000000..ebbc370 --- /dev/null +++ b/docs/api/file-rotation-config-to-json.md @@ -0,0 +1,75 @@ +--- +name: file-rotation-config-to-json +group: api +category: config +update-time: 20260613 +description: Convert FileRotation into a JSON value for config export and nested sink serialization. +key-word: + - file + - rotation + - json + - public +--- + +## File-rotation-config-to-json + +Convert `FileRotation` into a `JsonValue`. This helper is the structured export path for file rotation policy when callers need machine-readable config data instead of a runtime policy object. + +### Interface + +```moonbit +pub fn file_rotation_config_to_json(config : FileRotation) -> @json_parser.JsonValue {} +``` + +#### input + +- `config : FileRotation` - File rotation config value to export. + +#### output + +- `JsonValue` - Structured JSON representation of the rotation policy. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- The output includes `max_bytes` and `max_backups`. +- Both numeric fields are exported as JSON numbers. +- This helper serializes the rotation config object itself rather than sink availability, failure counters, or file state. +- The same JSON shape is reused by `sink_config_to_json(...)`, file sink state export helpers, and larger logger config serialization paths. + +### How to Use + +Here are some specific examples provided. + +#### When Need Structured Rotation Policy Export + +When file rotation settings should be embedded into a larger config payload: +```moonbit +let value = file_rotation_config_to_json(file_rotation(1024 * 1024, max_backups=3)) +``` + +In this example, the rotation policy becomes a reusable JSON value instead of final text. + +#### When Need Manual Sink Config Assembly + +When code is exporting only the rotation portion of a file-related config flow: +```moonbit +let rotation = file_rotation(4096, max_backups=2) +let rotation_json = file_rotation_config_to_json(rotation) +``` + +In this example, callers can carry the nested rotation shape without exporting a full sink config. + +### Error Case + +e.g.: +- If callers need a complete sink or logger config snapshot, this helper alone is too narrow and should be paired with `sink_config_to_json(...)` or `logger_config_to_json(...)`. + +- If callers need text output rather than a JSON value, they should stringify a larger containing config instead of manually formatting this value. + +### Notes + +1. Use this helper when downstream code expects `JsonValue` rather than a typed `FileRotation` value. + +2. Pair it with `file_rotation(...)` when building rotation policy in code before export. diff --git a/docs/api/index.md b/docs/api/index.md index ba032bf..f2d0bf2 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -112,6 +112,7 @@ BitLogger API navigation. - [filter-sink.md](./filter-sink.md) - [patch-sink.md](./patch-sink.md) - [file-sink.md](./file-sink.md) +- [native-files-supported.md](./native-files-supported.md) - [file-rotation.md](./file-rotation.md) - [file-rotation-type.md](./file-rotation-type.md) - [file-sink-policy-to-json.md](./file-sink-policy-to-json.md) @@ -152,6 +153,7 @@ BitLogger API navigation. - [config-error.md](./config-error.md) - [sink-kind.md](./sink-kind.md) +- [file-rotation-config-to-json.md](./file-rotation-config-to-json.md) - [queue-config-type.md](./queue-config-type.md) - [queue-config.md](./queue-config.md) - [queue-config-to-json.md](./queue-config-to-json.md) diff --git a/docs/api/native-files-supported.md b/docs/api/native-files-supported.md new file mode 100644 index 0000000..7a772e0 --- /dev/null +++ b/docs/api/native-files-supported.md @@ -0,0 +1,74 @@ +--- +name: native-files-supported +group: api +category: sink +update-time: 20260613 +description: Query whether the current backend provides real host file support for file sink operations. +key-word: + - native + - file + - support + - public +--- + +## Native-files-supported + +Query whether the current backend provides real file support for `file_sink(...)` and related file runtime operations. This helper is the public capability gate for code that needs to decide whether host file logging is actually available on the current target. + +### Interface + +```moonbit +pub fn native_files_supported() -> Bool {} +``` + +#### output + +- `Bool` - `true` when the active backend provides real file support, otherwise `false`. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This helper is target-sensitive runtime capability detection, not a compile-time type gate. +- The native backend currently returns `true`. +- The stub backend used for non-file-capable targets currently returns `false`. +- File APIs can remain part of the broader portable surface, but callers should use this check before depending on actual file creation, writes, flushes, or reopen behavior. + +### How to Use + +Here are some specific examples provided. + +#### When Need Safe Cross-target File Logging + +When code should enable file output only on targets that really support it: +```moonbit +if native_files_supported() { + let sink = file_sink("app.log") + Logger::new(sink).info("started") +} +``` + +In this example, file logging is activated only when the backend can actually provide it. + +#### When Need To Match Runtime Availability Checks + +When capability detection should align with file sink health state: +```moonbit +let sink = file_sink("app.log") +inspect(sink.is_available() == native_files_supported(), content="true") +``` + +In this example, the public support flag matches the observable file sink availability contract. + +### Error Case + +e.g.: +- If this helper returns `false`, callers should not treat file writes, flushes, or reopen operations as available runtime behavior. + +- If this helper returns `true`, individual file operations can still fail later because of path, permission, or filesystem state issues. + +### Notes + +1. Use this helper as the first portability guard around `file_sink(...)`, `file(...)`, and file-runtime control APIs. + +2. See [target-verification.md](./target-verification.md) when you need the current local verification boundary for target-sensitive behavior.