Infinispan Server includes an endpoint that implements the RESP3 protocol and allows you to interact with remote caches using Redis clients.

1. Infinispan RESP endpoint

The RESP endpoint is enabled by default on the single-port endpoint. Redis client connections will automatically be detected and routed to the internal connector. The RESP endpoint works with:

  • Standalone Infinispan Server deployments, exactly like standalone Redis, where each server instance runs independently of each other.

  • Clustered Infinispan Server deployments, where server instances replicate or distribute data between each other. Clustered deployments provides clients with failover capabilities.

Prerequisites
  • Install Infinispan Server.

Procedure
  1. Create a user

Verification

When you start Infinispan Server check for the following log message:

[org.infinispan.SERVER] ISPN080018: Started connector Resp (internal)

You can now connect to the RESP endpoint with a Redis client. For example, with the Redis CLI you can do the following to add an entry to the cache:

redis-cli -p 11222 --user username --pass password
127.0.0.1:11222> SET k v
OK
127.0.0.1:11222> GET k
"v"
127.0.0.1:11222> quit

1.1. Configuring caches for the RESP endpoint

The RESP endpoint automatically configures and starts a respCache cache. This cache has the following configuration:

  • local-cache or distributed-cache depending on the Infinispan Server clustering mode.

  • application/octet-stream encoding for both keys and values.

  • RESPHashFunctionPartitioner hash partitioner, which supports the CRC16 hashing used by Redis clients

Explicit configuration for cache

It is possible to supply a custom configuration for the cache, as long as it does not violate the requirements of the RESP connector, in which case the server will raise an exception and will not start. Main constraints are:

  • hash partitioning function must be org.infinispan.distribution.ch.impl.RESPHashFunctionPartitioner.

  • key encoding must be application/octet-stream.

Example of explicit cache configuration follows.

XML
<distributed-cache name="respCache" aliases="0" owners="2"
                   key-partitioner="org.infinispan.distribution.ch.impl.RESPHashFunctionPartitioner"
                   mode="SYNC" remote-timeout="17500" statistics="true">
	<encoding media-type="application/octet-stream"/>
</distributed-cache>
JSON
{
   "respCache": {
     "distributed-cache": {
       "aliases": ["0"],
       "owners": "2",
       "key-partitioner": "org.infinispan.distribution.ch.impl.RESPHashFunctionPartitioner",
       "mode": "SYNC",
       "statistics": true,
       "encoding": {
         "media-type": "application/octet-stream"
       }
     }
   }
 }
YAML
respCache:
  distributedCache:
    aliases:
      - "0"
    owners: "2"
    keyPartitioner: "org.infinispan.distribution.ch.impl.RESPHashFunctionPartitioner"
    mode: "SYNC"
    statistics: "true"
    encoding:
      mediaType: "application/octet-stream"

Configure your cache value encoding with Protobuf encoding if you want to view cache entries in the Infinispan Console (value media-type="application/x-protostream").

Explicit RESP endpoint configuration

If the implicit configuration used by the single-port endpoint does not fit your needs, explicit configuration is available.

XML
<endpoints>
  <endpoint socket-binding="default" security-realm="default">
    <resp-connector cache="mycache" />
    <hotrod-connector />
    <rest-connector/>
  </endpoint>
</endpoints>
JSON
{
  "server": {
    "endpoints": {
      "endpoint": {
        "socket-binding": "default",
        "security-realm": "default",
        "resp-connector": {
          "cache": "mycache"
        },
        "hotrod-connector": {},
        "rest-connector": {}
      }
    }
  }
}
YAML
server:
  endpoints:
    endpoint:
      socketBinding: "default"
      securityRealm: "default"
      respConnector:
        cache: "mycache"
      hotrodConnector: ~
      restConnector: ~

Clustered configuration

Infinispan is a horizontally scalable Resp-compatible server with high availability capabilities. Infinispan provides clustering mechanisms with automatic failover detection and membership discovery by default. Topology changes are handled automatically, and adding or removing nodes to the cluster is a streamlined process that automatically redistributes entries between nodes without downtime. The cluster is homogeneous, where nodes are the primary and the backup owners of entries, guaranteeing that entries are available even in case of server failures.

Backed by a consistent hash, compatible with the hash-slot algorithm in Resp clients, entries are distributed across cluster members. Infinispan automatically redirects requests to the proper entry owner. As a result, hash tags in keys and the -MOVED error response for requests are not required even for multi-key operations accessing keys with different owners.

Infinispan allows multiple logical databases with the SELECT command in clustering mode.

1.2. Mapping caches to Redis logical databases

Use the cache aliases configuration attributes to map caches to Redis logical databases. The default respCache is mapped to logical database 0.

Infinispan can use multiple logical databases even in clustered mode, as opposed to Redis which only supports database 0 when using Redis Cluster.

1.3. Differences between Infinispan and Redis implementation

Infinispan provides different guarantees compared to Redis for some functionalities. This chapter summarizes the differences and, when possible, alternative configurations for a similar behavior.

1.3.1. Protocol version

Infinispan only supports RESP version 3. Attempting to use version 2, will result in an error.

1.3.2. Isolation

Redis utilizes a single thread to handle user requests, which provides serializable isolation and atomic behavior for multi-key requests. Infinispan provides a relaxed isolation level, which is configurable. Concurrent requests might perceive a partial result for commands that access multiple keys, such as MSET, where only a subset of the keys were inserted in the cache before the operation finishes.

The only alternative in Infinispan for an atomic behavior is to submit multi-keys operations within a MULTI…EXEC block. However, this requires configuring the default cache with transactional capabilities.

Infinispan does not provide serializable transactions. See the cache configuration guide for more information.

1.3.3. Transactions

Applications utilizing the MULTI…EXEC commands should update the default cache configuration to enable transactional capabilities. Transactions in Redis do not have the concept of rollback to revert in case of failures. Infinispan provides ACID transactions and rollback in case of failures. Additionally, the transactions are distributed in cluster mode and can operate across many slots.

The recommended configuration utilizes PESSIMISTIC locking and transaction mode different from NONE. See the cache configuration guide for more information.

1.3.4. Lua Scripts

Lua scripts executed by Infinispan serialize responses using the RESP3 protocol. This is equivalent to invoking redis.setresp(3) in every script.

1.4. Redis commands

The Infinispan RESP endpoint implements the following Redis commands, grouped by category.

1.4.1. ACL Categories

Each command shows its ACL categories which control access permissions:

  • Data type: @string, @hash, @list, @set, @sortedset, @bitmap, @hyperloglog, @stream, @pubsub, @json, @bloom, @cuckoo, @cms, @topk, @tdigest

  • Operation: @read, @write, @keyspace, @admin, @dangerous

  • Performance: @fast, @slow, @blocking

  • Other: @connection, @transaction, @scripting

1.4.2. String Commands

Command ACL Description

APPEND

@write @fast

BITCOUNT

@read @fast

BITOP

@write @slow

BITPOS

@read @fast

DECR

@write @fast

DECRBY

@write @fast

GET

@read @fast

GETBIT

@read @fast

GETDEL

@write @fast

GETEX

@write @fast

GETRANGE

@read @slow

GETSET

@write @fast

This command is deprecated. Use the SET command with the appropriate flags instead.

INCR

@write @fast

INCRBY

@write @fast

INCRBYFLOAT

@write @fast

LCS

@read @slow

MGET

@read @fast

MSET

@write @slow

MSETNX

@write @slow

PSETEX

@write @slow

This command is deprecated. Use the SET command with the appropriate flags.

SET

@write @slow

SETBIT

@write @slow

SETEX

@write @slow

This command is deprecated. Use the SET command with the appropriate flags instead.

SETNX

@write @fast

This command is deprecated. Use the SET command with the appropriate flags instead.

SETRANGE

@write @slow

STRALGO

@read @slow

STRLEN

@read @fast

SUBSTR

@read @slow

This command is deprecated. Use the GETRANGE command instead.

1.4.3. Hash Commands

Command ACL Description

HDEL

@write @fast

HEXISTS

@read @fast

HGET

@read @fast

HGETALL

@read @slow

HINCRBY

@write @fast

HINCRBYFLOAT

@write @fast

HKEYS

@read @slow

HLEN

@read @fast

HMGET

@read @fast

HMSET

@write @fast

This command is deprecated. Use the HSET command with multiple field-value pairs instead.

HRANDFIELD

@read @slow

HSCAN

@read @slow

HSET

@write @fast

HSETNX

@write @fast

HSTRLEN

@read @fast

HVALS

@read @slow

1.4.4. List Commands

Command ACL Description

BLMPOP

@write @slow @blocking

BLPOP

@write @slow @blocking

BRPOP

@write @slow @blocking

LINDEX

@read @slow

LINSERT

@write @slow

The current implementation has a time complexity of O(N), where N is the size of the list.

LLEN

@read @fast

LMOVE

@write @slow

The current implementation is atomic for rotation when the source and destination are the same list. For different lists, there is relaxed consistency for concurrent operations or failures unless the resp cache is configured to use transactions.

LMPOP

@write @slow

LPOP

@write @fast

LPOS

@read @slow

LPUSH

@write @fast

LPUSHX

@write @fast

LRANGE

@read @slow

LREM

@write @slow

LSET

@write @slow

LTRIM

@write @slow

RPOP

@write @fast

RPOPLPUSH

@write @slow

This command is deprecated. Use the LMOVE command with the RIGHT and LEFT arguments instead.

RPUSH

@write @fast

RPUSHX

@write @fast

SORT

@write @slow @dangerous

SORT_RO

@read @slow @dangerous

1.4.5. Set Commands

Command ACL Description

SADD

@write @fast

SCARD

@read @fast

SDIFF

@read @slow

SDIFFSTORE

@write @slow

SINTER

@read @slow

SINTERCARD

@read @slow

SINTERSTORE

@write @slow

SISMEMBER

@read @fast

SMEMBERS

@read @slow

SMISMEMBER

@read @fast

SMOVE

@write @fast

The current implementation has a relaxed isolation level. A client can see the source and destination set without the element. The operation is not atomic, it could remove the element from source and fails to insert to the target set.

SPOP

@write @fast

SRANDMEMBER

@read @fast

SREM

@write @fast

SSCAN

@read @slow

SUNION

@read @slow

SUNIONSTORE

@write @slow

1.4.6. Sorted Set Commands

Command ACL Description

ZADD

@write @fast

ZCARD

@read @fast

ZCOUNT

@read @fast

ZDIFF

@read @slow

ZDIFFSTORE

@write @slow

ZINCRBY

@write @fast

ZINTER

@read @slow

ZINTERCARD

@read @slow

ZINTERSTORE

@write @slow

ZLEXCOUNT

@read @fast

ZMPOP

@write @slow

ZMSCORE

@read @fast

ZPOPMAX

@write @fast

ZPOPMIN

@write @fast

ZRANDMEMBER

@read @slow

ZRANGE

@read @slow

ZRANGEBYLEX

@read @slow

This command is deprecated. Use the ZRANGE command with the BYLEX argument instead.

ZRANGEBYSCORE

@read @slow

This command is deprecated. Use the ZRANGE command with the BYSCORE argument instead.

ZRANGESTORE

@read @slow

ZRANK

@read @fast

ZREM

@write @fast

ZREMRANGEBYLEX

@write @slow

ZREMRANGEBYRANK

@write @slow

ZREMRANGEBYSCORE

@write @slow

ZREVRANGE

@read @slow

This command is deprecated. Use the ZRANGE command with the REV argument instead.

ZREVRANGEBYLEX

@read @slow

This command is deprecated. Use the ZRANGE command with the REV and BYLEX arguments instead.

ZREVRANGEBYSCORE

@read @slow

This command is deprecated. Use the ZRANGE command with the REV and BYSCORE arguments instead.

ZREVRANK

@read @fast

ZSCAN

@read @slow

ZSCORE

@read @fast

ZUNION

@read @slow

ZUNIONSTORE

@write @slow

1.4.7. Bitmap Commands

Command ACL Description

BITFIELD

@write @slow

BITFIELD_RO

@read @fast

1.4.8. HyperLogLog Commands

Command ACL Description

PFADD

@write @fast

PFCOUNT

@read @slow

PFMERGE

@write @slow

1.4.9. Pub/Sub Commands

Command ACL Description

PSUBSCRIBE

@slow

PUBLISH

@fast

PUBSUB CHANNELS

@slow

PUBSUB NUMPAT

@slow

PUNSUBSCRIBE

@slow

SUBSCRIBE

@slow

UNSUBSCRIBE

@slow

1.4.10. JSON Commands

Command ACL Description

JSON.ARRAPPEND

@write @slow

JSON.ARRINDEX

@read @slow

JSON.ARRINSERT

@write @slow

JSON.ARRLEN

@read @slow

JSON.ARRPOP

@write @slow

JSON.ARRTRIM

@write @slow

JSON.CLEAR

@write @slow

JSON.DEBUG

@read

JSON.DEL

@write @slow

JSON.FORGET

@write @slow

JSON.GET

@read @slow

JSON filter with RegEx differences from Redis implementation:

  1. Pattern could be expressed in Redis style "(i)pattern" or Java style "/.pattern./i)".

  2. Dynamic filter with regex is not supported. i.e. $.store.book[?(@.name =~ $.pattern)] doesn’t work.

  3. Filtering an array returns all matching elements and all nested arrays containing matching elements.

JSON.MERGE

@write @slow

JSON.MGET

@read @slow

JSON.MSET

@write @slow

This command is non-atomic

JSON.NUMINCRBY

@write @slow

JSON.NUMMULTBY

@write @slow

JSON.OBJKEYS

@read @slow

JSON.OBJLEN

@read @slow

JSON.RESP

@read @slow

JSON.SET

@write @slow

JSON.STRAPPEND

@write @slow

JSON.STRLEN

@read @slow

JSON.TOGGLE

@write @slow

JSON.TYPE

@read @slow

1.4.11. Scripting Commands

Command ACL Description

EVAL

@slow

Unlike Redis, which maintains a bounded cache of ephemeral scripts, Infinispan discards the script immediately after execution.

EVALSHA

@slow

EVALSHA_RO

@slow

EVAL_RO

@slow

Unlike Redis, which maintains a bounded cache of ephemeral scripts, Infinispan discards the script immediately after execution.

SCRIPT EXISTS

@slow

SCRIPT FLUSH

@slow

SCRIPT LOAD

@slow

1.4.12. Transaction Commands

Command ACL Description

DISCARD

@fast

EXEC

@slow

See the MULTI command.

MULTI

@fast

The current implementation has a relaxed isolation level. Redis offers serializable transactions.

UNWATCH

@fast

WATCH

@fast

1.4.13. Connection Commands

Command ACL Description

AUTH

@fast

COMMAND

@slow

ECHO

@fast

HELLO

@fast

Only protocol version 3 (RESP3) is supported.

PING

@fast

QUIT

@fast

This command is deprecated.

READONLY

@fast

READWRITE

@fast

RESET

@fast

SELECT

@fast

Infinispan allows the SELECT command both in local and clustered mode, unlike Redis Cluster which forbids use of this command and only supports database zero.

1.4.14. Generic Commands

Command ACL Description

DBSIZE

@read @fast

DEL

@write @slow

EXISTS

@read @fast

EXPIRE

@write @fast

EXPIREAT

@write @fast

EXPIRETIME

@read @fast

FLUSHALL

@write @slow @dangerous

This command behaves like FLUSHDB and flushes only the current database.

FLUSHDB

@write @slow @dangerous

KEYS

@read @slow @dangerous

PERSIST

@write @fast

PEXPIRE

@write @fast

PEXPIREAT

@write @fast

PEXPIRETIME

@read @fast

PTTL

@read @fast

RANDOMKEY

@read @slow

RENAME

@write @slow

RENAMENX

@write @fast

SCAN

@read @slow

Cursors are reaped in case they have not been used within a timeout. The timeout is 5 minutes.

TOUCH

@read @fast

TTL

@read @fast

TYPE

@read @fast

1.4.15. Search Commands

Command ACL Description

FT._LIST

@slow @admin

1.4.16. Other Commands

Command ACL Description

CLIENT GETNAME

@slow

CLIENT ID

@slow

CLIENT INFO

@slow

CLIENT LIST

@slow

CLIENT SETINFO

@slow

CLIENT SETNAME

@slow

CLUSTER KEYSLOT

@slow

CLUSTER NODES

@slow

This command includes all required fields, but some fields are set to 0 as they do not apply to Infinispan.

CLUSTER SHARDS

@slow

CLUSTER SLOTS

@slow

CONFIG

@slow

INFO

@slow @dangerous

This implementation attempts to return all attributes that a real Redis server returns. However, in most cases, the values are set to 0 because they cannot be retrieved, or don’t apply to Infinispan.

LOLWUT

@read @fast

MEMORY STATS

@slow

This command will return the same fields as a real Redis server, but all values will be set to 0.

MEMORY USAGE

@slow

This command will return the memory used by the key and the value. It doesn’t include the memory used by additional metadata associated with the entry.

MODULE

@slow

TIME

@fast