DocBuf (文档缓冲区)

概述

文档缓冲区（DocBuf）是一种用于结构化文档规范的接口描述语言（IDL）。

DocBuf 的灵感来自于创建一个更现代、更高效的 XSD 版本。XSD 提供了许多很好的功能，例如为每个元素提供验证要求，称为“限制”。然而，尽管其细粒度控制良好，但 XSD 实现的 XML 数据冗长，并且在出现语法错误或字段缺失时，序列化和反序列化可能会变得脆弱。

DocBuf 取 XSD 的优点，例如实现了自己的字段选项版本（field::options）和编译时验证，并将其实用性扩展到一种轻量级二进制格式，该格式可以高效地序列化和反序列化为原生编程语言的规范数据，例如 Rust。

类似于 Protocol Buffers 和 gRPC，DocBuf 引入了 process 关键字来定义具有 endpoints 的进程，这些端点指定远程过程调用（RPC）或 stream API。在 process:options 部分定义了对配置选项的内置支持。

示例 .docbuf 源文件

pragma docbuf v1;

// Module name of the documents.
module my_module;

// relative path to other document imports
import "another.docbuf";

#[document::options {
    // overwrite the document name in the generated code.
    name = "MyDocType";
    // Mark the document as the root document.
    // The root document is the entry point for the document buffer.
    // There can only be one root document per document buffer.
    root = true;
}]
document MyDocumentType {
    // comment field
    #[field::options {
        min_length = 0;
        max_length = 32;
        regex = "[a-zA-Z]";
        default = "my-text-field";
        // All fields are optional by default.
        // Set required to true to force the field to exist.
        required = true;
        // overwrite the field name in the generated code.
        name = "CustomFieldID";
    }]
    text_field: String,
    // no options or limitations
    no_options: String,
    #[field::options {
        min_value = 0;
        max_value = 100;
        // Default value will be zero unless specified otherwise.
        default = 10;
    }]
    32_bit_integer: i32,
    64_bit_integer: i64,
    32_bit_unsigned: u32,
    64_bit_unsigned: u64,
    32_bit_floating: f32,
    64_bit_floating: f64,
    binary_or_bytecode: [u8],
    #[field::options {
        min_length = 1;
        required = true;
    }]
    my_other_document: [MyOtherDocument],
    // List of like-typed items
    my_list: [String],
    // Enumerable types
    my_enum: MyOptionTypes,
}

#[enum::options {
    name = "MyOptions";
}]
enumerable MyOptionTypes {
    OptionOne,
    OptionTwo(i32),
    OptionThree(MyOtherDocument),
    #[field::options {
        min_length = 1;
        max_length = 32;
        regex = "[a-zA-Z]";
    }]
    OptionFour(String),
}

#[process::options {
    // use ipv6 address space
    ipv6 = true;
    host = "::1";
    port = 1337;
    name = "MessageProcessor";
    protocol = "quic";
    // Certificate options
    public_cert = "/path/to/public/certificate";
    private_cert = "/path/to/private/certificate";
    // Signing options
    keypair = "/path/to/keypair";
    // Asymmetric Cryptography Algorithms
    crypto = "ed25519";
    // Use the noise encryption protocol
    noise = true;
    //
    // ALTERNATIVELY, USE CONFIG FILE
    // Use a config file instead of options
    config = "/path/to/config";
}]
process Messenger {
    #[endpoint::options {
        required = true;
        // allowed request limit per minute
        request_rate_limit_per_minute = 10;
        // endpoint must include a signed message field
        signature_required = true;
        // convert endpoint into a stream
        stream = true;
    }]
    upload_document: MyDocumentType -> (),
    /// Upload multiple documents in the process
    /// Comments with three slashes will be made public in the generated source code
    upload_documents: [MyDocumentType] -> (),

}

版权

© 2024 Emergent Financial, LLC - 版权所有