dflockd

dflockd (Go)

• dflockd (Go)
  • Build
  • Run
  • Configuration
  • Tests
  • Protocol
    • Commands
    • Example session with netcat
    • Two-phase example
  • Client Libraries - Go client quick start

Go implementation of the dflockd distributed lock server.

Read the docs here

Build

go build -o dflockd ./cmd/dflockd

Run

./dflockd

The server listens on 127.0.0.1:6388 by default.

Configuration

All settings can be passed as CLI flags or environment variables. Environment variables take precedence.

Example:

./dflockd --port 7000 --max-locks 512
# or
DFLOCKD_PORT=7000 DFLOCKD_MAX_LOCKS=512 ./dflockd

TLS

To enable TLS encryption, provide both a certificate and private key:

./dflockd --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem
# or
DFLOCKD_TLS_CERT=/path/to/cert.pem DFLOCKD_TLS_KEY=/path/to/key.pem ./dflockd

Both --tls-cert and --tls-key must be provided together. When TLS is enabled, clients must connect using TLS:

l := &client.Lock{
    Key:       "my-resource",
    Servers:   []string{"127.0.0.1:6388"},
    TLSConfig: &tls.Config{},  // configure CA, etc.
}

Authentication

To require token-based authentication, set a shared secret:

./dflockd --auth-token my-secret-token
# or load from a file (avoids leaking the secret in the process list):
./dflockd --auth-token-file /run/secrets/dflockd-token
# or via environment variables:
DFLOCKD_AUTH_TOKEN=my-secret-token ./dflockd

When set, every client must send an auth command as its first message. If unset, no authentication is required (fully backward compatible).

l := &client.Lock{
    Key:       "my-resource",
    Servers:   []string{"127.0.0.1:6388"},
    AuthToken: "my-secret-token",
}

Use together with TLS to protect the token in transit.

Benchmarking

A built-in benchmark tool measures lock acquire/release latency and throughput under concurrent load:

go run ./cmd/bench [flags]

Example:

# taken from macbook air m1 benchmark:
$ bench: 100 workers x 500 rounds (key_prefix="bench", conns/worker=1)

  total ops : 50000
  wall time : 0.575s
  throughput: 86922.7 ops/s

  mean      : 1.116 ms
  min       : 0.037 ms
  max       : 21.251 ms
  p50       : 0.895 ms
  p99       : 5.112 ms
  stdev     : 0.942 ms

Each worker uses a unique randomized key, so all workers run in parallel without contending. To benchmark contended locks, use the same --key value with --workers 1 and increase --rounds.

Tests

go test ./... -v

Protocol

The wire protocol is identical to the Python server. Each request is 3 newline-terminated UTF-8 lines (command\nkey\narg\n). Each response is a single newline-terminated line.

Commands

Lock (l) — acquire a lock, blocking up to timeout_s seconds.

l\n<key>\n<timeout_s> [<lease_ttl_s>]\n

Response: ok <token> <lease_ttl>\n | timeout\n | error_max_locks\n | error_max_waiters\n

Release (r) — release a held lock.

r\n<key>\n<token>\n

Response: ok\n | error\n

Renew (n) — renew the lease on a held lock.

n\n<key>\n<token> [<lease_ttl_s>]\n

Response: ok <seconds_remaining>\n | error\n

Enqueue (e) — join the lock queue without blocking (two-phase step 1).

e\n<key>\n[<lease_ttl_s>]\n

Response: acquired <token> <lease_ttl>\n | queued\n | error_max_locks\n | error_max_waiters\n

Wait (w) — block until the enqueued lock is granted (two-phase step 2).

w\n<key>\n<timeout_s>\n

Response: ok <token> <lease_ttl>\n | timeout\n | error\n

Semaphore Acquire (sl) — acquire a semaphore slot, blocking up to timeout_s seconds.

sl\n<key>\n<timeout_s> <limit> [<lease_ttl_s>]\n

Response: ok <token> <lease_ttl>\n | timeout\n | error_max_locks\n | error_limit_mismatch\n | error_max_waiters\n

Semaphore Release (sr) — release a held semaphore slot.

sr\n<key>\n<token>\n

Response: ok\n | error\n

Semaphore Renew (sn) — renew the lease on a held semaphore slot.

sn\n<key>\n<token> [<lease_ttl_s>]\n

Response: ok <seconds_remaining>\n | error\n

Semaphore Enqueue (se) — join the semaphore queue without blocking (two-phase step 1).

se\n<key>\n<limit> [<lease_ttl_s>]\n

Response: acquired <token> <lease_ttl>\n | queued\n | error_max_locks\n | error_limit_mismatch\n | error_max_waiters\n

Semaphore Wait (sw) — block until the enqueued semaphore slot is granted (two-phase step 2).

sw\n<key>\n<timeout_s>\n

Response: ok <token> <lease_ttl>\n | timeout\n | error\n

Stats (stats) — query server runtime state (connections, locks, semaphores, idle entries).

stats\n_\n\n

Response: ok <json>\n

The JSON payload includes connections, locks, semaphores, idle_locks, and idle_semaphores. Key and arg lines are read but ignored.

Example session with netcat

# Terminal 1: start the server
./dflockd

# Terminal 2: acquire and release a lock
$ nc localhost 6388
l
mykey
10
ok a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 33
r
mykey
a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
ok

Two-phase example

$ nc localhost 6388
e
mykey

acquired a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 33
w
mykey
10
ok a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 33
r
mykey
a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
ok

Semaphore example

$ nc localhost 6388
sl
worker-pool
10 3
ok a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 33
sr
worker-pool
a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
ok

Stats example

$ nc localhost 6388
stats
_

ok {"connections":1,"locks":[],"semaphores":[],"idle_locks":[],"idle_semaphores":[]}

Go semaphore quick start

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/mtingers/dflockd/client"
)

func main() {
    s := &client.Semaphore{
        Key:            "worker-pool",
        Limit:          3,
        AcquireTimeout: 10 * time.Second,
        Servers:        []string{"127.0.0.1:6388"},
    }

    ok, err := s.Acquire(context.Background())
    if err != nil {
        log.Fatal(err)
    }
    if !ok {
        log.Fatal("timed out waiting for semaphore slot")
    }
    defer s.Release(context.Background())

    fmt.Println("semaphore slot acquired, doing work...")
}

Client Libraries

• Go (in-repo) — go get github.com/mtingers/dflockd/client (docs)
• Python client
• TypeScript client

Go client quick start

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/mtingers/dflockd/client"
)

func main() {
    l := &client.Lock{
        Key:            "my-resource",
        AcquireTimeout: 10 * time.Second,
        Servers:        []string{"127.0.0.1:6388"},
    }

    ok, err := l.Acquire(context.Background())
    if err != nil {
        log.Fatal(err)
    }
    if !ok {
        log.Fatal("timed out waiting for lock")
    }
    defer l.Release(context.Background())

    fmt.Println("lock acquired, doing work...")
}

The Lock type handles server selection (optional sharding), lease renewal in the background, and context cancellation. For lower-level control, use client.Dial with client.Acquire/client.Release/client.Renew directly.