🥮 mooncakes.io

    #gateway

    Transport-agnostic API execution layer for vcdb collections.

    #Features

    • Collection management (create, list, delete)
    • Point operations (upsert, get, delete)
    • Vector search with pagination
    • Persistence with pluggable storage backends
    • Raw-path execution for transport adapters and native entrypoints

    #Responsibility

    • Accept API-shaped requests as method + path + body
    • Execute vcdb collection commands
    • Return structured JSON responses

    It does not open sockets or serve HTTP directly. Runtime-specific transports belong in adapter packages such as http and js.

    #Usage

    let manager : CollectionManager[@storage.MemoryStorage] = CollectionManager::new()
    let response = execute_path_request(
      manager,
      "POST",
      "/collections/test",
      body,
    )

    GatewayError

    source
    pub(all) suberror GatewayError {
      NotFound(String)
      InvalidInput(String)
      DimensionMismatch(expected~ : Int, got~ : Int)
      CollectionExists(String)
      CollectionNotFound(String)
      StorageError(String)
    }

    Gateway errors

    ApiResponse

    source
    pub struct ApiResponse {
      status : String
      result : Json?
      error : String?
    }

    Generic API response wrapper
    impl Show for ApiResponse

    ApiResponse::err

    source
    fn ApiResponse::err(message : String) -> ApiResponse

    Create error response

    ApiResponse::ok

    source
    fn ApiResponse::ok(result : Json) -> ApiResponse

    Create success response

    ApiResponse::to_json

    source
    fn ApiResponse::to_json(self : ApiResponse) -> Json

    Convert API response to JSON

    Collection

    source
    pub struct Collection[S] {
      config : CollectionConfig
      db : 
    PersistentDB    [S, S]
    }

    Collection entry — wraps VectorDB with its config.

    CollectionConfig

    source
    pub struct CollectionConfig {
      name : String
      dim : Int
      metric : 
    Metric
      strategy : 
    Strategy
    }

    Collection configuration

    CollectionConfig::default

    source
    fn CollectionConfig::default(name : String, dim : Int) -> CollectionConfig

    Create default collection config

    CollectionConfig::from_json

    source
    fn CollectionConfig::from_json(json : Json) -> Result[CollectionConfig, String]

    Parse collection config from JSON Supports both formats:
    • {"dim": 4, "metric": "Cosine"}
    • {"vectors": {"size": 4, "distance": "Cosine"}} (Qdrant-compatible)

    CollectionConfig::to_json

    source
    fn CollectionConfig::to_json(self : CollectionConfig) -> Json

    Convert collection config to JSON

    CollectionInfo

    source
    pub struct CollectionInfo {
      name : String
      vectors_count : Int
      dim : Int
      metric : String
      strategy : String
    }

    Collection info response

    CollectionInfo::to_json

    source
    fn CollectionInfo::to_json(self : CollectionInfo) -> Json

    Convert collection info to JSON

    CollectionManager

    source
    pub struct CollectionManager[S] {
      collections : Map[String, Collection[S]]
      storage : S?
      base_path : String
      checkpoint_threshold : Int
    }

    Collection manager with optional storage

    CollectionManager::checkpoint

    source
    async fn[S : 
    AsyncStorage    ] CollectionManager::checkpoint(self : CollectionManager[S], name : String) -> Unit

    Checkpoint: write snapshot and truncate WAL

    CollectionManager::count

    source
    fn[S] CollectionManager::count(self : CollectionManager[S]) -> Int

    CollectionManager::create

    source

    CollectionManager::delete

    source
    async fn[S : 
    AsyncStorage    ] CollectionManager::delete(self : CollectionManager[S], name : String) -> Result[Unit, GatewayError]

    CollectionManager::exists

    source
    fn[S] CollectionManager::exists(self : CollectionManager[S], name : String) -> Bool

    CollectionManager::export_metadata

    source
    fn[S] CollectionManager::export_metadata(self : CollectionManager[S]) -> Json

    CollectionManager::get

    source

    Get or load a collection (async for lazy loading from storage)

    CollectionManager::get_db

    source
    fn[S] CollectionManager::get_db(self : CollectionManager[S], name : String) -> 
    PersistentDB    [S, S]?

    Get VectorDB for read operations (sync)

    CollectionManager::get_info

    source

    CollectionManager::list

    source

    CollectionManager::list_info

    source

    CollectionManager::load_collection

    source
    fn[S] CollectionManager::load_collection(self : CollectionManager[S], config : CollectionConfig, data : Bytes, storage : S, base_path : String) -> Result[Unit, GatewayError]

    CollectionManager::new

    source
    fn[S] CollectionManager::new(base_path? : String) -> CollectionManager[S]

    Create without storage (in-memory only)

    CollectionManager::remove_point

    source
    async fn[S : 
    AsyncStorage    ] CollectionManager::remove_point(self : CollectionManager[S], name : String, id : 
    VectorId    , timestamp_ns? : Int64) -> Result[Unit, GatewayError]

    Remove a point from a collection via PersistentVectorDB (WAL-before-state).

    CollectionManager::serialize_collection

    source
    fn[S] CollectionManager::serialize_collection(self : CollectionManager[S], name : String) -> Bytes?

    CollectionManager::upsert_points

    source
    async fn[S : 
    AsyncStorage    ] CollectionManager::upsert_points(self : CollectionManager[S], name : String, points : Array[(
    VectorId    , Array[Double], 
    Attrs    )], timestamp_ns? : Int64) -> Result[Int, GatewayError]

    Upsert points into a collection via PersistentVectorDB (WAL-before-state).

    CollectionManager::with_storage

    source
    fn[S] CollectionManager::with_storage(storage : S, base_path? : String, checkpoint_threshold? : Int) -> CollectionManager[S]

    Create with storage

    CollectionsResponse

    source
    pub struct CollectionsResponse {
      collections : Array[CollectionInfo]
    }

    Collections list response

    CollectionsResponse::to_json

    source

    Convert collections list to JSON

    PointData

    source
    pub struct PointData {
      id : Int64
      vector : Array[Double]
      payload : 
    Attrs
    }

    Single point for upsert
    impl Show for PointData

    PointData::from_json

    source
    fn PointData::from_json(json : Json) -> PointData?

    Parse point from JSON

    PointData::to_json

    source
    fn PointData::to_json(self : PointData) -> Json

    Convert point to JSON

    PointResponse

    source
    pub struct PointResponse {
      id : 
    VectorId
      payload : 
    Attrs
      vector : Array[Double]
    }

    Point response (for get operations)

    PointResponse::to_json

    source
    fn PointResponse::to_json(self : PointResponse) -> Json

    Convert point response to JSON

    ScrollPointResponse

    source
    pub struct ScrollPointResponse {
      id : 
    VectorId
      payload : 
    Attrs    ?
      vector : Array[Double]?
    }

    ScrollPointResponse::to_json

    source

    ScrollRequest

    source
    pub struct ScrollRequest {
      offset : Int64?
      limit : Int
      with_payload : Bool
      with_vector : Bool
    }

    Scroll request, modelled after Qdrant's scroll points API.

    ScrollRequest::from_json

    source
    fn ScrollRequest::from_json(json : Json) -> ScrollRequest?

    ScrollResponse

    source
    pub struct ScrollResponse {
      points : Array[ScrollPointResponse]
      next_page_offset : 
    VectorId    ?
    }

    ScrollResponse::to_json

    source
    fn ScrollResponse::to_json(self : ScrollResponse) -> Json

    SearchHitResponse

    source
    pub struct SearchHitResponse {
      id : 
    VectorId
      score : Double
      payload : 
    Attrs    ?
      vector : Array[Double]?
    }

    Search hit (result item)

    SearchHitResponse::to_json

    source

    Convert search hit to JSON

    SearchRequest

    source
    pub struct SearchRequest {
      vector : Array[Double]
      limit : Int
      filter : Json?
      with_payload : Bool
      with_vector : Bool
    }

    Search request

    SearchRequest::from_json

    source
    fn SearchRequest::from_json(json : Json) -> SearchRequest?

    Parse search request from JSON

    SearchResponse

    source
    pub struct SearchResponse {
      result : Array[SearchHitResponse]
      time_ms : Double
    }

    Search response

    SearchResponse::to_json

    source
    fn SearchResponse::to_json(self : SearchResponse) -> Json

    Convert search response to JSON

    UpsertRequest

    source
    pub struct UpsertRequest {
      points : Array[PointData]
    }

    Upsert request (batch)

    UpsertRequest::from_json

    source
    fn UpsertRequest::from_json(json : Json) -> UpsertRequest?

    Parse upsert request from JSON

    attr_value_to_json

    source
    fn attr_value_to_json(value : 
    AttrValue    ) -> Json

    Convert AttrValue to Json

    attrs_to_json

    source
    fn attrs_to_json(attrs : 
    Attrs    ) -> Json

    Convert Attrs to Json

    execute_path_request

    source
    async fn[S : 
    AsyncStorage    ] execute_path_request(manager : CollectionManager[S], http_method : String, target : String, body : String) -> ApiResponse

    Execute a request using a raw path such as /collections/demo?foo=bar.

    execute_request

    source
    async fn[S : 
    AsyncStorage    ] execute_request(manager : CollectionManager[S], http_method : String, path : Array[String], body : String) -> ApiResponse

    Parse and execute an API request, returning JSON response. All operations are now async since collection loading and writes require I/O.

    get_array

    source
    fn get_array(obj : Json, key : String) -> Array[Json]?

    Get an array field from a JSON object

    get_bool

    source
    fn get_bool(obj : Json, key : String) -> Bool?

    Get a boolean field from a JSON object

    get_int

    source
    fn get_int(obj : Json, key : String) -> Int?

    Get an integer field from a JSON object

    get_int64

    source
    fn get_int64(obj : Json, key : String) -> Int64?

    Get an Int64 field from a JSON object

    get_number

    source
    fn get_number(obj : Json, key : String) -> Double?

    Get a number field from a JSON object

    get_object

    source
    fn get_object(obj : Json, key : String) -> Map[String, Json]?

    Get an object field from a JSON object

    get_string

    source
    fn get_string(obj : Json, key : String) -> String?

    Get a string field from a JSON object

    handle_create_collection

    source
    async fn[S : 
    AsyncStorage    ] handle_create_collection(manager : CollectionManager[S], config : CollectionConfig) -> Result[Unit, GatewayError]

    Handle collection creation (async — writes to storage)

    handle_delete_collection

    source
    async fn[S : 
    AsyncStorage    ] handle_delete_collection(manager : CollectionManager[S], name : String) -> Result[Unit, GatewayError]

    Handle collection deletion (async — writes to storage)

    handle_get_collection

    source
    async fn[S : 
    AsyncStorage    ] handle_get_collection(manager : CollectionManager[S], name : String) -> Result[CollectionInfo, GatewayError]

    Handle get collection info (async — may load from storage)

    handle_get_point

    source

    Handle get point by ID (sync)

    handle_health

    source
    fn handle_health() -> Json

    Handle health check

    handle_list_collections

    source
    async fn[S : 
    AsyncStorage    ] handle_list_collections(manager : CollectionManager[S]) -> Result[CollectionsResponse, GatewayError]

    Handle list collections (async — may load from storage)

    handle_scroll

    source
    fn[W, S] handle_scroll(db : 
    PersistentDB    [W, S], req : ScrollRequest) -> Result[ScrollResponse, GatewayError]

    Handle scrolling points in a collection (sync).
    fn[W, S] handle_search(db : 
    PersistentDB    [W, S], req : SearchRequest) -> Result[SearchResponse, GatewayError]

    Handle search in a collection (sync — reads from in-memory engine)

    handle_service_info

    source
    fn handle_service_info() -> Json

    Handle service info

    json_array

    source
    fn json_array(items : Array[Json]) -> Json

    Build a JSON array

    json_object

    source
    fn json_object(pairs : Array[(String, Json)]) -> Json

    Build a JSON object from key-value pairs

    json_to_attr_value

    source
    fn json_to_attr_value(json : Json) -> 
    AttrValue    ?

    Convert Json to AttrValue

    json_to_attrs

    source
    fn json_to_attrs(json : Json) -> 
    Attrs    ?

    Convert Json (object) to Attrs

    json_to_vector

    source
    fn json_to_vector(json : Json) -> Array[Double]?

    Extract a vector (Array[Double]) from a JSON array

    parse_json

    source
    fn parse_json(s : String) -> Json?

    Parse a JSON string. Returns None for invalid input.

    parse_request_path

    source
    fn parse_request_path(path : String) -> Array[String]

    Parse a request path into gateway route segments.

    split_request_target

    source
    fn split_request_target(target : String) -> (String, String)

    Split a raw request target into path and query components.

    vector_to_json

    source
    fn vector_to_json(vec : Array[Double]) -> Json

    Convert a vector to JSON array

    with_collection

    source
    async fn[S : 
    AsyncStorage    , T] with_collection(manager : CollectionManager[S], name : String, handler : (
    PersistentDB    [S, S]) -> Result[T, GatewayError]) -> Result[T, GatewayError]

    Convenience: Handle request with collection name (async)

    Source Files

    Powered by MoonBit

    Site sourceReport issueModulesSkillsCLIBuild queueStatistics

    © 2026 mooncakes.io