#moonetcd

#Layout

#Install

moon add moonbitstack/moonetcd

#Quick start

async fn main {
  let config = @moonetcd.ClientConfig::{
    ..@moonetcd.default_client_config,
    endpoints: ["127.0.0.1:2379"],
  }
  let client = @client.Client::connect(config)

  let _ = client.kv().put(b"/greeting", b"hello")
  let resp = client.kv().get(b"/greeting")
  for item in resp.kvs {
    println("value = \{@utf8.decode_lossy(item.value[:])}")
  }
  client.close()
}

let client = @client.Client::connect_gateway(config)

#Two transports

curl -s -X POST http://127.0.0.1:2379/v3/kv/range -d '{"key":"L2dyZWV0aW5n"}'

• A watch is cancelled by closing its stream, which is how the gateway ends it.
• A keep-alive is one request and one acknowledgement, so KeepAlive::next() returns what the last keep_alive(id) was told rather than a stream of autonomous renewals.

#API surface

#KV — client.kv()

#Watch — client.watch()

@async.with_task_group <| g => {
  let chan = client.watch().watch_create(
    g,
    @moonetcd.WatchCreateRequest::{ ..@moonetcd.WatchCreateRequest::empty(), key: b"/watched" },
  )
  match chan.next() {
    Some(resp) => println("revision \{resp.header.revision}, \{resp.events.length()} event(s)")
    None => println("watch ended")
  }
  chan.cancel()
}

#Lease — client.lease()

#Cluster — client.cluster()

#Auth — client.auth()

#Maintenance — client.maintenance()

#Lock and Election — client.lock() / client.election()

#Concurrency helpers

import {
  "moonbitstack/moonetcd/client",
  "moonbitstack/moonetcd/concurrency",
}

let session = @concurrency.Session::new(client, 30L)   // grants a lease
let mutex = @concurrency.Mutex::new(client, session, b"/my-lock")
mutex.lock()
// critical section
mutex.unlock()
session.close()                                         // revokes the lease

• Session grants a lease and revokes it on close; both are plain unary calls. For a long-lived session, open session.keep_alive(task_group) and drive the returned KeepAlive so the lease does not expire.
• Mutex is a distributed lock over v3lock, held on the session's lease, so it is released automatically if the holder dies.
• Election campaigns, proclaims, and resigns over v3election.

#Service discovery

let registry = @sd.Registry::new(client)
group.spawn_bg(() => @moonsd.hold(registry, "greeter", @moonsd.Endpoint::new("10.0.0.1", 12000)))
let endpoints = registry.resolve("greeter")

#Errors

• Refused(Status) — a non-OK gRPC status, carrying the code and message.
• Compacted(revision) — the requested revision was compacted (etcd's FAILED_PRECONDITION).
• FutureRev(revision) — the requested revision is in the future (etcd's OUT_OF_RANGE).

#Connection

#Examples

moon run --target native src/examples/00-connect   # dial and print member status
moon run --target native src/examples/01-kv        # put / get / prefix scan / delete
moon run --target native src/examples/02-watch     # watch a key and read the event
moon run --target native src/examples/03-lease     # grant a lease, attach a key, revoke
moon run --target native src/examples/04-txn       # compare-and-swap with a transaction
moon run --target native src/examples/05-lock      # distributed mutex over a session
moon run --target native src/examples/06-gateway   # the same calls over HTTP/JSON

#Building and testing

moon check --target all --deny-warn
moon build --target all
moon test  --target all
moon info  --target all

#Notes

• The transport is h2c (HTTP/2 over plaintext) through moonrpc. The TlsConfig fields are present so callers can configure TLS, but they are honoured only once TLS reaches the transport.
• Maintenance::snapshot() buffers the whole stream; a very large snapshot is held in memory.
• Watch and Lease KeepAlive use a pull model (next() returns one response at a time). Open them inside @async.with_task_group so the connection's read pump runs.
• The gateway transport keeps its unary connections for reuse and dials again when one has been closed under it; a stream owns its connection until it ends.

#License