🥮 mooncakes.io

    oas2moon_runtime

    Runtime request, response, encoding, auth, and transport boundary for oas2moon clients.

    openapi
    http
    client
    runtime
    Download zip
    Version
    0.1.0
    License
    MIT
    Repository
    Last updated
    4 hours ago
    Downloads
    3

    Dependencies

    #oas2moon runtime

    Runtime support for SDKs generated by oas2moon.

    This package defines the transport-neutral request/response boundary, structured SDK errors, encoding and authentication helpers, and the native HTTP adapter.

    Repository: https://github.com/Atman-Angle/oas2moon

    Transport

    source
    pub trait Transport {
      fn send(Self, Request) -> Response raise SdkError
    }

    The only boundary generated operations use to perform I/O.

    SdkError

    source
    pub(all) suberror SdkError {
      Transport(String, String)
      Http(String, Int, Map[String, String], String)
      Decode(String, String)
      Encode(String, String)
      Configuration(String, String)
      Unsupported(String, String)
    } derive(
    Debug    )

    Structured SDK error type.

    Every variant carries an operation_id so that diagnosis context is never discarded. The Http variant additionally carries status, headers, and raw body for programmatic inspection by callers.

    Variant map:
    • Transport — DNS, connection, timeout, TLS, or adapter failure;
    • Http — non-2xx response (status, headers, raw body);
    • Decode — response did not match the declared representation;
    • Encode — request serialization failed;
    • Configuration — invalid base URL or auth configuration;
    • Unsupported — rejected OpenAPI semantic surfaced at runtime boundary.

    SdkError::body

    source
    fn SdkError::body(self : SdkError) -> String

    Raw response body when this is an Http error, otherwise "".

    SdkError::configuration

    source
    fn SdkError::configuration(operation_id : String, message : String) -> SdkError

    Convenience constructor for a configuration error.

    SdkError::decode

    source
    fn SdkError::decode(operation_id : String, message : String) -> SdkError

    Convenience constructor for a decode error.

    SdkError::encode

    source
    fn SdkError::encode(operation_id : String, message : String) -> SdkError

    Convenience constructor for an encode error.

    SdkError::headers

    source
    fn SdkError::headers(self : SdkError) -> Map[String, String]

    Response headers when this is an Http error, otherwise an empty map.

    SdkError::http

    source
    fn SdkError::http(operation_id : String, status : Int, headers : Map[String, String], body : String) -> SdkError

    Convenience constructor for an HTTP error.

    SdkError::message

    source
    fn SdkError::message(self : SdkError) -> String

    Human-readable detail message for any variant. For Http this is a status summary; for other variants it is the original message string.

    SdkError::operation_id

    source
    fn SdkError::operation_id(self : SdkError) -> String

    The operation id carried by this error, or "" when unknown.

    SdkError::status

    source
    fn SdkError::status(self : SdkError) -> Int

    HTTP status code when this is an Http error, otherwise 0.

    SdkError::to_string

    source
    fn SdkError::to_string(self : SdkError) -> String

    Stable, human-readable display of an SDK error.

    The output is deterministic for equal inputs and never contains absolute paths, timestamps, or random identifiers.

    SdkError::transport

    source
    fn SdkError::transport(operation_id : String, message : String) -> SdkError

    Convenience constructor for a transport error.

    SdkError::unsupported

    source
    fn SdkError::unsupported(operation_id : String, message : String) -> SdkError

    Convenience constructor for an unsupported-feature error.

    CaptureTransport

    source
    pub struct CaptureTransport {
      response : Response
      last_request : Request?
    } derive(
    Debug    )

    In-memory transport useful for deterministic unit tests.

    CaptureTransport::last_request

    source
    fn CaptureTransport::last_request(self : CaptureTransport) -> Request?

    The last request that was sent through this transport, if any.

    CaptureTransport::new

    source

    CaptureTransport::send

    source
    fn CaptureTransport::send(self : CaptureTransport, request : Request) -> Response

    Config

    source
    pub struct Config {
      origin : String
      base_path : String
      bearer_token : String?
      basic_username : String?
      basic_password : String?
      api_key_name : String?
      api_key_value : String?
      api_key_location : String?
    } derive(
    Debug    )

    Static configuration for one generated SDK client.

    Config::api_key_location

    source
    fn Config::api_key_location(self : Config) -> String?

    The configured API key location ("header" or "query"), when one was supplied.

    Config::api_key_name

    source
    fn Config::api_key_name(self : Config) -> String?

    The configured API key name (header name or query parameter name), when one was supplied.

    Config::api_key_value

    source
    fn Config::api_key_value(self : Config) -> String?

    The configured API key value, when one was supplied.

    Config::base_path

    source
    fn Config::base_path(self : Config) -> String

    The path prefix that every request target of this client starts with.

    Config::basic_password

    source
    fn Config::basic_password(self : Config) -> String?

    The configured basic auth password, when one was supplied.

    Config::basic_username

    source
    fn Config::basic_username(self : Config) -> String?

    The configured basic auth username, when one was supplied.

    Config::bearer_token

    source
    fn Config::bearer_token(self : Config) -> String?

    The configured bearer token, when one was supplied.

    Config::new

    source
    fn Config::new(base_url : String, bearer_token? : String, basic_username? : String, basic_password? : String, api_key_name? : String, api_key_value? : String, api_key_location? : String) -> Config

    Create a runtime configuration.

    base_url is split into an origin (scheme://authority) and a base path. The split is required because the transport library connects to an origin, while request targets must stay relative. A trailing slash is dropped so that path joining stays deterministic.

    Config::origin

    source
    fn Config::origin(self : Config) -> String

    The scheme://authority part of the configured base URL.

    Request

    source
    pub struct Request {
      http_method : String
      path : String
      query : Array[(String, String)]
      headers : Map[String, String]
      body : String?
    } derive(
    Debug    )

    A transport-neutral request.

    Request::body

    source
    fn Request::body(self : Request) -> String?

    Request::headers

    source
    fn Request::headers(self : Request) -> Map[String, String]

    Request::http_method

    source
    fn Request::http_method(self : Request) -> String

    Request::new

    source
    fn Request::new(http_method : String, path : String, query? : Array[(String, String)], headers? : Map[String, String], body? : String) -> Request

    Request::path

    source
    fn Request::path(self : Request) -> String

    Request::query

    source
    fn Request::query(self : Request) -> Array[(String, String)]

    Response

    source
    pub struct Response {
      status : Int
      headers : Map[String, String]
      body : String
    } derive(
    Debug    )

    A transport-neutral response.

    Response::body

    source
    fn Response::body(self : Response) -> String

    Response::headers

    source
    fn Response::headers(self : Response) -> Map[String, String]

    Response::new

    source
    fn Response::new(status : Int, headers? : Map[String, String], body? : String) -> Response

    Response::status

    source
    fn Response::status(self : Response) -> Int

    auth_headers

    source
    fn auth_headers(cfg : Config, requirements : Array[String], operation_id? : String) -> Map[String, String] raise SdkError

    Build auth headers for the given security requirements. Does not perform I/O; pure map construction.

    Supports the V1 schemes bearer, basic, and apiKey. An apiKey carried in the query string contributes no header; auth_query supplies it instead.

    operation_id is included in any raised Configuration error: a missing or unusable credential is a configuration fault, not a transport fault.

    auth_query

    source
    fn auth_query(cfg : Config, requirements : Array[String], operation_id? : String) -> Array[(String, String)] raise SdkError

    Build the query parameters an in-query API key contributes.

    Returns an empty array for every other scheme so a caller can append the result unconditionally.

    build_query_string

    source
    fn build_query_string(params : Array[(String, String)]) -> String

    Build a query string from encoded key-value pairs. Returns the query string without the leading ?.

    decode_json

    source
    fn[T : 
    FromJson    ] decode_json(response : Response, operation_id? : String) -> T raise SdkError

    Decode a JSON response body into the target type.

    A declared JSON operation that receives an unexpected response media type fails explicitly instead of attempting a known-wrong decode. A missing Content-Type is tolerated for transport-neutral capture fixtures.

    operation_id is included in any raised error so that callers can programmatically identify which operation failed.

    encode_header_array

    source
    fn encode_header_array(values : Array[String]) -> String

    Encode header array values (simple style). Values are comma-separated.

    encode_header_value

    source
    fn encode_header_value(value : String) -> String

    Encode a header value (simple style). Simple style passes through as-is.

    encode_json

    source
    fn[T : ToJson] encode_json(value : T) -> String

    encode_path_array

    source
    fn encode_path_array(values : Array[String]) -> String

    Encode multiple values for path insertion (simple style, array).

    encode_path_value

    source
    fn encode_path_value(value : String) -> String

    Encode a single value for path insertion (simple style).

    encode_query_array_explode

    source
    fn encode_query_array_explode(name : String, values : Array[String]) -> Array[(String, String)]

    Encode a query array parameter with explode=true (form style).

    encode_query_array_joined

    source
    fn encode_query_array_joined(name : String, values : Array[String]) -> (String, String)

    Encode a query array parameter with explode=false (form style).

    encode_query_pair

    source
    fn encode_query_pair(name : String, value : String) -> (String, String)

    Encode a query parameter key-value pair (form style). Both key and value are percent-encoded.

    expect_status

    source
    fn expect_status(response : Response, expected : Array[Int], operation_id? : String) -> Unit raise SdkError

    Assert that the response status is one of the expected values.

    On failure, raises Http carrying the full status, headers, and raw body so callers can programmatically inspect the error response.

    interpolate_path

    source
    fn interpolate_path(path : String, params : Map[String, String]) -> String

    Interpolate path parameters into a path template. Replaces {paramName} placeholders with encoded values from the map.

    percent_encode

    source
    fn percent_encode(value : String) -> String

    Percent-encode a string value according to RFC 3986. Reserved characters and non-ASCII bytes are encoded as %XX. Unreserved characters (A-Z, a-z, 0-9, -, ., _, ~) pass through.

    render_query

    source
    fn render_query(params : Array[(String, String)]) -> String

    Render query parameters into a request target suffix.

    Names and values are percent-encoded with the same RFC 3986 rules the path encoder uses, so repeated keys keep their declared order.

    Returns "" when there is nothing to encode and "?k=v&k2=v2" otherwise.

    send

    source
    fn[T : Transport] send(transport : T, request : Request) -> Response raise SdkError

    transmit

    source
    async fn transmit(config : Config, request : Request, operation_id? : String) -> Response raise SdkError

    Perform one request against the origin of config.

    The body is already JSON-encoded by the generated operation, so this function only computes Content-Length and writes the bytes. Responses with status 204/304 never carry a body, matching the SDK response policy.

    Any I/O failure becomes Transport; the HTTP status itself is not judged here, because expect_status owns that decision.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io