Skip to content

Commit 4dc0508

Browse files
committed
feat(serialization): value serializer seam, chosen per policy
ICacheValueSerializer is a public interface anyone can implement to store cache values in their own format. A serializer is registered by name with AddValueSerializer and chosen per cache policy with CachePolicy.Serializer; JSON stays the default and headerless. Each non-JSON value starts with a format id. The library owns 0x01-0x0F except 0x09, 0x0A and 0x0D, consumers own 0x10-0x1E, and 0x1F marks an extended id in the next byte (0x100-0x1FF, also for consumers). Registration rejects duplicate, out-of-range and mixed-length ids, a duplicate name and "json". Writes go through a pooled buffer for any serializer, with the header reserved first. Policy checks run on the effective, merged policy: a blank Write or Read name, an empty Read list and a Write that Read leaves out are rejected. The registry keeps the ids it validated and disposes the serializers it created. AddDistributedCache stays on JSON whatever Serializer says, so the caller's bytes never get a header. A Write name that the policy factory did not resolve, from a per-call policy or a custom factory, is resolved through the registry, and an unknown name throws; a custom factory's names are checked when its first cache is built. The registry owns and disposes what a factory returns, including serializers that are only IAsyncDisposable, and a null FormatIds fails with the serializer's name. ICacheValueSerializer documents that the library writes and strips the header, that FormatIds is read once, and how empty, multi-segment and null payloads behave. Signed-off-by: Cosmin Staicu <cosmin.staicu@uipath.com>
1 parent 4301cc8 commit 4dc0508

39 files changed

Lines changed: 2231 additions & 37 deletions

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
66

77
## [Unreleased]
88

9+
### Added
10+
11+
- **A seam for value serializers.** `ICacheValueSerializer` and `CacheValueFormats` define a buffer-based serializer whose output starts with a one-byte format id, `AddValueSerializer` registers one by name, and `CachePolicy.Serializer` (`Write`, `Read`, `MigrateOnRead`) names it per policy. `AddValueSerializer` throws at the call for a name used twice on one builder or for `json`. A policy that names an unregistered or blank serializer, has an empty `Read`, or writes a format its `Read` leaves out fails with an `OptionsValidationException`, as does a serializer whose ids are outside the consumer ranges; these are checked when the policy factory is first resolved, on first cache use rather than at host start. A custom `ICachePolicyFactory` whose policy names an unregistered serializer fails the same way when the Redis provider builds its cache. Serializers the container created are disposed with it, through `DisposeAsync` when they only implement `IAsyncDisposable`, so a factory must return a new instance rather than one resolved from DI. The default stays JSON with no header, and `AddDistributedCache` ignores `Serializer`: its own policy always writes and reads JSON with no migration, so the caller's bytes never get a format header.
12+
913
### Changed
1014

1115
- **Cache event properties are read as typed values.** The built-in event formatters parse `_version_`, the expirations, the metadata and the peer fields straight into `long`, `DateTimeOffset`, string dictionaries and byte arrays instead of a `JsonElement` that was parsed again by the value serializer, which saves a clone, a box and a second parse per property of a peer-update event. The event bytes on the wire are unchanged. A custom `ISerializerProxy<byte[]>` no longer sees these properties in `TryDeserialize(object)` when the built-in formatters decode the event.

‎docs/how-to/extending.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -359,6 +359,21 @@ adapter, which constructs its own `RawByteSerializerProxy`; see the contract not
359359
- **Only replace the default globally.** `AddDistributedCache` gives its own provider `RawByteSerializerProxy` explicitly rather than resolving one from DI, so replacing the app-wide registration does not change what the `IDistributedCache` adapter stores in its `data` field. That is deliberate: those bytes belong to the caller.
360360
- **Set members are compared by their serialized bytes.** `ISetCache`'s local tier keys its snapshot on `Serialize` output using structural byte equality, so a serializer must be deterministic: two equal values must serialize identically, or set membership and de-duplication will disagree between the memory and Redis tiers.
361361

362+
### Named value serializers: `ICacheValueSerializer`
363+
364+
`AddValueSerializer(name, factory)` registers an `ICacheValueSerializer` that a policy selects with
365+
`Serializer.Write` (see [Policies\[\<name\>\].Serializer](../reference/settings.md#policiesnameserializer-serializerpolicy)).
366+
The library writes and strips the format header; the serializer only produces and reads the payload.
367+
368+
```csharp
369+
builder.AddValueSerializer("fast", _ => new MyValueSerializer());
370+
```
371+
372+
The registry owns whatever the factory returns and disposes it with the container, through `DisposeAsync` when
373+
the serializer has one and `Dispose` otherwise. So the factory must return a new instance, not one resolved from
374+
DI, which the container would dispose a second time. The factory runs when the registry is built, on first cache
375+
use; a build that throws disposes what it created, and the next use runs the factory again.
376+
362377
### Distributed cache keyspace
363378

364379
The distributed cache stores each entry as a Redis hash with a `data` field plus `absexp`/`sldexp`

‎docs/reference/settings.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -440,6 +440,7 @@ Entries are keyed by string under `Caching:Policies`. `ICache<T>` and `IHashCach
440440
| `RehydrateEnabled` | `bool?` | `null` | Per-policy | Master switch for proactive background refresh; `null` = inherit (default off). |
441441
| `Rehydrate` | `RehydrateOptions?` | `null` | Per-policy | Rehydrate tuning; replaced wholesale (no per-field merge) when overriding. See [Policies\[\<name\>\].Rehydrate (RehydrateOptions)](#policiesnamerehydrate-rehydrateoptions). |
442442
| `Lock` | `LockProfile?` | `null` | Per-policy | Per-cache lock overrides; field-level merged against the default policy. See [Policies\[\<name\>\].Lock (LockProfile)](#policiesnamelock-lockprofile). |
443+
| `Serializer` | `SerializerPolicy?` | `null` | Per-policy | Which value serializer the policy writes with and reads; `null` = JSON. Field-level merged against the default policy. See [Policies\[\<name\>\].Serializer (SerializerPolicy)](#policiesnameserializer-serializerpolicy). |
443444

444445
---
445446

@@ -469,3 +470,17 @@ Nested under a `CachePolicy` entry. Field-level merged against the default polic
469470
| `DistributedLockTimeout` | `TimeSpan?` | `null` | Per-policy | `null` = inherit from provider options or default policy. |
470471
| `DistributedLockExpiry` | `TimeSpan?` | `null` | Per-policy | Redis key TTL for the distributed lock; `null` = inherit from provider options or default policy. |
471472
| `DistributedLockSkipReread` | `bool?` | `null` | Per-policy | Skip the second Redis read under a lock free at the first attempt (see the provider option); `null` = inherit from provider options or default policy. |
473+
474+
---
475+
476+
## Policies\[\<name\>\].Serializer (SerializerPolicy)
477+
478+
Nested under a `CachePolicy` entry. Field-level merged against the default policy's `SerializerPolicy`: set only the fields you want to override; `null` inherits. A blank name, or one that is not registered with `AddValueSerializer` (and is not `json`), fails with an `OptionsValidationException` when the policy factory is first resolved, which is on first cache use rather than at host start. The merged policy must also read what it writes: `Read` may not be empty and must include `Write`. `AddDistributedCache` ignores `Serializer`: its own policy always writes and reads JSON, so a default `Serializer` does not stop it.
479+
480+
| Property | Type | Default | Scope | Notes |
481+
|---|---|---|---|---|
482+
| `Write` | `string?` | `null` | Per-policy | A registered serializer name, or `json`; blank is rejected; `null` = inherit, and under that `json`. |
483+
| `Read` | `string[]?` | `null` | Per-policy | The formats the policy reads, each a registered name or `json`; never empty, and including `Write`; `null` = inherit, and under that every registered format. Arrays from layered configuration merge by index, see below. |
484+
| `MigrateOnRead` | `bool?` | `null` | Per-policy | Rewrite a value read in another format into the write format; `null` = inherit, and under that off. |
485+
486+
**`Read` and layered configuration.** A `Read` set in code replaces the default policy's list as a whole, but .NET configuration providers merge arrays by index. With a base layer of `"Read": ["a", "b"]` and an override layer of `"Read": ["json"]`, the bound list is `["json", "b"]`, not `["json"]`. An override of `"Read": []` binds as `null`, so it inherits and the policy reads every registered format. To override safely, set every index the base layer sets (or repeat the full list), or declare `Read` in one layer only.

‎samples/UiPath.Caching.Sample/appsettings.all.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -522,6 +522,15 @@
522522
"DistributedLockExpiry": "0:00:05",
523523
// DistributedLockSkipReread: null = inherit from provider options or default policy
524524
"DistributedLockSkipReread": null
525+
},
526+
// Serializer: the value serializer this policy writes with and reads; field-level merged against the default policy (UiPath.Caching.SerializerPolicy)
527+
"Serializer": {
528+
// Write: a registered serializer name, or "json"; null = inherit (default json)
529+
"Write": "messagepack",
530+
// Read: the formats this policy reads; null = inherit (default every registered format). Layered config merges arrays by index, so repeat the full list in an override layer
531+
"Read": ["json", "messagepack"],
532+
// MigrateOnRead: rewrite a value read in another format into the write format; null = inherit (default off)
533+
"MigrateOnRead": true
525534
}
526535
}
527536
},
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
namespace UiPath.Caching;
2+
3+
public static class CacheValueFormats
4+
{
5+
public const int MessagePack = 0x02;
6+
public const int MessagePackLz4 = 0x03;
7+
public const int FirstConsumer = 0x10;
8+
public const int LastConsumer = 0x1E;
9+
public const int FirstExtended = 0x100;
10+
public const int LastExtended = 0x1FF;
11+
public const string JsonName = "json";
12+
}

‎src/UiPath.Caching.Abstractions/Config/CachePolicy.cs‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,4 +89,10 @@ public sealed class CachePolicy
8989
/// while inheriting the rest. (Compare with <see cref="Rehydrate"/>, which is replaced wholesale.)
9090
/// </summary>
9191
public LockProfile? Lock { get; init; }
92+
93+
/// <summary>Which value serializer the policy writes with and reads. Merged field by field against the default policy. <c>null</c> inherits (default JSON).</summary>
94+
public SerializerPolicy? Serializer { get; init; }
95+
96+
/// <summary>The serializer <see cref="SerializerPolicy.Write"/> names, set once the policy factory has resolved it; <c>null</c> writes JSON.</summary>
97+
internal ICacheValueSerializer? WriteSerializer { get; init; }
9298
}
Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
namespace UiPath.Caching;
2+
3+
/// <summary>Which value serializer a cache policy writes with and reads. Merged field by field against the default policy, a <c>null</c> field inheriting.</summary>
4+
public sealed class SerializerPolicy
5+
{
6+
/// <summary>A registered serializer name, or <c>"json"</c>, never blank; <c>null</c> inherits (default JSON).</summary>
7+
public string? Write { get; init; }
8+
9+
/// <summary>Names of the formats this policy reads, never empty and including <c>Write</c>; <c>null</c> inherits (default every registered format).</summary>
10+
/// <remarks>
11+
/// Merging two policies in code replaces the list as a whole. Layered configuration does not: the binder merges arrays by index, so an override of
12+
/// <c>["json"]</c> over a base <c>["a", "b"]</c> binds as <c>["json", "b"]</c>, and an empty array binds as <c>null</c> (inherit). To override safely, set every index
13+
/// the base layer sets, or declare <c>Read</c> in one layer only.
14+
/// </remarks>
15+
public IReadOnlyList<string>? Read { get; init; }
16+
17+
/// <summary>Rewrite a value read in another format into the write format; <c>null</c> inherits (default off).</summary>
18+
public bool? MigrateOnRead { get; init; }
19+
}
Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
using System.Buffers;
2+
3+
namespace UiPath.Caching;
4+
5+
/// <summary>Writes and reads cache values as bytes, each tagged on the wire with one of its <see cref="FormatIds"/>.</summary>
6+
/// <remarks>
7+
/// One instance serves every thread and every cache at once, so an implementation must be thread-safe and keep no state between calls; calls may be nested on one thread.
8+
/// The library writes and strips the format header: <see cref="Serialize{T}"/> writes none and <see cref="Deserialize{T}"/> receives header-free bytes.
9+
/// </remarks>
10+
public interface ICacheValueSerializer
11+
{
12+
/// <summary>The ids this serializer writes and reads, all with the same header length: 0x10-0x1E take one byte, 0x100-0x1FF two.</summary>
13+
/// <remarks>Read once, when the serializer is registered; it must not change afterwards.</remarks>
14+
IReadOnlyList<int> FormatIds { get; }
15+
16+
/// <summary>Writes at least one byte and returns the id it wrote, one of <see cref="FormatIds"/>.</summary>
17+
/// <remarks>A null value included: an empty payload is reserved for a cached null. <paramref name="target"/> is valid only during the call.</remarks>
18+
int Serialize<T>(T value, IBufferWriter<byte> target);
19+
20+
/// <summary>Returns the value in <paramref name="source"/>, or throws; must not retain <paramref name="source"/> past the call.</summary>
21+
/// <remarks>
22+
/// Throw on an id it does not own and on corrupt or truncated input, and never return a partial value: the reader maps a throw to a cache miss.
23+
/// <paramref name="source"/> may span several segments or be empty. A null result for a non-empty payload is read as a cached null: a hit when <c>CacheNullValues</c> is on, a miss when it is off.
24+
/// </remarks>
25+
T? Deserialize<T>(int formatId, ReadOnlySequence<byte> source);
26+
}
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,23 @@
11
#nullable enable
2+
const UiPath.Caching.CacheValueFormats.FirstConsumer = 16 -> int
3+
const UiPath.Caching.CacheValueFormats.FirstExtended = 256 -> int
4+
const UiPath.Caching.CacheValueFormats.JsonName = "json" -> string!
5+
const UiPath.Caching.CacheValueFormats.LastConsumer = 30 -> int
6+
const UiPath.Caching.CacheValueFormats.LastExtended = 511 -> int
7+
const UiPath.Caching.CacheValueFormats.MessagePack = 2 -> int
8+
const UiPath.Caching.CacheValueFormats.MessagePackLz4 = 3 -> int
9+
UiPath.Caching.CacheValueFormats
10+
UiPath.Caching.ICacheValueSerializer
11+
UiPath.Caching.ICacheValueSerializer.Deserialize<T>(int formatId, System.Buffers.ReadOnlySequence<byte> source) -> T?
12+
UiPath.Caching.ICacheValueSerializer.FormatIds.get -> System.Collections.Generic.IReadOnlyList<int>!
13+
UiPath.Caching.ICacheValueSerializer.Serialize<T>(T value, System.Buffers.IBufferWriter<byte>! target) -> int
14+
UiPath.Caching.CachePolicy.Serializer.get -> UiPath.Caching.SerializerPolicy?
15+
UiPath.Caching.CachePolicy.Serializer.init -> void
16+
UiPath.Caching.SerializerPolicy
17+
UiPath.Caching.SerializerPolicy.MigrateOnRead.get -> bool?
18+
UiPath.Caching.SerializerPolicy.MigrateOnRead.init -> void
19+
UiPath.Caching.SerializerPolicy.Read.get -> System.Collections.Generic.IReadOnlyList<string!>?
20+
UiPath.Caching.SerializerPolicy.Read.init -> void
21+
UiPath.Caching.SerializerPolicy.SerializerPolicy() -> void
22+
UiPath.Caching.SerializerPolicy.Write.get -> string?
23+
UiPath.Caching.SerializerPolicy.Write.init -> void

src/UiPath.Caching/Config/ForegroundOnlyPolicyFactory.cs renamed to src/UiPath.Caching/Config/AdapterPolicyFactory.cs

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,14 @@
22

33
namespace UiPath.Caching.Config;
44

5-
/// <summary>The inner policies with background writes off, for writes of memory the caller reclaims on return.</summary>
6-
internal sealed class ForegroundOnlyPolicyFactory(ICachePolicyFactory inner) : ICachePolicyFactory
5+
/// <summary>The inner policies with background writes off, for writes of memory the caller reclaims on return, and with the JSON serializer only, since the values are the caller's own bytes.</summary>
6+
internal sealed class AdapterPolicyFactory(ICachePolicyFactory inner) : ICachePolicyFactory
77
{
8-
private static readonly CachePolicy Awaited = new() { BackgroundDistributedWrite = false };
8+
internal static readonly CachePolicy Overlay = new()
9+
{
10+
BackgroundDistributedWrite = false,
11+
Serializer = new SerializerPolicy { Write = CacheValueFormats.JsonName, Read = [CacheValueFormats.JsonName], MigrateOnRead = false },
12+
};
913

1014
// Keyed on the inner instance, so a reloaded policy is merged again.
1115
private readonly ConcurrentDictionary<string, Merged> _named = new(StringComparer.Ordinal);
@@ -19,7 +23,7 @@ public CachePolicy? Default
1923
var merged = Volatile.Read(ref _default);
2024
if (merged is null || !ReferenceEquals(merged.Source, source))
2125
{
22-
merged = new Merged(source, CachePolicyMerger.Merge(Awaited, source));
26+
merged = new Merged(source, CachePolicyMerger.Merge(Overlay, source));
2327
Volatile.Write(ref _default, merged);
2428
}
2529

@@ -38,7 +42,7 @@ public CachePolicy? Default
3842

3943
if (!_named.TryGetValue(policyName, out var merged) || !ReferenceEquals(merged.Source, named))
4044
{
41-
_named[policyName] = merged = new Merged(named, CachePolicyMerger.Merge(Awaited, named));
45+
_named[policyName] = merged = new Merged(named, CachePolicyMerger.Merge(Overlay, named));
4246
}
4347

4448
return merged.Policy;

0 commit comments

Comments
 (0)