caching connectors¶

Cache integrations. After the 2026-06-19 Helix-first cleanup, the lineup is: two Go-native in-process / distributed-read-through caches (ristretto, groupcache), three Java-ecosystem distributed caches kept for migration users (hazelcast, ignite, infinispan), and the binary-protocol memcached. The caffeine and ehcache shims were dropped — they had no JVM cache running under the hood, just a sync.Map wearing a Java name. For high-volume cache traffic you'll usually want the dedicated redis:// component (RESP) instead.

Connectors in this category¶

Deep notes per connector¶

ristretto://¶

Source: pkg/connector/connectors/caching/ristretto.go · SDK: github.com/dgraph-io/ristretto/v2

Helix-native recommended in-process cache. TinyLFU admission policy with cost-based eviction (not LRU). Default values fit small services; tune max_cost (bytes) and num_counters (~10× expected key count) for production.

Ops: get, put (optional ttl + cost headers), remove, clear, stats.

connectors:
  fast-cache:
    type: ristretto
    config:
      num_counters: 100000     # 10x expected items
      max_cost: 67108864       # 64 MiB
      default_ttl_seconds: 300

routes:
  - id: cache-write
    from: direct://write
    steps:
      - set-header: { name: operation, constant: put }
      - set-header: { name: key,       constant: "user-42" }
      - set-header: { name: ttl,       constant: "60" }
      - set-body:   { constant: '{"name":"alice"}' }
      - to: connector://fast-cache/send

groupcache://¶

Source: pkg/connector/connectors/caching/groupcache.go · SDK: github.com/mailgun/groupcache/v2

Maintained v2 fork of golang/groupcache that adds Set, Remove, and TTL-style expiry (the original is read-through-only). Runs in-process by default; set self, peers, and listen_addr to enable HTTP peer fan-out (each node both serves and fetches across the pool).

Ops: get, put (optional ttl header), remove, stats.

connectors:
  shared-cache:
    type: groupcache
    config:
      name: helix-shared
      max_bytes: 67108864
      # Distributed mode (uncomment for cluster):
      # self: http://10.0.0.1:8080
      # peers: http://10.0.0.1:8080,http://10.0.0.2:8080,http://10.0.0.3:8080
      # listen_addr: ":8080"

hazelcast://¶

Source: pkg/connector/connectors/caching/hazelcast.go · SDK: github.com/hazelcast/hazelcast-go-client v1.6 (Hazelcast's official Go client)

Distributed IMap operations against a Hazelcast cluster. Cluster discovery, smart routing, and binary serialization all handled by the official client. Auth is optional (cluster name + credentials).

Ops: get, put, remove, contains-key, size, clear, get-all (CSV keys header or []string body), put-all (map body).

connectors:
  hz:
    type: hazelcast
    config:
      cluster_name: dev
      addresses:    "127.0.0.1:5701,127.0.0.1:5702"
      map_name:     helix-test

routes:
  - id: hz-put-all
    from: direct://hz-put-all
    steps:
      - set-header: { name: operation, constant: put-all }
      - set-body:
          constant:
            user-1: '{"name":"alice"}'
            user-2: '{"name":"bob"}'
      - to: connector://hz/send

ignite://¶

Source: pkg/connector/connectors/caching/ignite.go · SDK: Apache Ignite REST API (Apache Ignite ships no first-party Go client)

Ignite REST is part of the Ignite server itself (load OPTION_LIBS=ignite-rest-http). The connector wraps every documented cmd=… operation it implements. Default port 8080.

Ops: create-cache (idempotent getorcreate), get, put, remove, contains-key, size, clear, query (Ignite SQL via sql header).

connectors:
  ig:
    type: ignite
    config:
      server_url: http://127.0.0.1:8080
      cache_name: helix-test

routes:
  - id: ignite-bootstrap
    from: direct://ignite-bootstrap
    steps:
      - set-header: { name: operation, constant: create-cache }
      - to: connector://ig/send

  - id: ignite-query
    from: direct://ignite-query
    steps:
      - set-header: { name: operation, constant: query }
      - set-header: { name: sql,       constant: "SELECT * FROM helix-test LIMIT 10" }
      - to: connector://ig/send

infinispan://¶

Source: pkg/connector/connectors/caching/infinispan.go · SDK: Infinispan REST v2 (no Go SDK published)

Infinispan / Red Hat Data Grid REST endpoint. The server ships with DIGEST as its default REST auth mechanism, not Basic — the connector handles both via the auth_mode field (default digest; uses icholy/digest Transport for the challenge / response).

Caches must be created with explicit value media-type when JSON is the payload (Infinispan's default cache config has media-type: application/unknown which rejects typed PUTs); see the caching-batch.md audit doc for the create-cache JSON body.

Ops: get, put, remove, clear, stats, query (Ickle query via query header or string body).

connectors:
  isp:
    type: infinispan
    config:
      server_url: http://127.0.0.1:11222
      cache_name: helix-test
      username:   admin
      password:   password
      auth_mode:  digest        # or 'basic' / 'none'

memcached://¶

Source: pkg/connector/connectors/caching/memcached.go · SDK: bradfitz/gomemcache

Pure-Go memcached binary protocol; supports CAS, TTL, multi-get, and atomic increment / decrement. servers accepts a comma-separated list to fan out across cluster nodes.

connectors:
  mc:
    type: memcached
    config:
      servers: "mc-1:11211,mc-2:11211,mc-3:11211"
      timeout: 5s

Runnable bundle¶

A complete, validatable bundle that exercises every connector in this category lives at examples/esb/caching.yaml:

bin/helix validate examples/esb/caching.yaml
# Validation passed: 0 workflow(s), 5 connector(s), 0 starlang block(s)

See also¶

• Connector SDK guide — adding a new connector.
• redis:// component — full RESP protocol via go-redis/v9 when you need a real KV store backed by Redis.