cbor
A high-performance, standard-compliant CBOR (RFC 8949) serialization library for MoonBit.
cbor
serialization
binary
rfc8949
codec
moon add 2515050242/cbor@0.1.2
Download zipAuthor
Version
0.1.2
License
Apache-2.0
Last updated
5 hours ago
Downloads
15
README#MoonBit CBOR (RFC 8949)
A CBOR (Concise Binary Object Representation, RFC 8949) serialization and deserialization library written in pure MoonBit.
This project was built for the CCF x MoonBit Open Source Competition (2026).
#Core Features
- RFC 8949 data model coverage for signed/unsigned integers, bytes, text, arrays, maps, tags, simple values, and floating-point decoding.
- CborDecode conversions for CborValue, Bool, Int64, UInt64, String, Bytes, and Double via decode_as.
- Full-width unsigned values are preserved as CborValue::Unsigned(UInt64) instead of being narrowed through Int64.
- Floating-point decoding across half, single, and double precision inputs.
- Indefinite-length decoding for byte strings, text strings, arrays, and maps.
- Deterministic map encoding with canonical key ordering.
- Decoder validation for integer bounds, trailing bytes, malformed simple values, strict UTF-8, and non-canonical integer and length encodings.
- Human-readable diagnostic notation output for debugging and examples.
- Versioned application message envelopes for requests, responses, events, and commands.
- Batch message encoding with producer/sequence metadata for queue and log transports.
- Nested path queries, immutable document patches, object projection, and field merging.
- Length-delimited streaming frames with partial-chunk decoding and bounded admission control.
- Composable application validation reports, lifecycle message storage, retry/dead-letter state, document metrics, and recursive sensitive-field redaction.
- Bounded application ingress policies that aggregate byte/node/depth limits across documents, messages, batches, and framed streams with indexed rejection reports.
#Installation
The project is verified with the MoonBit 0.10.x toolchain. CI installs the
current official toolchain on every supported runner; the local acceptance
environment currently uses moonc v0.10.7.
Add the package with the current MoonBit workflow:
moon add 2515050242/cborOr add it manually to moon.pkg:
import = [
"2515050242/cbor",
]#Usage Example
import "2515050242/cbor"
fn main {
let value = cbor.Map([
(cbor.Text("hello"), cbor.Integer(42L)),
(cbor.Text("world"), cbor.Array([cbor.Integer(1L), cbor.Integer(2L)])),
])
let bytes = cbor.encode(value)
println("Encoded \{bytes.length()} bytes.")
let decoded = cbor.decode(bytes) catch {
err => fail("Failed to decode: \{err}")
}
println("Decoded Diagnostic:")
println(cbor.diagnostic(decoded))
let count : Int64 = cbor.decode_as(b"\x18\x2a") catch {
err => fail("Failed to decode Int64: \{err}")
}
println("Decoded integer: \{count}")
}#CLI Example
The repository includes a runnable CLI in cmd/main:
moon run ./cmd/main
moon run ./cmd/main -- decode-hex a26161016162820203
moon run ./cmd/main -- roundtrip-hex 5f42010243030405ff
moon run ./cmd/main -- benchmark 20000
moon run ./cmd/main -- application-demoThe benchmark command reports four reproducible workloads: a small map, UTF-8
text containing a non-BMP scalar, a 256-byte binary payload, and a nested
array/map value. Each line includes the iteration count, encoded payload size,
and elapsed time.
The application demo exercises a versioned request/response batch, a framed
transport buffer, nested field queries, validation reports, recursive
redaction, and bounded-ingress accounting in one reproducible command.
#Performance Notes
- The encoder is buffer-backed and streaming-oriented for integers, byte strings, arrays, and maps.
- The current implementation is not globally zero-allocation: UTF-8 text encoding and canonical map-key sorting still use temporary buffers.
- The repository documentation has been aligned to this implementation boundary so reviewer expectations match real behavior.
#Validation
Local acceptance loop:
moon fmt --check
moon info
moon check --target wasm-gc --deny-warn
moon test --target wasm-gc --deny-warnCI additionally runs moon check --target all --deny-warn and
moon test --target all --deny-warn on Linux, macOS, and Windows, and checks
that formatting and generated interface steps leave a clean checkout.
Windows PowerShell helper:
powershell -ExecutionPolicy Bypass -File .\scripts\verify_acceptance.ps1Repository self-check report:
python ./scripts/check_repo_compliance.pyThe self-check reports both physical MoonBit source lines and effective
production source lines (non-empty, non-comment .mbt lines excluding tests).
The local production-source gate is 3300 lines so that the project scope is
backed by reusable implementation rather than documentation or generated files.
#Competition Notes
- The repository is public and keeps README, license, CI, tests, and MoonBit-first source visible for OSC2026 review.
- CI runs formatting, moon info, warning-free checks/tests for all backends, and CLI smoke tests on Linux, macOS, and Windows.
- The test suite includes RFC 8949 Appendix A vectors plus malformed-input regressions for reviewer verification.
- The application suite includes 52 deterministic tests covering policy limits, batch ingress, frame recovery, lifecycle transitions, redaction, and aggregate budget accounting.
- Source attribution and acceptance notes are kept in docs/source-attribution.md and docs/acceptance-checklist.md.
#License
This project is licensed under Apache-2.0. See LICENSE for details.
#CborDecode
Trait for types that can be deserialized from CBOR.
impl CborDecode for Bool
impl CborDecode for Int64impl CborDecode for UInt64impl CborDecode for Doubleimpl CborDecode for Stringimpl CborDecode for Bytes#CborEncode
Trait for types that can be serialized to CBOR.
impl CborEncode for Boolimpl CborEncode for Intimpl CborEncode for Int64impl CborEncode for UInt64impl CborEncode for Doubleimpl CborEncode for String#CborError
#AppIngestResult
pub(all) struct AppIngestResult {
accepted : Bool
kind : AppIngressKind
value : CborValue?
values : Array[CborValue]
stats : CborDocumentStats
report : AppPolicyReport
} derive(Debug)Result returned by the application ingress helpers.
#AppIngressKind
Identifies the ingress representation that was accepted.
#AppMessage
pub(all) struct AppMessage {
version : Int
kind : AppMessageKind
id : String
correlation_id : String?
headers : Array[(String, String)]
payload : CborValue
} derive(Eq, Debug)A versioned message envelope suitable for RPC, events, and queue records.
#AppMessage::new
fn AppMessage::new(version~ : Int, kind~ : AppMessageKind, id~ : String, payload~ : CborValue) -> AppMessageCreate a message with no correlation ID or headers.
#AppMessageBatch
pub(all) struct AppMessageBatch {
producer : String
sequence : UInt64
messages : Array[AppMessage]
} derive(Eq, Debug)An ordered group of application messages for queue and log transports.
#AppMessageKind
Application-level message kinds for services built on top of CBOR.
#AppMessageStore
pub(all) struct AppMessageStore {
records : Array[AppStoreRecord]
dead_letters : Array[AppMessage]
capacity : Int
max_retries : Int
} derive(Debug)A bounded in-memory message store for demos, tests, and embedded workers.
#AppPolicy
Resource limits applied at an application ingress boundary.
#AppPolicyIssue
One policy violation suitable for logs or an API response.
#AppPolicyReport
A policy report retains every independent limit violation.
#AppStoreRecord
pub(all) struct AppStoreRecord {
message : AppMessage
state : AppStoreState
retries : Int
} derive(Eq, Debug)An immutable record containing message lifecycle data.
#AppStoreState
Lifecycle state for an application message held by the local store.
#AppStoreStats
Metrics for observing a store without exposing its internal arrays.
#CborDocumentStats
Structural metrics for logging, admission control, and telemetry.
#CborFrameDecoder
pub(all) struct CborFrameDecoder {
pending : Bytes
max_frame_size : Int
frames_seen : Int
bytes_seen : Int
} derive(Debug)Decoder state for a bounded length-delimited CBOR stream.
#CborFrameDecoder::new
Create a decoder that rejects frames larger than the configured limit.
#CborFrameStats
Counters returned by stream consumers and useful for telemetry.
#CborPatch
pub(all) enum CborPatch {
Set(Array[CborPathSegment], CborValue)
Remove(Array[CborPathSegment])
Merge(Array[CborPathSegment], CborValue)
} derive(Eq, Debug)A small immutable patch language for configuration and event documents.
#CborPathSegment
A location inside a CBOR document.
#CborValue
#ValidationIssue
One machine-readable issue found during validation.
#ValidationReport
A complete validation result; all independent issues are retained.
#ValidationRule
pub(all) enum ValidationRule {
Required(String)
RequiredText(String)
RequiredBool(String)
RequiredInteger(String)
IntegerRange(String, Int64, Int64)
TextLength(String, Int, Int)
ArrayLength(String, Int, Int)
ObjectFields(String, Array[ValidationRule])
ArrayItems(String, Array[ValidationRule])
OneOfText(String, Array[String])
} derive(Eq, Debug)Validation rules for common CBOR application payloads.
#app_batch_append
Return a copy with one message appended.
#app_batch_correlated_response_count
Return the number of request/response pairs represented in a batch.
#app_batch_encoded_size
Return the encoded size of a batch for transport admission control.
#app_batch_filter_kind
Select messages of one kind while preserving their order.
#app_batch_find
Find a message in a batch by its stable ID.
#app_batch_first
Return the first message in a batch, if any.
#app_batch_fits_policy
Return whether a batch can be framed under the policy.
#app_batch_from_cbor
Decode and validate a batch from a CBOR value.
#app_batch_has_unique_ids
Return true when all message IDs in the batch are unique.
#app_batch_ids
Return all message IDs for audit and deduplication.
#app_batch_is_empty
Return whether a batch contains no messages.
#app_batch_kind_count
Count messages of one lifecycle kind.
#app_batch_kind_summary
Return a deterministic kind histogram for operational dashboards.
#app_batch_last
Return the last message in a batch, if any.
#app_batch_new
fn app_batch_new(producer~ : String, sequence~ : UInt64, messages~ : Array[AppMessage]) -> AppMessageBatchConstruct a batch with producer and monotonically increasing sequence metadata.
#app_batch_next_sequence
Return the next sequence number for a producer.
#app_batch_payload_bytes
Return the total encoded payload bytes without envelope overhead.
#app_batch_payload_nodes
Count all CBOR nodes carried by batch payloads.
#app_batch_payloads_within_budget
Return true when every payload remains under a node budget.
#app_batch_responses_for
Return all response messages correlated to a request ID.
#app_batch_summary
Return a compact audit summary for a batch.
#app_batch_to_cbor
Encode a batch using an explicit versioned map representation.
#app_event
Build an event message with a topic header.
#app_ingest_add_business_issue
fn app_ingest_add_business_issue(result : AppIngestResult, path : String, code : String, message : String) -> AppIngestResultReject a report with a caller-provided business rule.
#app_ingest_is_valid
A single status predicate for adapters that should reject invalid ingress.
#app_ingest_issue_codes
Return all policy issue codes in stable order.
#app_ingest_primary_issue
Return the first issue code for a stable caller-facing rejection reason.
#app_ingest_summary
Return a compact summary of an ingress result for metrics.
#app_ingest_values_encoded_bytes
Return the exact re-encoded size of values retained by an ingress result.
#app_ingest_values_nodes
Return the aggregate node count recorded in an ingress result.
#app_message_from_cbor
Decode and validate an application message envelope.
#app_message_header
Find the first header with a given name.
#app_message_summary
Return a compact application-message summary for logs.
#app_message_to_cbor
Convert an application message into its stable CBOR representation.
#app_message_with_correlation
Return a copy with a correlation ID used to link a response to a request.
#app_message_with_header
Return a copy with one application header appended.
#app_message_with_payload
Copy a message while replacing its payload.
#app_messages_are_correlated
Return true when two messages can be paired as request and response.
#app_policy_budget_summary
Produce a compact budget snapshot for logs and telemetry.
#app_policy_collection_fits_transport
Check the encoded collection against both storage and transport budgets.
#app_policy_combine
Combine policy reports from multiple documents.
#app_policy_default
A practical default policy for service and edge workloads.
#app_policy_is_sane
Validate that a policy is internally coherent before accepting config.
#app_policy_is_stricter_or_equal
Check whether a policy has no looser resource limit than another policy.
#app_policy_issue_to_string
Render one policy issue in a stable log-friendly form.
#app_policy_many_within_budget
Check aggregate byte and node budgets without losing per-document errors.
#app_policy_prefix
Prefix issues when a payload is embedded in a larger protocol object.
#app_policy_report_code_count
Count occurrences of a policy code for dashboards and alert grouping.
#app_policy_report_has_code
Test whether a report contains a particular admission failure class.
#app_policy_report_to_string
Render all policy issues in insertion order.
#app_policy_strict
A smaller policy useful for untrusted public endpoints.
#app_policy_summary
Return a policy line for startup logs and configuration audits.
#app_policy_transport_limit
Return the configured maximum transport size.
#app_policy_with_limits
Build a policy with explicit limits for deterministic tests and deployments.
#app_request
Build a request message with an operation header.
#app_response
Build a response correlated to a request.
#app_store_ack
Mark a message as successfully processed.
#app_store_append
Insert a message; the Boolean is false for duplicate IDs or a full store.
#app_store_append_batch
fn app_store_append_batch(store : AppMessageStore, messages : Array[AppMessage]) -> (AppMessageStore, Int)Insert messages in order and return the accepted count.
#app_store_available_capacity
Return the number of available capacity slots.
#app_store_contains
Return true when an ID is already known to the store.
#app_store_dead_letters
Return the stored dead-letter messages.
#app_store_drain_dead_letters
Drain dead letters and return the cleared store plus the drained messages.
#app_store_get
Find a message by ID, including messages awaiting acknowledgement.
#app_store_ids
Return all message IDs in insertion order.
#app_store_is_acknowledged
Return whether a message has reached a terminal success state.
#app_store_mark_delivered
Mark a message as delivered to a worker.
#app_store_new
Create an empty bounded store.
#app_store_next_pending
Return the next pending message in insertion order.
#app_store_pending
Return all records that are ready for delivery.
#app_store_record
Return a record with lifecycle metadata.
#app_store_record_retry
Record a retry; messages over the retry budget move to the dead-letter list.
#app_store_remove_acknowledged
Remove a record after acknowledgement and preserve all other records.
#app_store_resize
Change the capacity only when it can hold the current records.
#app_store_retry_count
Return the retry count for a message, or zero when it is unknown.
#app_store_set_retry_budget
Return a copy with a new retry budget for future failures.
#app_store_stats
Calculate lifecycle counters for dashboards and tests.
#app_store_summary
Create a compact audit string for operational logs.
#append_cbor_frame
Encode frames incrementally into a caller-owned buffer.
#append_frame_with_stats
fn append_frame_with_stats(buffer : Buffer, value : CborValue, max_frame_size : Int, stats : CborFrameStats) -> CborFrameStats raise CborErrorAdd a frame to a buffer and return the resulting statistics.
#cbor_apply_patch_with_label
Apply exactly one patch and return its operation label with the result.
#cbor_apply_patches
Apply patches in order, returning a new document.
#cbor_apply_patches_bounded
Apply a batch and reject documents that exceed a node budget.
#cbor_clear_object
Return a patch list that removes every top-level key in an object.
#cbor_diff_objects
Construct patches for changed or newly added top-level object fields.
#cbor_document_binary_count
Return the number of byte-string payloads in a document.
#cbor_document_contains_text
Search both object keys and values for an exact text value.
#cbor_document_encoded_size
Return the encoded byte size of a document.
#cbor_document_field_count
Return the number of map entries, including nested objects.
#cbor_document_largest_binary
Return the largest byte-string payload length in a document.
#cbor_document_leaf_paths
Collect leaf paths for audit logs without exposing leaf contents.
#cbor_document_numeric_count
Count numeric leaves, including integer and floating-point values.
#cbor_document_stats
Compute node, container, depth, payload, and encoded-size metrics.
#cbor_document_summary
Create a stable summary for an observability event.
#cbor_document_tag_count
Count tagged values to support application-specific extension audits.
#cbor_document_text_count
Return the number of text values in a document.
#cbor_document_within_budget
fn cbor_document_within_budget(value : CborValue, max_nodes : Int, max_encoded_bytes : Int, max_depth : Int) -> BoolReturn true when the document fits both structural budgets.
#cbor_frame_decoder_feed
fn cbor_frame_decoder_feed(decoder : CborFrameDecoder, chunk : Bytes) -> (CborFrameDecoder, Array[CborValue]) raise CborErrorFeed a chunk and return all complete values plus the updated decoder.
#cbor_frame_decoder_finish
Signal end-of-input and reject an incomplete frame header or payload.
#cbor_frame_decoder_frames
Return the number of complete frames emitted by a decoder.
#cbor_frame_decoder_limit
Return the maximum payload accepted by a decoder.
#cbor_frame_decoder_pending_bytes
Return the number of bytes currently buffered but not yet decoded.
#cbor_frame_decoder_stats
Decode frames while retaining a stable stream statistics snapshot.
#cbor_frame_wire_size
Return the wire size of a frame for admission control.
#cbor_ingest_batch
Decode and policy-check one ordered application batch.
#cbor_ingest_document
Decode and policy-check a raw CBOR document at an application boundary.
#cbor_ingest_frames
Decode and policy-check every value in a length-delimited frame stream.
#cbor_ingest_message
Decode and policy-check one versioned application message.
#cbor_message_policy_accepts
Validate a message payload together with its application headers.
#cbor_object_get
Read a top-level object field without constructing a path.
#cbor_object_has
Return whether an object contains a text key.
#cbor_object_keys
Return all text keys in insertion order.
#cbor_object_merge
Merge two objects; fields from overlay replace fields from base.
#cbor_object_project
Project an object onto a list of keys, preserving the requested order.
#cbor_object_remove
Return a copy of an object with a field removed.
#cbor_object_set
Return a copy of an object with a text field inserted or replaced.
#cbor_partition_frames
Split a batch into transport-sized frame batches without losing order.
#cbor_patch_audit_line
Return a deterministic audit line for a patch batch.
#cbor_patch_is_noop
Return true when applying a patch does not change the encoded document.
#cbor_patch_merge
Create an object merge patch.
#cbor_patch_operation
Return a short operation name for metrics and audit logs.
#cbor_patch_path
Return the path targeted by a patch.
#cbor_patch_remove
Create a removal patch.
#cbor_patch_set
Create a replacement patch.
#cbor_path_segment_to_string
Return a readable path fragment for diagnostics and logs.
#cbor_path_to_string
Format a path without introducing a dependency on a JSON pointer package.
#cbor_policy_accepts
Return true when a raw document passes the configured policy.
#cbor_policy_check
Check structural resource limits for one CBOR document.
#cbor_policy_check_many
Check every document in an ordered collection and retain indexed paths.
#cbor_policy_many_encoded_bytes
Measure the exact encoded footprint of a collection.
#cbor_policy_many_nodes
Count nodes across a collection for admission control and metrics.
#cbor_query_at
Resolve a path one segment at a time and return the selected value.
#cbor_query_bool
Read a boolean field at a nested path.
#cbor_query_bytes
Read a byte string field at a nested path.
#cbor_query_double
Read a floating-point field, accepting integer CBOR numbers as well.
#cbor_query_int64
Read an integer field at a nested path without narrowing unsafely.
#cbor_query_optional
fn cbor_query_optional(value : CborValue, path : Array[CborPathSegment]) -> CborValue? raise CborErrorResolve a path, returning None only when a field is absent.
#cbor_query_preview
Convert a value to a compact log-safe diagnostic with a length limit.
#cbor_query_text
Read a text field at a nested path.
#cbor_query_uint64
Read a full-width unsigned integer field.
#cbor_redact_fields
Recursively replace values whose object key is in a sensitive-field list.
#cbor_redacted_preview
Return a redacted preview bounded by a character budget.
#cbor_set_path
Replace a nested path while preserving all untouched values.
#cbor_value_depth
Return the maximum nesting depth of a document.
#cbor_value_fits_frame
Return whether a value can be emitted under a frame limit.
#cbor_value_node_count
Count descendants in a document for lightweight telemetry.
#count_cbor_frames
Count complete frames in a wire buffer without decoding payloads.
#decode
Decode a CBOR value from a byte array.
#decode_app_batch
Decode a complete application message batch.
#decode_app_message
Decode a complete application message.
#decode_as
Decode a complete CBOR payload into a target type via CborDecode.
#decode_cbor_frames
Decode a complete transport buffer.
#decode_from_offset
Decode a CBOR value from a byte array starting at the given offset.
#diagnostic
Convert a CborValue to CBOR Diagnostic Notation (RFC 8949 Section 8)
#encode_app_batch
Encode a complete application message batch.
#encode_app_message
Encode a validated application message.
#encode_cbor_frame
Encode one CBOR value as a length-delimited frame.
#encode_cbor_frames
Encode a batch of values into a single transport buffer.
#encode_to_buffer
Encode a CBOR value into a mutable Buffer.
#inspect_cbor_frames
Calculate transport statistics from a complete frame stream.
#validate_app_batch
Validate batch metadata and every contained envelope.
#validate_app_batch_for_transport
fn validate_app_batch_for_transport(batch : AppMessageBatch, max_encoded_bytes : Int) -> Unit raise CborErrorValidate an upper bound and ID uniqueness in one operation.
#validate_app_message
Validate message invariants without encoding the payload.
#validate_message_payload
fn validate_message_payload(message : AppMessage, rules : Array[ValidationRule]) -> ValidationReportValidate a message payload and prefix its errors with the message ID.
#validate_object_payload
Validate an object and retain every independent field issue.
#validation_array_length
Construct an inclusive array length rule.
#validation_business_error
Return a report containing one explicit business-rule error.
#validation_combine
Compose two reports without losing issue order.
#validation_error_count
Return the number of errors in a validation report.
#validation_int_range
Construct an inclusive integer range rule.
#validation_issue_to_string
Return a stable single-line representation for log aggregation.
#validation_items
Construct a rule applied to every item in an array.
#validation_object
Construct a nested object rule.
#validation_one_of
Construct a finite text enumeration rule.
#validation_prefix
Add a path prefix to every issue in a report.
#validation_report_to_string
Render all issues in deterministic order.
#validation_required
Construct a required-field rule.
#validation_required_bool
Construct a required boolean rule.
#validation_required_integer
Construct a required integer rule.
#validation_required_text
Construct a required non-empty text rule.
#validation_succeeds
Return true when a value passes a set of object rules.
#validation_text_length
Construct an inclusive UTF-16 string length rule.
#validation_unknown_fields
Reject unknown text fields when an application has a closed schema.
A high-performance, standard-compliant CBOR (RFC 8949) serialization library for MoonBit.
cborserializationbinaryrfc8949codec
0.1.2
Apache-2.0
Updated 5 hours ago
15 downloads