🥮 mooncakes.io

    moonconsul

    A complete Consul client for MoonBit: agent, catalog, health, KV (with CAS, locks and semaphores), sessions, events, ACL, status, coordinate, prepared queries and config entries, with blocking queries and watch.

    consul
    discovery
    client
    moonbit
    kv
    acl
    session
    Download zip
    Version
    0.1.0
    License
    Apache-2.0
    Repository
    Last updated
    3 hours ago
    Downloads
    13

    #moonconsul

    A Consul client for MoonBit, with the surface of HashiCorp's Go consul/api: Agent, Catalog, Health, KV, Session, Event, ACL, Status, Coordinate, Prepared Query and Config Entries, plus locks, semaphores and watches. MoonBit types and snake_case names follow the organisation's conventions; the wire format, endpoints and semantics follow that package, and the tests run against real agents.

    #Quick start

    async fn main {
      let client = @fetch.connect()
      ignore(client.kv().put(pair))
      let lock = @concurrency.Lock::new(client, "jobs/nightly")
      lock.hold(() => run_the_job())
    }

    moonconsul needs nothing but a Transport, so it runs on every backend. moonconsul/fetch is the transport over moonfetch; connect(config~) gives a client for the agent config names, and default_config is http://127.0.0.1:8500 with no token.

    PackageHolds
    moonbitstack/moonconsulThe API groups, Transport, Client::poll
    moonbitstack/moonconsul/fetchFetch, connect
    moonbitstack/moonconsul/concurrencyLock, Semaphore, keep_alive, watch: what waits
    moonbitstack/moonconsul/sdRegistry, moonsd's Registrar and Discovery on Consul

    Examples are in src/examples/, each run with moon run src/examples/<name>--target native against consul agent -dev.

    #API surface

    Each group is a pub struct returned by a Client accessor. Reads take QueryOptions and return (Result, QueryMeta); writes take WriteOptions and return WriteMeta; every call raises Refused (see Errors).

    #Agent — client.agent()

    Service and check lifecycle on this agent, plus cluster membership and maintenance mode.

    MethodIntent
    service_register(reg, options~)Register a service (with inline checks) on this agent
    service_deregister(id, options~)Deregister a service instance
    check_register(reg, options~)Register a check (optionally bound to a service)
    check_deregister(check_id, options~)Deregister a check
    check_pass(check_id, options~)Mark a TTL/HTTP/TCP/gRPC check passing
    check_fail(check_id, options~)Mark a check failing
    check_update(update, options~)Set a TTL check's status/output without resetting its clock
    self(options~)This agent's config, member record and stats
    members(options~)Cluster members this agent gossips with
    members_with_filter(filter, options~)Members, requiring a tag filter
    join(address, wan~, options~)Ask an agent to join the cluster (LAN or WAN)
    leave(options~)Leave the cluster gracefully
    force_leave(node, options~)Force a node out without its cooperation
    enable_service_maintenance(service_id, reason~, options~)Put a service instance in maintenance mode
    disable_service_maintenance(service_id, options~)Take a service instance out of maintenance mode
    enable_node_maintenance(reason~, options~)Put the whole node in maintenance mode
    disable_node_maintenance(options~)Take the node out of maintenance mode
    update_acl_token(token, options~)Replace the agent's local ACL token

    #Catalog — client.catalog()

    Datacenter-wide registration and read-only listing of nodes and services.

    MethodIntent
    register(reg, options~)Register a node/service/check against the catalog
    deregister(dereg, options~)Remove a node, service or check from the catalog
    datacenters(options~)Datacenters in the WAN federation
    nodes(options~)Nodes in this datacenter
    node(node, options~)One node and every service on it
    services(options~)Service names, each with its tag set
    service(service, options~)Instances of a service in this datacenter

    #Health — client.health()

    Checks and the healthy instances of a service, including blocking queries that watch a service for membership changes.

    MethodIntent
    node(node, options~)Checks on a node
    checks(service, options~)Checks belonging to a service
    checks_in_state(state, options~)Checks in a given state
    service(service, passing~, options~)Healthy instances of a service (blocking)
    state(state, options~)Checks in any of the three states
    connect_service(service, passing~, options~)Only connect-mesh-reachable instances

    #KV — client.kv()

    The key/value store. flags and the indexes are UInt64, as Consul has them.

    MethodIntent
    get(key, options~)Read one key (None when absent)
    list(prefix, options~)Every entry under a prefix
    keys(prefix, options~)Only the keys under a prefix
    put(pair, options~)Write a pair
    delete(key, options~)Delete a key
    delete_cas(pair, options~)Delete a key if its index still matches; true on success
    delete_tree(prefix, options~)Delete every entry under a prefix
    cas(pair, options~)Compare-and-swap; true on success
    acquire(pair, options~)Acquire the lock on a key for a session
    release(pair, options~)Release the lock held by a session
    txn(ops, options~)Atomic batch of read and write operations

    #Session — client.session()

    Ephemeral leases bound to a set of checks; they back locks and semaphores. When a session's checks fail or its TTL lapses, its held keys are released.

    MethodIntent
    create(entry~, options~)Create a session; the result carries the assigned id
    destroy(id, options~)Destroy a session, releasing everything it holds
    renew(id, options~)Renew a session; None if it expired
    info(id, options~)Read one session by id
    node(node, options~)Sessions active on a node
    list(options~)Every session in the datacenter

    lock_delay is in nanoseconds, and Consul reads a value under 1000 as seconds. @concurrency.keep_alive renews a session until its task is cancelled.

    #Event — client.event()

    User events fanned out across the datacenter, optionally scoped to nodes, services or tags.

    MethodIntent
    fire(name, payload, options~, write_options~)Fire an event, returning the accepted event
    list(options~, query_options~)List events, optionally by name

    #ACL — client.acl()

    Tokens, policies, roles, auth methods and binding rules.

    Tokens: token_create, token_update, token_read, token_read_self, token_list, token_clone, token_delete, token_login, token_logout. Policies: policy_create, policy_update, policy_read, policy_list, policy_delete. Roles: role_create, role_update, role_read, role_read_by_name, role_list, role_delete. Auth methods: auth_method_create, auth_method_update, auth_method_read, auth_method_list, auth_method_delete. Binding rules: binding_rule_create, binding_rule_update, binding_rule_read, binding_rule_list, binding_rule_delete.

    #Status — client.status()

    MethodIntent
    leader(options~)Address of the Raft leader (empty if none)
    peers(options~)Raft peer addresses of the cluster

    #Coordinate — client.coordinate()

    Network coordinates (Vivaldi-embedded positions) for latency-aware routing.

    MethodIntent
    datacenters(options~)Coordinates of every datacenter
    nodes(options~)Coordinates of the nodes in this datacenter
    update(coord, options~)Publish this node's own coordinate

    #Prepared Query — client.prepared_query()

    Named and templated service queries with failover.

    MethodIntent
    create(def, options~)Create a query; result carries the assigned id
    update(def, options~)Update an existing query
    get(id, options~)Read a query by id
    delete(id, options~)Delete a query
    execute(id_or_name, params~, options~)Run a query by id or name
    list(options~)List every query in the datacenter

    #Config Entries — client.config_entries()

    Typed, centrally-stored configuration objects (service defaults, routers, splitters, resolvers, mesh-wide settings). A read returns the ConfigEntry variant for the stored kind; a write carries the variant to store.

    MethodIntent
    get(kind, name, options~)Read one config entry
    list(kind, options~)List the entries of one kind
    set(entry, options~)Write a config entry
    delete(kind, name, options~)Delete a config entry

    #Locks and semaphores

    @concurrency.Lock and @concurrency.Semaphore run the protocol of Go's api.Lock and api.Semaphore, which is what consul lock runs, so a lock here and one held by that command exclude each other. A test checks this against the command.

    let lock = @concurrency.Lock::new(client, "jobs/nightly")
    lock.hold(() => run_the_job())

    let seats = @concurrency.Semaphore::new(client, "jobs/workers", 4)
    seats.hold(() => run_a_worker())

    MethodDoes
    hold(body)Wait for it, run body with the session renewed, give it back. If it is lost, body is cancelled and this raises Conflict
    acquire()Wait for it. The session is renewed only during the wait, so a holder runs keep_alive itself
    try_acquire()Take it if it is free now
    release()Give it back, and destroy a session this value created
    destroy()Delete the keys of one nobody holds

    Cancelling the task gives up a wait, so @async.with_timeout bounds one. LockOptions and SemaphoreOptions default to Go's values; pass session to run on a session of your own, which then stays yours to renew and destroy.

    #Blocking queries and watches

    Reads take QueryOptions: set wait_index and wait_time to make a blocking query, and feed the returned QueryMeta.last_index into the next call.

    @concurrency.watch(client, kind, handler) is that loop, and runs until its task is cancelled. kind is a WatchKind, one per watch type of Consul's: Key, KeyPrefix, Services, Nodes, Service, Checks, State, Event, ConnectRoots, ConnectLeaf, AgentService.

    @concurrency.watch(client, Service("web", passing=true), (index, value) => {
      println("\{index}: \{value.stringify()}")
    })

    handler is called when the value changes, not each time the index moves. A failed query is tried again after retry milliseconds, then 4, 9, 16... times that, up to limit, as in Go's watch.Plan. Client::poll is one round of it.

    #Options and metadata

    • QueryOptions — datacenter, ns, token, wait_index, wait_hash, wait_time, consistency, near, filter, node_meta. default_query_options is a non-blocking default-consistency read.
    • WriteOptions — datacenter, ns, token. default_write_options has no overrides.
    • ConsistencyMode — Default, Consistent, Stale.
    • QueryMeta — last_index, last_hash, last_contact, known_leader, request_time.
    • WriteMeta — request_time.

    #Errors

    Every API method reports through Refused (a suberror), never Result[_, _]:

    VariantMeaning
    Transport(String)The HTTP medium could not carry the request
    Status(Int32, String)Non-2xx agent response and its body
    Json(String)A response body was not the JSON expected
    Conflict(String)A lock or semaphore is held, in use, lost, or not one
    NotFoundThe key, session or entry does not exist
    Param(String)A bad argument before the call left the client

    #Transport

    The client reaches an agent through a trait, and moonconsul/fetch is the one a program uses:

    pub(open) trait Transport {
      async fn send(Self, Request) -> Response raise Refused
    }

    Request and Response carry the verb, URL, headers, body and status. Implement the trait to send through something else; the white-box tests use one that returns canned bytes.

    #The gate

    Every commit passes this, with each exit code seen to be zero:

    moon clean && moon fmt && moon check --target all --deny-warn \
  && moon build --target all && moon test --target all

    src/integration runs against real agents: scripts/start_consul.sh starts two in Docker, one with ACLs on, and MOONCONSUL_LIVE=1 makes a missing agent a failure instead of a skip. MOONCONSUL_CONTAINER names the container whose consul command the interoperability tests run.

    #Releasing

    Push a signed tag v<version>. release.yml runs the tests first and publishes only if they pass and the organisation variable MOONCAKES_PUBLISH is true. The major version stays at 0.

    #License

    Apache-2.0.

    Transport

    source
    pub(open) trait Transport {
      async fn send(self : Self, Request) -> Response raise Refused
    }

    The HTTP medium a Client drives. It performs one request and returns the response, or raises Refused on a transport failure. The production client plugs an HTTP-backed transport in here; tests plug an in-memory fake that returns canned responses, so the request shaping and JSON parsing run against a real agent's wire format without a network.

    Refused

    source
    pub(all) suberror Refused {
      Transport(String)
      Status(Int, String)
      Json(String)
      Conflict(String)
      NotFound
      Param(String)
    }

    Errors raised by a Consul API call: a transport failure, a non-2xx agent response, a JSON decode failure, a lock conflict, or a bad input.

    ACL

    source
    pub struct ACL {
      client : Client
    }

    A handle to the ACL API: tokens (the credentials calls carry), policies (rule sets), roles (policy groupings), auth methods and binding rules.

    ACL::auth_method_create

    source
    async fn ACL::auth_method_create(self : ACL, entry : ACLAuthMethod, options? : WriteOptions) -> (ACLAuthMethod, WriteMeta) raise Refused

    Create an auth method.

    ACL::auth_method_delete

    source
    async fn ACL::auth_method_delete(self : ACL, name : String, options? : WriteOptions) -> WriteMeta raise Refused

    Delete an auth method by name.

    ACL::auth_method_list

    source
    async fn ACL::auth_method_list(self : ACL, options? : QueryOptions) -> (Array[ACLAuthMethod], QueryMeta) raise Refused

    List auth methods.

    ACL::auth_method_read

    source
    async fn ACL::auth_method_read(self : ACL, name : String, options? : QueryOptions) -> (ACLAuthMethod, QueryMeta) raise Refused

    Read an auth method by name.

    ACL::auth_method_update

    source
    async fn ACL::auth_method_update(self : ACL, entry : ACLAuthMethod, options? : WriteOptions) -> (ACLAuthMethod, WriteMeta) raise Refused

    Update an auth method.

    ACL::binding_rule_create

    source
    async fn ACL::binding_rule_create(self : ACL, rule : ACLBindingRule, options? : WriteOptions) -> (ACLBindingRule, WriteMeta) raise Refused

    Create a binding rule.

    ACL::binding_rule_delete

    source
    async fn ACL::binding_rule_delete(self : ACL, id : String, options? : WriteOptions) -> WriteMeta raise Refused

    Delete a binding rule by id.

    ACL::binding_rule_list

    source
    async fn ACL::binding_rule_list(self : ACL, options? : QueryOptions) -> (Array[ACLBindingRule], QueryMeta) raise Refused

    List binding rules.

    ACL::binding_rule_read

    source
    async fn ACL::binding_rule_read(self : ACL, id : String, options? : QueryOptions) -> (ACLBindingRule, QueryMeta) raise Refused

    Read a binding rule by id.

    ACL::binding_rule_update

    source
    async fn ACL::binding_rule_update(self : ACL, rule : ACLBindingRule, options? : WriteOptions) -> (ACLBindingRule, WriteMeta) raise Refused

    Update a binding rule.

    ACL::policy_create

    source
    async fn ACL::policy_create(self : ACL, policy : ACLPolicy, options? : WriteOptions) -> (ACLPolicy, WriteMeta) raise Refused

    Create a policy.

    ACL::policy_delete

    source
    async fn ACL::policy_delete(self : ACL, id : String, options? : WriteOptions) -> WriteMeta raise Refused

    Delete a policy by id or name.

    ACL::policy_list

    source
    async fn ACL::policy_list(self : ACL, options? : QueryOptions) -> (Array[ACLPolicy], QueryMeta) raise Refused

    List policies.

    ACL::policy_read

    source
    async fn ACL::policy_read(self : ACL, id : String, options? : QueryOptions) -> (ACLPolicy, QueryMeta) raise Refused

    Read a policy by id or name.

    ACL::policy_update

    source
    async fn ACL::policy_update(self : ACL, policy : ACLPolicy, options? : WriteOptions) -> (ACLPolicy, WriteMeta) raise Refused

    Update a policy.

    ACL::role_create

    source
    async fn ACL::role_create(self : ACL, role : ACLRole, options? : WriteOptions) -> (ACLRole, WriteMeta) raise Refused

    Create a role.

    ACL::role_delete

    source
    async fn ACL::role_delete(self : ACL, id : String, options? : WriteOptions) -> WriteMeta raise Refused

    Delete a role by id or name.

    ACL::role_list

    source
    async fn ACL::role_list(self : ACL, options? : QueryOptions) -> (Array[ACLRole], QueryMeta) raise Refused

    List roles.

    ACL::role_read

    source
    async fn ACL::role_read(self : ACL, id : String, options? : QueryOptions) -> (ACLRole, QueryMeta) raise Refused

    Read a role by id or name.

    ACL::role_read_by_name

    source
    async fn ACL::role_read_by_name(self : ACL, name : String, options? : QueryOptions) -> (ACLRole, QueryMeta) raise Refused

    Read a role by name.

    ACL::role_update

    source
    async fn ACL::role_update(self : ACL, role : ACLRole, options? : WriteOptions) -> (ACLRole, WriteMeta) raise Refused

    Update a role.

    ACL::token_clone

    source
    async fn ACL::token_clone(self : ACL, id : String, options? : WriteOptions) -> (ACLToken, WriteMeta) raise Refused

    Clone a token, returning a new one with the same policies and roles.

    ACL::token_create

    source
    async fn ACL::token_create(self : ACL, token : ACLToken, options? : WriteOptions) -> (ACLToken, WriteMeta) raise Refused

    Create a token.

    ACL::token_delete

    source
    async fn ACL::token_delete(self : ACL, id : String, options? : WriteOptions) -> WriteMeta raise Refused

    Delete a token by id or accessor id.

    ACL::token_list

    source
    async fn ACL::token_list(self : ACL, options? : QueryOptions) -> (Array[ACLToken], QueryMeta) raise Refused

    List tokens.

    ACL::token_login

    source
    async fn ACL::token_login(self : ACL, params : ACLLoginParams, options? : WriteOptions) -> (ACLToken, WriteMeta) raise Refused

    Exchange an auth-method bearer_token for a Consul token.

    ACL::token_logout

    source
    async fn ACL::token_logout(self : ACL, options? : WriteOptions) -> WriteMeta raise Refused

    Drop the token the client is authenticated with.

    ACL::token_read

    source
    async fn ACL::token_read(self : ACL, id : String, options? : QueryOptions) -> (ACLToken, QueryMeta) raise Refused

    Read a token by id or accessor id.

    ACL::token_read_self

    source
    async fn ACL::token_read_self(self : ACL, options? : QueryOptions) -> (ACLToken, QueryMeta) raise Refused

    Read the token the client is authenticated with.

    ACL::token_update

    source
    async fn ACL::token_update(self : ACL, token : ACLToken, options? : WriteOptions) -> (ACLToken, WriteMeta) raise Refused

    Update a token.

    ACLAuthMethod

    source
    pub(all) struct ACLAuthMethod {
      name : String?
      kind : String?
      description : String?
      config : Map[String, String]?
      ns : String?
      partition : String?
    }

    An auth method: a name and kind (e.g. kubernetes, oidc), its config, and its description.

    ACLBindingRule

    source
    pub(all) struct ACLBindingRule {
      id : String?
      description : String?
      auth_method : String?
      selector : String?
      bind_type : String?
      bind_name : String?
      ns : String?
      partition : String?
    }

    A binding rule: selects identities from an auth method and maps them to a bind_type/bind_name via selector.

    ACLLoginParams

    source
    pub(all) struct ACLLoginParams {
      auth_method : String?
      bearer_token : String?
      token_metadata : Map[String, String]?
    }

    Parameters for token_login.

    ACLPolicy

    source
    pub(all) struct ACLPolicy {
      id : String?
      name : String?
      description : String?
      rules : String?
      datacenter : String?
      ns : String?
      partition : String?
      hash : String?
    }

    A policy: a name and its rules (HCL or JSON) plus its description.

    ACLRole

    source
    pub(all) struct ACLRole {
      id : String?
      name : String?
      description : String?
      policies : Array[ACLRolePolicyLink]?
      ns : String?
      partition : String?
      hash : String?
    }

    A role: a name grouping policies, plus its description and hash.
    pub(all) struct ACLRolePolicyLink {
      id : String?
      name : String?
    }

    A link from a role to a policy, by id or name.

    ACLToken

    source
    pub(all) struct ACLToken {
      id : String?
      accessor_id : String?
      secret_id : String?
      description : String?
      policies : Array[ACLTokenPolicyLink]?
      roles : Array[ACLTokenRoleLink]?
      is_local : Bool?
      ns : String?
      partition : String?
      hash : String?
      expiration_time : String?
    }

    A token: its accessor_id (for reference) and secret_id (for calls), the policies and roles it binds, whether it is is_local to one datacenter, and its description and hash.
    pub(all) struct ACLTokenPolicyLink {
      id : String?
      name : String?
    }

    A link from a token to a policy, by id or name.
    pub(all) struct ACLTokenRoleLink {
      id : String?
      name : String?
    }

    A link from a token to a role, by id or name.

    Agent

    source
    pub struct Agent {
      client : Client
    }

    A handle to the Agent API: register and deregister services and checks on this agent, keep TTL checks alive, read the agent's own state, and manage cluster membership and maintenance mode.

    Agent::check_deregister

    source
    async fn Agent::check_deregister(self : Agent, check_id : String, options? : WriteOptions) -> WriteMeta raise Refused

    Deregister the check check_id from this agent.

    Agent::check_fail

    source
    async fn Agent::check_fail(self : Agent, check_id : String, options? : WriteOptions) -> WriteMeta raise Refused

    Mark the check check_id failing.

    Agent::check_pass

    source
    async fn Agent::check_pass(self : Agent, check_id : String, options? : WriteOptions) -> WriteMeta raise Refused

    Mark the TTL/http/tcp/grpc check check_id passing; the keep-alive that renews a service's lease.

    Agent::check_register

    source
    async fn Agent::check_register(self : Agent, reg : AgentCheckRegistration, options? : WriteOptions) -> WriteMeta raise Refused

    Register reg (a check, optionally bound to a service) with this agent.

    Agent::check_update

    source
    async fn Agent::check_update(self : Agent, update : AgentCheckUpdate, options? : WriteOptions) -> WriteMeta raise Refused

    Set a TTL check's status and output without resetting its TTL clock.

    Agent::checks

    source
    async fn Agent::checks(self : Agent, options? : QueryOptions) -> (Map[String, HealthCheck], QueryMeta) raise Refused

    The checks registered with this agent, by id.

    Agent::disable_node_maintenance

    source
    async fn Agent::disable_node_maintenance(self : Agent, options? : WriteOptions) -> WriteMeta raise Refused

    Take the node out of maintenance mode.

    Agent::disable_service_maintenance

    source
    async fn Agent::disable_service_maintenance(self : Agent, service_id : String, options? : WriteOptions) -> WriteMeta raise Refused

    Take the service instance service_id out of maintenance mode.

    Agent::enable_node_maintenance

    source
    async fn Agent::enable_node_maintenance(self : Agent, reason? : String, options? : WriteOptions) -> WriteMeta raise Refused

    Put the whole node into maintenance mode.

    Agent::enable_service_maintenance

    source
    async fn Agent::enable_service_maintenance(self : Agent, service_id : String, reason? : String, options? : WriteOptions) -> WriteMeta raise Refused

    Put the service instance service_id into maintenance mode, marking its checks maintenance with reason; the instance stays registered but looks down to health checks.

    Agent::force_leave

    source
    async fn Agent::force_leave(self : Agent, node : String, options? : WriteOptions) -> WriteMeta raise Refused

    Force a node out of the cluster without its cooperation.

    Agent::join

    source
    async fn Agent::join(self : Agent, address : String, wan? : Bool, options? : WriteOptions) -> WriteMeta raise Refused

    Ask the agent at address to join the cluster; wan joins over the WAN gossip pool rather than the LAN pool.

    Agent::leave

    source
    async fn Agent::leave(self : Agent, options? : WriteOptions) -> WriteMeta raise Refused

    Ask this agent to leave the cluster gracefully.

    Agent::members

    source
    async fn Agent::members(self : Agent, options? : QueryOptions) -> (Array[AgentMember], QueryMeta) raise Refused

    The cluster members this agent gossips with. options.filter (a go-compatible tag expression) narrows the returned set.

    Agent::members_with_filter

    source
    async fn Agent::members_with_filter(self : Agent, filter : String, options? : QueryOptions) -> (Array[AgentMember], QueryMeta) raise Refused

    Like members, but filter is required rather than optional.

    Agent::self

    source
    async fn Agent::self(self : Agent, options? : QueryOptions) -> (AgentSelf, QueryMeta) raise Refused

    The agent's own configuration, member record and runtime stats.

    Agent::service_deregister

    source
    async fn Agent::service_deregister(self : Agent, id : String, options? : WriteOptions) -> WriteMeta raise Refused

    Deregister the service instance id from this agent.

    Agent::service_register

    source
    async fn Agent::service_register(self : Agent, reg : AgentServiceRegistration, options? : WriteOptions) -> WriteMeta raise Refused

    Register reg with this agent. A service with an inline TTL check starts critical; follow with check_pass to make it healthy.

    Agent::services

    source
    async fn Agent::services(self : Agent, options? : QueryOptions) -> (Map[String, AgentService], QueryMeta) raise Refused

    The services registered with this agent, by id.

    Agent::update_acl_token

    source
    async fn Agent::update_acl_token(self : Agent, token : String, options? : WriteOptions) -> WriteMeta raise Refused

    Replace the agent's ACL token (used when the local token must change without restarting the agent).

    AgentCheck

    source
    pub(all) struct AgentCheck {
      id : String
      name : String?
      status : String?
      notes : String?
      output : String?
      service_id : String?
      service_name : String?
      ns : String?
    }

    A check as reported by self and the check endpoints: its id, name, current status (passing, warning, critical), output, and the service it guards.

    AgentCheckRegistration

    source
    pub(all) struct AgentCheckRegistration {
      id : String?
      name : String
      notes : String?
      service_id : String?
      service_name : String?
      ns : String?
      status : String?
      definition : AgentServiceCheck
    }

    The body of PUT /v1/agent/check/register: the identity fields plus the check definition folded in as definition.

    AgentCheckUpdate

    source
    pub(all) struct AgentCheckUpdate {
      check_id : String
      status : String
      output : String?
    }

    The body of PUT /v1/agent/check/update: set a TTL check's status and output without sending a fresh TTL. check_id names the check to update.

    AgentMember

    source
    pub(all) struct AgentMember {
      name : String
      addr : String
      port : Int
      tags : Map[String, String]?
      status : String?
    }

    A cluster member as seen by the agent's gossip layer: its name, addr, port, status, and the tags it gossips (including role, dc, vsn).

    AgentSelf

    source
    pub(all) struct AgentSelf {
      config : Json
      agent_member : AgentMember
      stats : Json
    }

    The agent's own state: its config, its agent_member record, and stats.

    AgentService

    source
    pub(all) struct AgentService {
      id : String
      service : String
      tags : Array[String]
      address : String?
      port : Int?
      meta : Map[String, String]?
      ns : String?
      weights : AgentWeights?
    }

    A service registered on this agent. id defaults to name when empty; tags and meta are free-form; address and port are where the instance listens (when unset, the agent's address is used).

    AgentServiceCheck

    source
    pub(all) struct AgentServiceCheck {
      id : String?
      name : String?
      notes : String?
      service_id : String?
      status : String?
      ttl : String?
      interval : String?
      timeout : String?
      http : String?
      tls_skip_verify : Bool?
      http_method : String?
      tcp : String?
      grpc : String?
      grpc_use_tls : Bool?
      header : Map[String, Array[String]]?
      deregister_critical_service_after : String?
      alias_node : String?
      alias_service : String?
      success_before_passing : Int?
      failures_before_critical : Int?
    }

    A health check registered alongside a service or on its own. One of ttl, interval+script/http/tcp/grpc, or alias_* selects the check kind; deregister_critical_service_after lets a failing check auto-remove its service.

    AgentServiceRegistration

    source
    pub(all) struct AgentServiceRegistration {
      id : String?
      name : String
      tags : Array[String]?
      address : String?
      port : Int?
      meta : Map[String, String]?
      ns : String?
      check : AgentServiceCheck?
      checks : Array[AgentServiceCheck]?
      enable_tag_override : Bool?
      weights : AgentWeights?
    }

    The body of PUT /v1/agent/service/register: a service plus at most one inline check (check) or several (checks); enable_tag_override lets the agent's tags be overridden by the catalog.

    AgentWeights

    source
    pub(all) struct AgentWeights {
      passing : Int?
      warning : Int?
    }

    The primary and passing weights of a service, used by DNS and prepared queries. passing defaults to 1 and warning to 1 when unset.

    Catalog

    source
    pub struct Catalog {
      client : Client
    }

    A handle to the Catalog API: datacenter-wide registration of nodes and services, and read-only listing of nodes, services and their metadata.

    Catalog::datacenters

    source
    async fn Catalog::datacenters(self : Catalog, options? : QueryOptions) -> (Array[String], QueryMeta) raise Refused

    The datacenters in the WAN federation.

    Catalog::deregister

    source
    async fn Catalog::deregister(self : Catalog, dereg : CatalogDeregistration, options? : WriteOptions) -> WriteMeta raise Refused

    Deregister dereg from the catalog.

    Catalog::node

    source
    async fn Catalog::node(self : Catalog, node : String, options? : QueryOptions) -> (CatalogNode, QueryMeta) raise Refused

    One node and every service registered on it.

    Catalog::nodes

    source
    async fn Catalog::nodes(self : Catalog, options? : QueryOptions) -> (Array[Node], QueryMeta) raise Refused

    The nodes in this datacenter, narrowed by options.filter.

    Catalog::register

    source
    async fn Catalog::register(self : Catalog, reg : CatalogRegistration, options? : WriteOptions) -> WriteMeta raise Refused

    Register reg against the catalog.

    Catalog::service

    source
    async fn Catalog::service(self : Catalog, service : String, options? : QueryOptions) -> (Array[CatalogService], QueryMeta) raise Refused

    The instances of service in this datacenter.

    Catalog::services

    source
    async fn Catalog::services(self : Catalog, options? : QueryOptions) -> (Map[String, Array[String]], QueryMeta) raise Refused

    The service names in this datacenter, each with its tag set.

    CatalogDeregistration

    source
    pub(all) struct CatalogDeregistration {
      node : String
      address : String?
      service_id : String?
      check_id : String?
      ns : String?
      partition : String?
    }

    The body of PUT /v1/catalog/deregister: identifies a node, service or check to remove.

    CatalogNode

    source
    pub(all) struct CatalogNode {
      node : Node
      services : Map[String, CatalogNodeService]?
    }

    A node together with every service registered on it.

    CatalogNodeService

    source
    pub(all) struct CatalogNodeService {
      id : String
      service : String
      tags : Array[String]
      meta : Map[String, String]?
      ns : String?
      port : Int?
      address : String?
      weights : AgentWeights?
    }

    A single service bound to a node, as returned by node.

    CatalogRegistration

    source
    pub(all) struct CatalogRegistration {
      node : String
      address : String
      node_meta : Map[String, String]?
      ns : String?
      partition : String?
      service : CatalogService?
      check : AgentCheck?
      checks : Array[AgentCheck]?
    }

    The body of PUT /v1/catalog/register: a node and address, optional node_meta, and at most one service and check (or several checks) to register against that node.

    CatalogService

    source
    pub(all) struct CatalogService {
      id : String
      node : String
      address : String
      service : String
      tags : Array[String]
      meta : Map[String, String]?
      ns : String?
      partition : String?
      port : Int?
      weights : AgentWeights?
      create_index : UInt64?
      modify_index : UInt64?
    }

    A service as listed by the catalog: its id, the node it runs on, and its tags, meta and port.

    Client

    source
    pub struct Client {
      config : Config
      transport : &Transport
    }

    A Consul client. It carries a Config and the Transport that performs the HTTP calls, and hands out one handle per API group; each handle shares this client, so a token or datacenter set on the client applies across groups.

    Client::acl

    source
    fn Client::acl(self : Client) -> ACL

    The ACL API: tokens, policies, roles, auth methods and binding rules.

    Client::agent

    source
    fn Client::agent(self : Client) -> Agent

    The Agent API: service and check lifecycle on this agent.

    Client::catalog

    source
    fn Client::catalog(self : Client) -> Catalog

    The Catalog API: datacenter-wide node and service registration.

    Client::config_entries

    source
    fn Client::config_entries(self : Client) -> ConfigEntries

    The Config Entries API: centralized configuration objects.

    Client::coordinate

    source
    fn Client::coordinate(self : Client) -> Coordinate

    The Coordinate API: network coordinates for latency-aware routing.

    Client::do_delete

    source
    async fn Client::do_delete(self : Client, path : String, opt : WriteOptions, extra : Array[(String, String)]) -> (Json, WriteMeta) raise Refused

    A DELETE with opt and extra query pairs, returning the parsed body and a fresh write metadata.

    Client::do_get

    source
    async fn Client::do_get(self : Client, path : String, opt : QueryOptions, extra : Array[(String, String)]) -> (Json, QueryMeta) raise Refused

    A GET with opt and extra query pairs, returning the parsed body and the query metadata.

    Client::do_get_found

    source
    async fn Client::do_get_found(self : Client, path : String, opt : QueryOptions, extra : Array[(String, String)]) -> (Json?, QueryMeta) raise Refused

    A GET that takes a 404 for an answer: None, with the index the agent gave it, which is what a blocking read of something absent waits from.

    Client::do_post

    source
    async fn Client::do_post(self : Client, path : String, body : Bytes, opt : WriteOptions, extra : Array[(String, String)]) -> (Json, WriteMeta) raise Refused

    A POST with opt and extra query pairs (used by the ACL login/logout endpoints), returning the parsed body and a fresh write metadata.

    Client::do_put

    source
    async fn Client::do_put(self : Client, path : String, body : Bytes, opt : WriteOptions, extra : Array[(String, String)]) -> (Json, WriteMeta) raise Refused

    A PUT with opt and extra query pairs, returning the parsed body and a fresh write metadata.

    Client::do_put_q

    source
    async fn Client::do_put_q(self : Client, path : String, body : Bytes, opt : WriteOptions, extra : Array[(String, String)]) -> (Json, QueryMeta) raise Refused

    A PUT over a query-style call (e.g. txn): returns the parsed body and the blocking-query metadata instead of a WriteMeta.

    Client::event

    source
    fn Client::event(self : Client) -> Event

    The Event API: user events fanned out across the datacenter.

    Client::health

    source
    fn Client::health(self : Client) -> Health

    The Health API: checks and the healthy instances of a service.

    Client::kv

    source
    fn Client::kv(self : Client) -> KV

    The KV API: the key/value store, with compare-and-swap, locks and semaphores.

    Client::new

    source
    fn Client::new(config : Config, transport : &Transport) -> Client

    A client over config and transport.

    Client::poll

    source
    async fn Client::poll(self : Client, kind : WatchKind, options? : QueryOptions) -> (Json?, QueryMeta) raise Refused

    One read of kind, as raw JSON, blocking as options says. None is a 404, which is what a key answers until it exists. @concurrency.watch is the loop around this.

    Client::prepared_query

    source
    fn Client::prepared_query(self : Client) -> PreparedQuery

    The Prepared Query API: named and templated service queries.

    Client::session

    source
    fn Client::session(self : Client) -> Session

    The Session API: sessions that back locks and semaphores.

    Client::status

    source
    fn Client::status(self : Client) -> Status

    The Status API: leader and peer membership.

    Client::with_address

    source
    fn Client::with_address(address : String, transport : &Transport) -> Client

    A client targeting address over transport, with the rest at defaults.

    Config

    source
    pub(all) struct Config {
      address : String
      scheme : String
      datacenter : String?
      ns : String?
      token : String?
      wait_time : Int64
      consistency : ConsistencyMode
      tls : TlsConfig
      transport : &Transport?
    }

    A Consul client configuration. address is host:port; scheme is http or https. datacenter, namespace and token are the defaults applied to every call unless a call's own options override them. wait_time bounds a blocking query when QueryOptions.wait_time is unset. transport overrides the default moonfetch-backed medium; tests pass an in-memory fake.

    ConfigEntries

    source
    pub struct ConfigEntries {
      client : Client
    }

    A handle to the Config Entries API: typed, centrally-stored configuration objects (service defaults, routers, splitters, resolvers, mesh-wide settings) that Consul serves to the data plane.

    ConfigEntries::delete

    source
    async fn ConfigEntries::delete(self : ConfigEntries, kind : String, name : String, options? : WriteOptions) -> WriteMeta raise Refused

    Delete the config entry of kind and name.

    ConfigEntries::get

    source
    async fn ConfigEntries::get(self : ConfigEntries, kind : String, name : String, options? : QueryOptions) -> (ConfigEntry, QueryMeta) raise Refused

    Read one config entry by kind and name.

    ConfigEntries::list

    source
    async fn ConfigEntries::list(self : ConfigEntries, kind : String, options? : QueryOptions) -> (Array[ConfigEntry], QueryMeta) raise Refused

    List the config entries of kind.

    ConfigEntries::set

    source
    async fn ConfigEntries::set(self : ConfigEntries, entry : ConfigEntry, options? : WriteOptions) -> WriteMeta raise Refused

    Write entry; the wrapped entry carries its own kind and name.

    ConfigEntry

    source
    pub(all) enum ConfigEntry {
      ServiceDefault(ServiceDefaultConfigEntry)
      ServiceRouter(ServiceRouterConfigEntry)
      ServiceSplitter(ServiceSplitterConfigEntry)
      ServiceResolver(ServiceResolverConfigEntry)
      Mesh(MeshConfigEntry)
    }

    A config entry. Each variant carries the typed entry for one kind; a read returns the variant for the stored kind, and a write carries the variant to store. kind and name are read from the wrapped entry.

    ConsistencyMode

    source
    pub(all) enum ConsistencyMode {
      Default
      Consistent
      Stale
    }

    How strongly a read must reflect cluster state. Default is served from a follower that may be stale within a bounded window; Consistent is served from the leader and linearizable; Stale is served from any node, including one with no leader, for maximum availability.

    Coordinate

    source
    pub struct Coordinate {
      client : Client
    }

    A handle to the Coordinate API: network coordinates (Vivaldi-embedded positions) for latency-aware routing and nearest-node selection.

    Coordinate::datacenters

    source
    async fn Coordinate::datacenters(self : Coordinate, options? : QueryOptions) -> (Array[CoordinateNode], QueryMeta) raise Refused

    The coordinates of every datacenter, as seen from this node.

    Coordinate::nodes

    source
    async fn Coordinate::nodes(self : Coordinate, options? : QueryOptions) -> (Array[CoordinateEntry], QueryMeta) raise Refused

    The coordinates of the nodes in this datacenter.

    Coordinate::update

    source
    async fn Coordinate::update(self : Coordinate, coord : CoordinateValue, options? : WriteOptions) -> WriteMeta raise Refused

    Publish this node's own coord.

    CoordinateEntry

    source
    pub(all) struct CoordinateEntry {
      node : String
      segment : String?
      coord : CoordinateValue?
    }

    One node's coordinate in a segment.

    CoordinateNode

    source
    pub(all) struct CoordinateNode {
      node : String
      coordinates : Array[CoordinateEntry]
    }

    A node and the coordinates it holds for each datacenter segment.

    CoordinateValue

    source
    pub(all) struct CoordinateValue {
      vec : Array[Double]
      error : Double
      adjustment : Double
      height : Double
    }

    A single node's network coordinate: a vec in the embedded space plus an error, adjustment and height.

    DNSQuery

    source
    pub(all) struct DNSQuery {
      ttl : String?
    }

    DNS tuning for a query.

    Event

    source
    pub struct Event {
      client : Client
    }

    A handle to the Event API: user events are fire-and-forget messages fanned out across the datacenter, optionally scoped to nodes, services or tags.

    Event::fire

    source
    async fn Event::fire(self : Event, name : String, payload : Bytes, options? : EventFireOptions, write_options? : WriteOptions) -> (UserEvent, WriteMeta) raise Refused

    Fire name with payload, scoped by options, returning the accepted event.

    Event::list

    source
    async fn Event::list(self : Event, options? : EventListOptions, query_options? : QueryOptions) -> (Array[UserEvent], QueryMeta) raise Refused

    List events, optionally only those named options.name.

    EventFireOptions

    source
    pub(all) struct EventFireOptions {
      node_filter : String?
      service_filter : String?
      tag_filter : String?
    }

    Scope filters for fire.

    EventListOptions

    source
    pub(all) struct EventListOptions {
      name : String?
    }

    List filters for list.

    Health

    source
    pub struct Health {
      client : Client
    }

    A handle to the Health API: checks and the healthy instances of a service, including blocking queries that watch a service for membership changes.

    Health::checks

    source
    async fn Health::checks(self : Health, service : String, options? : QueryOptions) -> (Array[HealthCheck], QueryMeta) raise Refused

    The checks belonging to service.

    Health::checks_in_state

    source
    async fn Health::checks_in_state(self : Health, state : String, options? : QueryOptions) -> (Array[HealthCheck], QueryMeta) raise Refused

    The checks in state (passing, warning or critical).

    Health::connect_service

    source
    async fn Health::connect_service(self : Health, service : String, passing? : Bool, options? : QueryOptions) -> (Array[ServiceEntry], QueryMeta) raise Refused

    Like service, but only instances reachable over the connect mesh.

    Health::node

    source
    async fn Health::node(self : Health, node : String, options? : QueryOptions) -> (Array[HealthCheck], QueryMeta) raise Refused

    The checks on node.

    Health::service

    source
    async fn Health::service(self : Health, service : String, passing? : Bool, options? : QueryOptions) -> (Array[ServiceEntry], QueryMeta) raise Refused

    The healthy instances of service; passing filters to passing instances only. A blocking query (QueryOptions.wait_index) watches the set change.

    Health::state

    source
    async fn Health::state(self : Health, state : String, options? : QueryOptions) -> (Array[HealthCheck], QueryMeta) raise Refused

    The checks in state (any of the three states).

    HealthCheck

    source
    pub(all) struct HealthCheck {
      node : String
      check_id : String
      name : String?
      status : String?
      notes : String?
      output : String?
      service_id : String?
      service_name : String?
      ns : String?
    }

    A check as reported by the health endpoints: its check_id, name, current status, and output.

    HealthService

    source
    pub(all) struct HealthService {
      id : String
      service : String
      address : String?
      tags : Array[String]
      meta : Map[String, String]?
      ns : String?
      partition : String?
      port : Int?
      weights : AgentWeights?
    }

    One instance of a service as returned by service and connect_service, paired with the node it runs on and its live checks.
    pub struct KV {
      client : Client
    }

    A handle to the KV API: the key/value store. Reads and writes are paired with blocking queries; compare-and-swap, acquire and release are what the locks and semaphores of moonconsul/concurrency are built from.

    KV::acquire

    source
    async fn KV::acquire(self : KV, pair : KVPair, options? : WriteOptions) -> (Bool, WriteMeta) raise Refused

    Acquire the lock on key for pair.session; succeed only when the key is unlocked or already held by that session.

    KV::cas

    source
    async fn KV::cas(self : KV, pair : KVPair, options? : WriteOptions) -> (Bool, WriteMeta) raise Refused

    Compare-and-swap: succeed only when pair.modify_index matches the stored index. The returned Bool is true on success.

    KV::delete

    source
    async fn KV::delete(self : KV, key : String, options? : WriteOptions) -> WriteMeta raise Refused

    Delete key.

    KV::delete_cas

    source
    async fn KV::delete_cas(self : KV, pair : KVPair, options? : WriteOptions) -> (Bool, WriteMeta) raise Refused

    Delete pair.key only if its index is still pair.modify_index. The returned Bool is true on success.

    KV::delete_tree

    source
    async fn KV::delete_tree(self : KV, prefix : String, options? : WriteOptions) -> WriteMeta raise Refused

    Delete every entry under prefix.

    KV::get

    source
    async fn KV::get(self : KV, key : String, options? : QueryOptions) -> (KVPair?, QueryMeta) raise Refused

    Read key, returning None when it does not exist.

    KV::keys

    source
    async fn KV::keys(self : KV, prefix : String, options? : QueryOptions) -> (Array[String], QueryMeta) raise Refused

    List only the keys under prefix (lighter than list).

    KV::list

    source
    async fn KV::list(self : KV, prefix : String, options? : QueryOptions) -> (Array[KVPair], QueryMeta) raise Refused

    List every entry under prefix.

    KV::put

    source
    async fn KV::put(self : KV, pair : KVPair, options? : WriteOptions) -> WriteMeta raise Refused

    Write pair; modify_index is ignored on a fresh write.

    KV::release

    source
    async fn KV::release(self : KV, pair : KVPair, options? : WriteOptions) -> (Bool, WriteMeta) raise Refused

    Release the lock on key held by pair.session; succeed only when that session holds it.

    KV::txn

    source
    async fn KV::txn(self : KV, ops : Array[KVTxnOp], options? : QueryOptions) -> (KVTxnResponse, QueryMeta) raise Refused

    Run ops as an atomic batch; results carries the reads, errors the failures.

    KVPair

    source
    pub(all) struct KVPair {
      key : String
      create_index : UInt64
      modify_index : UInt64
      lock_index : UInt64
      flags : UInt64
      value : Bytes
      session : String?
    }

    One key/value entry: create_index and modify_index are the indexes that gate blocking reads and CAS; lock_index, flags and session are used by the lock primitives.

    KVTxnError

    source
    pub(all) struct KVTxnError {
      op_index : Int
      message : String
    }

    A per-operation failure inside a transaction.

    KVTxnOp

    source
    pub(all) struct KVTxnOp {
      verb : KVTxnOpVerb
      key : String
      value : Bytes?
      index : UInt64?
      session : String?
      flags : UInt64?
    }

    One operation in a txn batch.

    KVTxnOpVerb

    source
    pub(all) enum KVTxnOpVerb {
      Set
      CAS
      Delete
      DeleteTree
      DeleteCAS
      Acquire
      Release
      Get
      GetKeys
      CheckSession
      CheckIndex
      CheckNotExists
      Lock
      Unlock
      Read
    }

    The verb of a transaction operation.

    KVTxnResponse

    source
    pub(all) struct KVTxnResponse {
      results : Array[KVPair]
      errors : Array[KVTxnError]?
    }

    The outcome of a txn: the results for the read verbs and the errors for any operation that failed.

    MeshConfigEntry

    source
    pub(all) struct MeshConfigEntry {
      name : String
      partition : String?
      transparent_proxy : MeshTransparentProxy?
    }

    Mesh-wide configuration.

    MeshTransparentProxy

    source
    pub(all) struct MeshTransparentProxy {
      mode : String?
    }

    Transparent-proxy settings for the mesh.

    Node

    source
    pub(all) struct Node {
      node : String
      address : String
      meta : Map[String, String]?
      ns : String?
      partition : String?
      tagged_addresses : Map[String, String]?
      create_index : UInt64?
      modify_index : UInt64?
      deregister_critical_service_after : String?
    }

    A Consul node: its node name, address, and free-form meta.

    PreparedQuery

    source
    pub struct PreparedQuery {
      client : Client
    }

    A handle to the Prepared Query API: named and templated service queries with failover, used as a stable service-discovery entry point.

    PreparedQuery::create

    source
    async fn PreparedQuery::create(self : PreparedQuery, def : PreparedQueryDefinition, options? : WriteOptions) -> (String, WriteMeta) raise Refused

    Create a query, returning its assigned id.

    PreparedQuery::delete

    source
    async fn PreparedQuery::delete(self : PreparedQuery, id : String, options? : WriteOptions) -> WriteMeta raise Refused

    Delete the query id.

    PreparedQuery::execute

    source
    async fn PreparedQuery::execute(self : PreparedQuery, id_or_name : String, params? : PreparedQueryExecuteParams, options? : QueryOptions) -> (PreparedQueryExecuteResponse, QueryMeta) raise Refused

    Execute the query named or identified by id_or_name.

    PreparedQuery::get

    source
    async fn PreparedQuery::get(self : PreparedQuery, id : String, options? : QueryOptions) -> (Array[PreparedQueryDefinition], QueryMeta) raise Refused

    Read the query id (returns it wrapped in an array, matching the API).

    PreparedQuery::list

    source

    List every query in the datacenter.

    PreparedQuery::update

    source
    async fn PreparedQuery::update(self : PreparedQuery, def : PreparedQueryDefinition, options? : WriteOptions) -> WriteMeta raise Refused

    Update an existing query.

    PreparedQueryDefinition

    source
    pub(all) struct PreparedQueryDefinition {
      id : String?
      name : String?
      token : String?
      ns : String?
      partition : String?
      service : ServiceQuery?
      dns : DNSQuery?
    }

    A prepared query definition: its id (assigned by Consul), name, token, and the service and dns blocks.

    PreparedQueryExecuteParams

    source
    pub(all) struct PreparedQueryExecuteParams {
      ns : String?
      near : String?
      limit : Int?
    }

    Parameters for execute: the datacenter to run in, the near node to sort by, and a limit on nodes returned.

    PreparedQueryExecuteResponse

    source
    pub(all) struct PreparedQueryExecuteResponse {
      service : String?
      datacenter : String?
      nodes : Array[ServiceEntry]?
    }

    The result of executing a query.

    QueryDatacenterOptions

    source
    pub(all) struct QueryDatacenterOptions {
      nearest : Bool?
      datacenters : Array[String]?
    }

    Failover policy: prefer the nearest datacenter, then fall back through datacenters.

    QueryMeta

    source
    pub(all) struct QueryMeta {
      last_index : UInt64
      last_hash : String?
      last_contact : Int64
      known_leader : Bool
      request_time : Int64
    }

    Metadata returned by every read. last_index is the index the agent last saw for the queried data and is the wait_index of the next blocking query; known_leader and last_contact describe leadership; request_time is the round-trip time in nanoseconds.

    QueryOptions

    source
    pub(all) struct QueryOptions {
      datacenter : String?
      ns : String?
      token : String?
      wait_index : UInt64?
      wait_hash : String?
      wait_time : Int64?
      consistency : ConsistencyMode
      near : String?
      filter : String?
      node_meta : Map[String, String]?
    }

    Options for a read. wait_index and wait_time drive a blocking query: the agent holds the request until the data's index advances past wait_index or wait_time nanoseconds elapse, then returns the new QueryMeta.last_index to feed the next blocking call. The agent's own endpoints block on a content hash instead, which is what wait_hash and QueryMeta.last_hash carry. datacenter, namespace and token override the client defaults for this call only.

    Request

    source
    pub(all) struct Request {
      verb : String
      url : String
      headers : Map[String, String]
      body : Bytes
    }

    A single HTTP request to a Consul agent: the verb, the full URL (scheme, address, path and query already joined), the request headers, and the body for writes. The transport owns the socket and the TLS configuration.

    Request::new

    source
    fn Request::new(verb : String, url : String) -> Request

    A request with no headers and an empty body.

    Request::new_full

    source
    fn Request::new_full(verb : String, url : String, headers : Map[String, String], body : Bytes) -> Request

    A request with headers and body.

    Response

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

    A Consul agent's HTTP response: the status code, the response headers (the blocking-query metadata rides on X-Consul-Index and its siblings), and the raw body bytes.

    Response::header

    source
    fn Response::header(self : Response, name : String) -> String?

    A response header by name, case-insensitively (HTTP header names are not case-sensitive; Consul spells them X-Consul-Index and friends).

    Response::new

    source
    fn Response::new(status : Int, body : Bytes) -> Response

    A response carrying status and body, with no headers.

    Response::new_full

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

    A response carrying status, headers and body.

    ServiceDefaultConfigEntry

    source
    pub(all) struct ServiceDefaultConfigEntry {
      name : String
      ns : String?
      partition : String?
      protocol : String?
      mesh_gateway : ServiceMeshGateway?
    }

    Default protocol, mesh and per-service settings.

    ServiceEntry

    source
    pub(all) struct ServiceEntry {
      node : Node
      service : HealthService?
      checks : Array[HealthCheck]
    }

    A healthy service instance: the node it runs on, the service instance, and its checks.

    ServiceMeshGateway

    source
    pub(all) struct ServiceMeshGateway {
      mode : String?
    }

    A service's mesh-gateway mode.

    ServiceQuery

    source
    pub(all) struct ServiceQuery {
      service : String
      ns : String?
      tags_any : Array[String]?
      only_passing : Bool?
      node_type : String?
      failover : QueryDatacenterOptions?
    }

    The service a query targets, with tag and health criteria and failover.

    ServiceResolverConfigEntry

    source
    pub(all) struct ServiceResolverConfigEntry {
      name : String
      ns : String?
      partition : String?
      datacenter : String?
      service : String?
      failover : QueryDatacenterOptions?
      redirect : String?
    }

    How a service resolves to healthy instances, with failover.

    ServiceRoute

    source
    pub(all) struct ServiceRoute {
      matcher : ServiceRouteMatch?
      destination : ServiceRouteDestination?
    }

    One routing match/rewrite rule.

    ServiceRouteDestination

    source
    pub(all) struct ServiceRouteDestination {
      service : String?
      ns : String?
    }

    The destination half of a route.

    ServiceRouteHTTPMatch

    source
    pub(all) struct ServiceRouteHTTPMatch {
      path : String?
      prefix : String?
      regex : String?
    }

    HTTP match fields.

    ServiceRouteMatch

    source
    pub(all) struct ServiceRouteMatch {
      http : ServiceRouteHTTPMatch?
    }

    The match half of a route.

    ServiceRouterConfigEntry

    source
    pub(all) struct ServiceRouterConfigEntry {
      name : String
      ns : String?
      partition : String?
      routes : Array[ServiceRoute]?
    }

    Layer-7 routing rules for a service.

    ServiceSplit

    source
    pub(all) struct ServiceSplit {
      weight : Double
      service : String?
      ns : String?
    }

    One weighted destination in a split.

    ServiceSplitterConfigEntry

    source
    pub(all) struct ServiceSplitterConfigEntry {
      name : String
      ns : String?
      partition : String?
      splits : Array[ServiceSplit]?
    }

    Weighted traffic split for a service.

    Session

    source
    pub struct Session {
      client : Client
    }

    A handle to the Session API: sessions are ephemeral leases, bound to a set of checks, that back locks and semaphores. moonconsul/concurrency keeps one alive. When a session's checks fail or its TTL lapses, its held keys are released.

    Session::create

    source
    async fn Session::create(self : Session, entry? : SessionEntry, options? : WriteOptions) -> (SessionEntry, WriteMeta) raise Refused

    Create a session from entry; the returned entry carries the assigned id.

    Session::destroy

    source
    async fn Session::destroy(self : Session, id : String, options? : WriteOptions) -> WriteMeta raise Refused

    Destroy id, releasing everything it holds.

    Session::info

    source
    async fn Session::info(self : Session, id : String, options? : QueryOptions) -> (SessionEntry?, QueryMeta) raise Refused

    Read one session by id.

    Session::list

    source
    async fn Session::list(self : Session, options? : QueryOptions) -> (Array[SessionEntry], QueryMeta) raise Refused

    Every session in the datacenter.

    Session::node

    source
    async fn Session::node(self : Session, node : String, options? : QueryOptions) -> (Array[SessionEntry], QueryMeta) raise Refused

    The sessions active on node.

    Session::renew

    source
    async fn Session::renew(self : Session, id : String, options? : WriteOptions) -> (SessionEntry?, WriteMeta) raise Refused

    Renew id, returning the refreshed entry (or None if it expired).

    SessionBehavior

    source
    pub(all) enum SessionBehavior {
      Release
      Delete
    }

    What happens to a session's held keys when it is invalidated: Release frees them, Delete removes them.

    SessionEntry

    source
    pub(all) struct SessionEntry {
      id : String?
      name : String?
      node : String?
      checks : Array[String]?
      lock_delay : Int64?
      behavior : SessionBehavior?
      ttl : String?
    }

    A session: its id (assigned by Consul), the checks that keep it alive, the lock_delay before a key can be locked again after the session dies, in nanoseconds (Consul reads a value under 1000 as seconds), the behavior on invalidation, and the ttl that bounds its life without a renewal.

    Status

    source
    pub struct Status {
      client : Client
    }

    A handle to the Status API: the cluster's leader and its raft peer set.

    Status::leader

    source
    async fn Status::leader(self : Status, options? : QueryOptions) -> (String, QueryMeta) raise Refused

    The address of the Raft leader, or empty when none is elected.

    Status::peers

    source
    async fn Status::peers(self : Status, options? : QueryOptions) -> (Array[String], QueryMeta) raise Refused

    The Raft peer addresses of the cluster.

    TlsConfig

    source
    pub(all) struct TlsConfig {
      ca_file : String?
      cert_file : String?
      key_file : String?
      insecure_skip_verify : Bool
    }

    TLS settings for an HTTPS agent. The three file paths point at a CA bundle, a client certificate, and its key; insecure_skip_verify turns certificate checking off and is for development against a self-signed agent only.

    UserEvent

    source
    pub(all) struct UserEvent {
      id : String
      name : String
      payload : Bytes?
      node_filter : String?
      service_filter : String?
      tag_filter : String?
      version : Int?
      ltime : Int64?
    }

    A user event as fired and as listed back.

    WatchKind

    source
    pub(all) enum WatchKind {
      Key(String)
      KeyPrefix(String)
      Services
      Nodes
      Service(String, passing~ : Bool)
      Checks(String)
      State(String)
      Event(String)
      ConnectRoots
      ConnectLeaf(String)
      AgentService(String)
    }

    What a blocking read can follow, in the words of Consul's own watch types.

    WriteMeta

    source
    pub(all) struct WriteMeta {
      request_time : Int64
    }

    Metadata returned by every write: request_time is the round-trip time in nanoseconds.

    WriteOptions

    source
    pub(all) struct WriteOptions {
      datacenter : String?
      ns : String?
      token : String?
    }

    Options for a write: the datacenter and namespace to target and the ACL token to use, overriding the client defaults for this call only.

    config_with_address

    source
    fn config_with_address(address : String) -> Config

    A configuration targeting address, with the remaining fields at their defaults.

    default_config

    source
    let default_config : Config

    The default configuration: http://127.0.0.1:8500, no datacenter, namespace or token, a default-consistency read, and no transport override.

    default_event_fire_options

    source
    let default_event_fire_options : EventFireOptions

    No scope filter.

    default_event_list_options

    source
    let default_event_list_options : EventListOptions

    List every event.

    default_prepared_query_execute_params

    source
    let default_prepared_query_execute_params : PreparedQueryExecuteParams

    No execution parameters.

    default_query_options

    source
    let default_query_options : QueryOptions

    The default read options: no overrides, a default-consistency non-blocking read with no wait.

    default_service_check

    source
    let default_service_check : AgentServiceCheck

    A check with nothing set, to update the fields a check needs.

    default_service_registration

    source
    let default_service_registration : AgentServiceRegistration

    A registration with nothing set but an empty name, to update the fields a service needs.

    default_session_entry

    source
    let default_session_entry : SessionEntry

    The default session: no id, the default checks, and Consul's default lock delay and TTL.

    default_tls

    source
    let default_tls : TlsConfig

    The default TLS settings: no client certificates and verification on.

    default_write_options

    source
    let default_write_options : WriteOptions

    The default write options: no overrides.

    empty_query_meta

    source
    fn empty_query_meta() -> QueryMeta

    A zeroed QueryMeta, used where a call fails before a response is read.

    empty_write_meta

    source
    fn empty_write_meta() -> WriteMeta

    A zeroed WriteMeta.

    jarray

    source
    fn jarray(m : Map[String, Json], key : String) -> Array[Json]

    The key value as an array, or [] when absent or not an array.

    jbool_opt

    source
    fn jbool_opt(m : Map[String, Json], key : String) -> Bool?

    The key value as a bool, or None.

    jbytes_b64_opt

    source
    fn jbytes_b64_opt(m : Map[String, Json], key : String) -> Bytes?

    The key value as bytes, base64-decoded (Consul's encoding for binary fields), or None.

    jdouble_opt

    source
    fn jdouble_opt(m : Map[String, Json], key : String) -> Double?

    The key value as a Double, or None.

    ji32

    source
    fn ji32(m : Map[String, Json], key : String) -> Int

    The key value as an Int32, or 0 when absent or not a number.

    ji32_opt

    source
    fn ji32_opt(m : Map[String, Json], key : String) -> Int?

    The key value as an Int32, or None.

    ji64

    source
    fn ji64(m : Map[String, Json], key : String) -> Int64

    The key value as an Int64, or 0L when absent or not a number.

    ji64_opt

    source
    fn ji64_opt(m : Map[String, Json], key : String) -> Int64?

    The key value as an Int64, or None.

    jmap_opt

    source
    fn jmap_opt(m : Map[String, Json], key : String) -> Map[String, String]?

    The key value as a String map, or None.

    jobj

    source
    fn jobj() -> Map[String, Json]

    An empty JSON object to fill with put_*.

    json_array

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

    The array behind a Json, or an empty array when it is not an array.

    json_bool

    source
    fn json_bool(j : Json) -> Bool

    A Json as a bool: true only for True.

    json_map

    source
    fn json_map(j : Json) -> Map[String, Json]

    The object map behind a Json, or an empty map when it is not an object.

    json_null

    source
    fn json_null() -> Json

    The JSON null, built through Unit's ToJson (the Null variant is read-only and cannot be constructed directly).

    jstr

    source
    fn jstr(m : Map[String, Json], key : String) -> String

    The key value as a string, or "" when absent or not a string.

    jstr_array_opt

    source
    fn jstr_array_opt(m : Map[String, Json], key : String) -> Array[String]?

    The key value as a string array, or None.

    jstr_opt

    source
    fn jstr_opt(m : Map[String, Json], key : String) -> String?

    The key value as a string, or None.

    ju64

    source
    fn ju64(m : Map[String, Json], key : String) -> UInt64

    The key value as a UInt64, or 0. A Double cannot hold a large one, so it comes from the number's text.

    ju64_opt

    source
    fn ju64_opt(m : Map[String, Json], key : String) -> UInt64?

    The key value as a UInt64, or None.

    map_to_json

    source
    fn map_to_json(m : Map[String, String]) -> Json

    A String map as a JSON object.

    node_of

    source
    fn node_of(j : Json) -> Node

    A Node from its JSON object.

    parse_i64

    source
    fn parse_i64(s : StringView) -> Int64

    The leading decimal integer of s, or 0.

    parse_u64

    source
    fn parse_u64(s : StringView) -> UInt64

    Parse a decimal Int64 from a string, returning 0L on anything non-numeric.

    put_bool

    source
    fn put_bool(m : Map[String, Json], key : String, v : Bool?) -> Unit

    Set a bool field when Some.

    put_i32

    source
    fn put_i32(m : Map[String, Json], key : String, v : Int?) -> Unit

    Set an Int32 field when Some.

    put_i64

    source
    fn put_i64(m : Map[String, Json], key : String, v : Int64?) -> Unit

    Set an Int64 field when Some.

    put_json

    source
    fn put_json(m : Map[String, Json], key : String, v : Json?) -> Unit

    Set a nested JSON value when Some.

    put_str

    source
    fn put_str(m : Map[String, Json], key : String, v : String?) -> Unit

    Set m[key] when v is Some, leaving it out when None.

    put_str_array

    source
    fn put_str_array(m : Map[String, Json], key : String, v : Array[String]?) -> Unit

    Set a string-array field when Some.

    put_u64

    source
    fn put_u64(m : Map[String, Json], key : String, v : UInt64?) -> Unit

    Set a UInt64 field when Some, with its text so that a large one survives.

    url_encode

    source
    fn url_encode(s : String) -> String

    Percent-encode a query component, keeping only the RFC 3986 unreserved set.

    Source Files

    Powered by MoonBit

    Site sourceReport issueModulesSkillsBuild queueStatistics

    © 2026 mooncakes.io