Closes #640

Summary

This PR introduces support for field-level expiration in Valkey hash types, making it possible for individual fields inside a hash to expire independently — creating what we call volatile fields.
This is just the first out of 3 PRs. The content of this PR focus on enabling the basic ability to set and modify hash fields expiration as well as persistency (AOF+RDB) and defrag.
The second PR introduces the new algorithm (volatile-set) to track volatile hash fields is in the last stages of review. The current implementation in this PR (in volatile-set.h/c) is just s tub implementation and will be replaced by The second PR
The third PR which introduces the active expiration and defragmentation jobs.

For more highlevel design details you can track the RFC PR: valkey-io/valkey-rfc#22.

Major decisions

Some highlevel major decisions which are taken as part of this work:

1. We decided to copy the existing Redis API in order to maintain compatibility with existing clients.

2. We decided to avoid introducing lazy-expiration at this point, in order to reduce complexity and rely only on active-expiration for memory reclamation. This will require us to continue to work on improving the active expiration job and potentially consider introduce lazy-expiration support later on.

3. Although different commands which are adding expiration on hash fields are influencing the memory utilization (by allocating more memory for expiration time and metadata) we decided to avoid adding the DENYOOM for these commands (an exception is HSETEX) in order to be better aligned with highlevel keys commands like expire

4. Some hash type commands will produce unexpected results:

• HLEN - will still reflect the number of fields which exists in the hash object (either actually expired or not).
• HRANDFIELD - in some cases we will not be able to randomly select a field which was not already expired. this case happen in 2 cases: 1/ when we are asked to provide a non-uniq fields (i.e negative count) 2/ when the size of the hash is much bigger than the count and we need to provide uniq results. In both cases it is possible that an empty response will be returned to the caller, even in case there are fields in the hash which are either persistent or not expired.

5. For the case were a field is provided with a zero (0) expiration time or expiration time in the past, it is immediately deleted. We decided that, in order to be aligned with how high level keys are handled, we will emit hexpired keyspace event for that case (instead of hdel). For example:
   for the case:

HSET myhash f1 v1
> 0
HGETEX myhash EX 0 FIELDS 1 f1
> "v1"
HTTL myhash FIELDS 1 f1
>  -2

The reported events are:

1) "psubscribe"
2) "__keyevent@0__*"
3) (integer) 1
1) "pmessage"
2) "__keyevent@0__*"
3) "__keyevent@0__:hset"
4) "myhash"
1) "pmessage"
2) "__keyevent@0__*"
3) "__keyevent@0__:hexpired" <---------------- note this
4) "myhash"
1) "pmessage"
2) "__keyevent@0__*"
3) "__keyevent@0__:del"
4) "myhash"

6. We will ALWAYS load hash fields during rdb load. This means that when primary is rebooting with an old snapshot, it will take time to reclaim all the expired fields. However this simplifies the current logic and avoid major refactoring that I suspect will be needed.

New entry type

This PR also modularizes and exposes the internal hashTypeEntry logic as a new standalone entry.c/h module. This new abstraction handles all aspects of field–value–expiry encoding using multiple memory layouts optimized for performance and memory efficiency.

An entry is an abstraction that represents a single field–value pair with optional expiration. Internally, Valkey uses different memory layouts for compactness and efficiency, chosen dynamically based on size and encoding constraints.

The entry pointer is the field sds. Which make us use an entry just like any sds. We encode the entry layout type
in the field SDS header. Field type SDS_TYPE_5 doesn't have any spare bits to
encode this so we use it only for the first layout type.

Entry with embedded value, used for small sizes. The value is stored as
SDS_TYPE_8. The field can use any SDS type.

Entry can also have expiration timestamp, which is the UNIX timestamp for it to be expired.
For aligned fast access, we keep the expiry timestamp prior to the start of the sds header.

 +----------------+--------------+---------------+
 | Expiration     | field        | value         |
 | 1234567890LL   | hdr "foo" \0 | hdr8 "bar" \0 |
 +-----------------------^-------+---------------+
                         |
                         |
                        entry pointer (points to field sds content)

Entry with value pointer, used for larger fields and values. The field is SDS
type 8 or higher.

 +--------------+-------+--------------+
 | Expiration   | value | field        |
 | 1234567890LL | ptr   | hdr "foo" \0 |
 +--------------+--^----+------^-------+
                   |           |
                   |           |
                   |         entry pointer (points to field sds content)
                   |
                  value pointer = value sds

The entry.c/h API provides methods to:

• Create, read, and write and Update field/value/expiration
• Set or clear expiration
• Check expiration state
• Clone or delete an entry

Supported Commands

This PR introduces new commands and extends existing ones to support field expiration:

Commands

The proposed API is very much identical to the Redis provided API (Redis 7.4 + 8.0). This is intentionally proposed in order to avoid breaking client applications already opted to use hash items TTL.

HSETEX

Synopsis

HSETEX key [NX | XX] [FNX | FXX] [EX seconds | PX milliseconds |
  EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL]
  FIELDS numfields field value [field value ...]

Set the value of one or more fields of a given hash key, and optionally set their expiration time or time-to-live (TTL).

The HSETEX command supports the following set of options:

• NX — Only set the fields if the hash object does NOT exist.
• XX — Only set the fields if if the hash object doesx exist.
• FNX — Only set the fields if none of them already exist.
• FXX — Only set the fields if all of them already exist.
• EX seconds — Set the specified expiration time in seconds.
• PX milliseconds — Set the specified expiration time in milliseconds.
• EXAT unix-time-seconds — Set the specified Unix time in seconds at which the fields will expire.
• PXAT unix-time-milliseconds — Set the specified Unix time in milliseconds at which the fields will expire.
• KEEPTTL — Retain the TTL associated with the fields.

The EX, PX, EXAT, PXAT, and KEEPTTL options are mutually exclusive.

HEGTEX

Synopsis

HGETEX key [EX seconds | PX milliseconds | EXAT unix-time-seconds |
  PXAT unix-time-milliseconds | PERSIST] FIELDS numfields field
  [field ...]

Get the value of one or more fields of a given hash key and optionally set their expiration time or time-to-live (TTL).

The HGETEX command supports a set of options:

• EX seconds — Set the specified expiration time, in seconds.
• PX milliseconds — Set the specified expiration time, in milliseconds.
• EXAT unix-time-seconds — Set the specified Unix time at which the fields will expire, in seconds.
• PXAT unix-time-milliseconds — Set the specified Unix time at which the fields will expire, in milliseconds.
• PERSIST — Remove the TTL associated with the fields.

The EX, PX, EXAT, PXAT, and PERSIST options are mutually exclusive.

HEXPIRE

Synopsis

HEXPIRE key seconds [NX | XX | GT | LT] FIELDS numfields
  field [field ...]

Set an expiration (TTL or time to live) on one or more fields of a given hash key. You must specify at least one field. Field(s) will automatically be deleted from the hash key when their TTLs expire.
Field expirations will only be cleared by commands that delete or overwrite the contents of the hash fields, including HDEL and HSET commands. This means that all the operations that conceptually alter the value stored at a hash key's field without replacing it with a new one will leave the TTL untouched.
You can clear the TTL of a specific field by specifying 0 for the ‘seconds’ argument.
Note that calling HEXPIRE/HPEXPIRE with a time in the past will result in the hash field being deleted immediately.

The HEXPIRE command supports a set of options:

• NX — For each specified field, set expiration only when the field has no expiration.
• XX — For each specified field, set expiration only when the field has an existing expiration.
• GT — For each specified field, set expiration only when the new expiration is greater than current one.
• LT — For each specified field, set expiration only when the new expiration is less than current one.

HEXPIREAT

Synopsis

HEXPIREAT key unix-time-seconds [NX | XX | GT | LT] FIELDS numfields
  field [field ...]

HEXPIREAT has the same effect and semantics as HEXPIRE, but instead of specifying the number of seconds for the TTL (time to live), it takes an absolute Unix timestamp in seconds since Unix epoch. A timestamp in the past will delete the field immediately.

The HEXPIREAT command supports a set of options:

• NX — For each specified field, set expiration only when the field has no expiration.
• XX — For each specified field, set expiration only when the field has an existing expiration.
• GT — For each specified field, set expiration only when the new expiration is greater than current one.
• LT — For each specified field, set expiration only when the new expiration is less than current one.

HPEXPIRE

Synopsis

HPEXPIRE key milliseconds [NX | XX | GT | LT] FIELDS numfields
  field [field ...]

This command works like HEXPIRE, but the expiration of a field is specified in milliseconds instead of seconds.

The HPEXPIRE command supports a set of options:

• NX — For each specified field, set expiration only when the field has no expiration.
• XX — For each specified field, set expiration only when the field has an existing expiration.
• GT — For each specified field, set expiration only when the new expiration is greater than current one.
• LT — For each specified field, set expiration only when the new expiration is less than current one.

HPEXPIREAT

Synopsis

HPEXPIREAT key unix-time-milliseconds [NX | XX | GT | LT]
  FIELDS numfields field [field ...]

HPEXPIREAT has the same effect and semantics as HEXPIREAT``, but the Unix time at which the field will expire is specified in milliseconds since Unix epoch instead of seconds.

HPERSIST

Synopsis

HPERSIST key FIELDS numfields field [field ...]

Remove the existing expiration on a hash key's field(s), turning the field(s) from volatile (a field with expiration set) to persistent (a field that will never expire as no TTL (time to live) is associated).

HSETEX

Synopsis

HSETEX key [NX] seconds field value [field value ...]

Similar to HSET but adds one or more hash fields that expire after specified number of seconds. By default, this command overwrites the values and expirations of specified fields that exist in the hash. If NX option is specified, the field data will not be overwritten. If key doesn't exist, a new Hash key is created.

The HSETEX command supports a set of options:

• NX — For each specified field, set expiration only when the field has no expiration.

HTTL

Synopsis

HTTL key FIELDS numfields field [field ...]

Returns the remaining TTL (time to live) of a hash key's field(s) that have a set expiration. This introspection capability allows you to check how many seconds a given hash field will continue to be part of the hash key.

HPTTL

HPTTL key FIELDS numfields field [field ...]

Like HTTL, this command returns the remaining TTL (time to live) of a field that has an expiration set, but in milliseconds instead of seconds.

HEXPIRETIME

Synopsis

HEXPIRETIME key FIELDS numfields field [field ...]

Returns the absolute Unix timestamp in seconds since Unix epoch at which the given key's field(s) will expire.

HPEXPIRETIME

Synopsis

HPEXPIRETIME key FIELDS numfields field [field ...]

HPEXPIRETIME has the same semantics as HEXPIRETIME, but returns the absolute Unix expiration timestamp in milliseconds since Unix epoch instead of seconds.

Keyspace Notifications

This PR introduces new notification events to support field-level expiration:

Note that we diverge from Redis in the cases we emit hexpired event.
For example:
given the following usecase:

HSET myhash f1 v1
(integer) 0
HGETEX myhash EX 0 FIELDS 1 f1
1) "v1"
 HTTL myhash FIELDS 1 f1
1) (integer) -2

regarding the keyspace-notifications:
Redis reports:

1) "psubscribe"
2) "__keyevent@0__:*"
3) (integer) 1
1) "pmessage"
2) "__keyevent@0__:*"
3) "__keyevent@0__:hset"
4) "myhash2"
1) "pmessage"
2) "__keyevent@0__:*"
3) "__keyevent@0__:hdel" <---------------- note this
4) "myhash2"
1) "pmessage"
2) "__keyevent@0__:*"
3) "__keyevent@0__:del"
4) "myhash2"

However In our current suggestion, Valkey will emit:

1) "psubscribe"
2) "__keyevent@0__*"
3) (integer) 1
1) "pmessage"
2) "__keyevent@0__*"
3) "__keyevent@0__:hset"
4) "myhash"
1) "pmessage"
2) "__keyevent@0__*"
3) "__keyevent@0__:hexpired" <---------------- note this
4) "myhash"
1) "pmessage"
2) "__keyevent@0__*"
3) "__keyevent@0__:del"
4) "myhash"

Propagation and Replication

• Expiration-aware commands (HSETEX, HGETEX, etc.) are not propagated as-is.
• Instead, Valkey rewrites them into equivalent commands like:
  • HDEL (for expired fields)
  • HPEXPIREAT (for setting absolute expiration)
  • HPERSIST (for removing expiration)

This ensures compatibility with replication and AOF while maintaining consistent field-level expiry behavior.

Performance Comparison

Accumulated Backlog

[ ] Consider extending HSETEX with extra arguments: NX/XX so that it is possible to prevent adding/setting/mutating fields of a non-existent hash
[ ] Avoid loading expired fields when non-preamble RDB is being loaded on primary. This is an optimization in order to reduce loading unnecessary fields (which are expired). This would also require us to propagate the HDEL to the replicas in case of RDBFLAGS_FEED_REPL. Note that it might have to require some refactoring:
1/ propagate the rdbflags and current time to rdbLoadObject. 2/ consider the case of restore and check_rdb etc...
For this reason I would like to avoid this optimizationfor the first drop.