Skip to content

Commit e77fc7f

Browse files
committed
feat(messagepack): MessagePack value serializer package
Adds the UiPath.Caching.MessagePack package, a value serializer that a policy picks with Serializer.Write = "messagepack". It is registered with AddMessagePackSerializer, which takes an optional name and a configure callback for MessagePackValueSerializerOptions. Values below CompressionThresholdBytes (default 1024) are written plain with format id 0x02. At or above it the value is tried with LZ4, stored as id 0x03 when the result is smaller and as plain 0x02 otherwise. A threshold of 0 tries every value. Reads accept both ids and reject a compressed value that claims more than 255 times its stored size or more than MaxDecompressedBytes (default 512 MiB), which is also applied as MessagePack's own decompression limit. A value larger than that cap is written plain so it stays readable, and an OutOfMemoryException wrapped by MessagePack is rethrown unwrapped. The default serializer options use a contractless resolver with MessagePackSecurity.UntrustedData, and supplied options that carry TrustedData are made untrusted. The serializer is internal and owns only ids 0x02 and 0x03, registered through an internal method that UiPath.Caching exposes to the package with InternalsVisibleTo. The public AddValueSerializer still accepts consumer ids only, so the package depends on the exact same UiPath.Caching version. Nothing changes until an app registers the package and a policy names it. Once values are written as MessagePack, every reader of those keys needs the package registered, readers first in a rolling deploy. Signed-off-by: Cosmin Staicu <cosmin.staicu@uipath.com>
1 parent a32ea16 commit e77fc7f

30 files changed

Lines changed: 1855 additions & 1 deletion

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
88

99
### Added
1010

11+
- **`UiPath.Caching.MessagePack`, a MessagePack value serializer.** `AddMessagePackSerializer()` registers it as `messagepack`, and a policy opts in per policy with `Serializer.Write = "messagepack"`; every other policy keeps writing JSON. It writes format id `0x02`, or `0x03` when the value's MessagePack bytes reach `CompressionThresholdBytes` (default 1024) and LZ4 compression makes them smaller, so an incompressible value stays `0x02`; it uses MessagePack's own LZ4 and adds no dependency. The default options are the contractless resolver with `MessagePackSecurity.UntrustedData`, and `SerializerOptions` replaces them. `MaxDecompressedBytes` defaults to 64 MiB: deserializing can allocate several times the decompressed size, so size it to available memory. Key types MessagePack has no collision-resistant comparer for (`TimeSpan`, `decimal`, tuples, custom structs) fall back to the default comparer. Register it on every node and finish that deploy before any policy writes it, since a node that cannot read the format misses and regenerates the value. Like JSON, contractless MessagePack writes property names, so renaming or retyping a property silently loses that data for values written before the change; `[MessagePackObject]` with `[Key]` avoids that. The package accepts MessagePack `[3.1.12, 4.0)`. See [MessagePack](docs/how-to/extending.md#messagepack).
1112
- **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. A policy that sets `Write` makes `RedisCache` and `RedisHashCache` write their values, hash fields and hash metadata with that serializer, and every read picks the serializer by the format id, whatever the policy writes. A value in a format no registered serializer owns is a miss, counted in `cache.serializer.unreadable` and removed only if the key still holds the bytes that were read, so a newer value written in between survives; a hash with such a field misses whole and is left in place. A value whose registered serializer throws is a logged miss and the key stays, like one that is not headered and fails to parse as JSON, because the bytes may be good for another version of the type during a rolling deploy; this departs from the design spec, which removed it, and an `OutOfMemoryException` from its payload is never swallowed, while one from a value with no header (JSON) is a logged miss as it is with no serializer registered. `RedisHashCache.TryDecodeFields` now treats any exception except `OutOfMemoryException` as a refresh, since a registered serializer can throw any type, where it caught four. A node with no serializer registered logs the `JsonException` and keeps the key. A policy passed to a single call that names an unregistered serializer throws `OptionsValidationException` before anything is written. The reader only looks for a header with the default JSON serializer or under a policy whose effective `Write` is a serializer other than `json` (`Read` does not count), so `byte[]` values stored through `RawByteSerializerProxy` or `AddDistributedCache` are never reinterpreted. A policy that sets no serializer, or only `Read`, takes the default policy's `Write`. 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. A hash write that names a serializer leaves `_metadata_` out when the metadata is empty and nulls are not cached, and a `HashReplace` one deletes the field an earlier write left. Hash system field names are compared as bytes instead of strings. See [value serializers](docs/how-to/extending.md#value-serializers) and [rolling a serializer out](docs/concepts.md#rolling-a-serializer-out).
1213

1314
### Changed

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,7 @@ flowchart LR
161161
| `UiPath.Caching.OpenTelemetry` | OpenTelemetry adapter for `ICachingTelemetryProvider` — `ActivitySource` + `Meter` named `UiPath.Caching`. |
162162
| `UiPath.Caching.Azure` | Microsoft Entra ID authentication for Azure Managed Redis / Azure Cache for Redis. Adds `AddAzureEntraAuthentication()`. |
163163
| `UiPath.Caching.Queue` | Set ("queue") caches — `ISetCache` / `ISetCache<T>`, registered per backing via `AddQueueMemory` / `AddQueueRedis` / `AddQueueInMemoryRedis`. |
164+
| `UiPath.Caching.MessagePack` | MessagePack value serializer with LZ4 compression above a size threshold; selected per policy through `Serializer.Write`. |
164165

165166
## Documentation
166167

‎UiPath.Caching.slnx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
<Project Path="src/UiPath.Caching.Analyzers/UiPath.Caching.Analyzers.csproj" />
1919
<Project Path="src/UiPath.Caching.Azure/UiPath.Caching.Azure.csproj" />
2020
<Project Path="src/UiPath.Caching.CloudEvents/UiPath.Caching.CloudEvents.csproj" />
21+
<Project Path="src/UiPath.Caching.MessagePack/UiPath.Caching.MessagePack.csproj" />
2122
<Project Path="src/UiPath.Caching.OpenTelemetry/UiPath.Caching.OpenTelemetry.csproj" />
2223
<Project Path="src/UiPath.Caching.Polly/UiPath.Caching.Polly.csproj" />
2324
<Project Path="src/UiPath.Caching.Queue/UiPath.Caching.Queue.csproj" />

‎benchmarks/UiPath.Caching.Benchmarks/FakeRedisConnector.cs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,8 @@ public static T Create(FakeRedisStore store)
110110

111111
if (method.Name == "StringSetAsync" && args is [RedisKey setKey, RedisValue value, ..])
112112
{
113-
_store.Values[setKey] = value;
113+
// The caller returns a pooled buffer to its pool once the call completes, so the store keeps its own bytes.
114+
_store.Values[setKey] = value.IsNull ? value : (byte[])value!;
114115
_store.LastSet = setKey;
115116
return Task.FromResult(true);
116117
}
Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
using System.Buffers;
2+
using BenchmarkDotNet.Attributes;
3+
using BenchmarkDotNet.Configs;
4+
using Microsoft.Extensions.DependencyInjection;
5+
using UiPath.Caching.Config;
6+
using UiPath.Caching.MessagePack;
7+
using UiPath.Caching.Serialization;
8+
9+
namespace UiPath.Caching.Benchmarks;
10+
11+
/// <summary>The MessagePack serializer with compression off against its default threshold, at three payload sizes of compressible rows.</summary>
12+
[MemoryDiagnoser]
13+
[GroupBenchmarksBy(BenchmarkLogicalGroupRule.ByCategory)]
14+
[CategoriesColumn]
15+
public class MessagePackCompressionBenchmark
16+
{
17+
private readonly ArrayBufferWriter<byte> _target = new();
18+
private ServiceProvider _plainServices = default!;
19+
private ServiceProvider _compressedServices = default!;
20+
private ICacheValueSerializer _plain = default!;
21+
private ICacheValueSerializer _compressed = default!;
22+
private Payload _value = default!;
23+
private byte[] _plainBytes = default!;
24+
private byte[] _compressedBytes = default!;
25+
private int _compressedId;
26+
27+
[Params(512, 1024, 16 * 1024, 128 * 1024)]
28+
public int Bytes { get; set; }
29+
30+
[GlobalSetup]
31+
public void Setup()
32+
{
33+
_plainServices = Build(o => o.CompressionThresholdBytes = int.MaxValue);
34+
_compressedServices = Build(_ => { });
35+
_plain = ValueSerializerRegistration.BuildRegistry(_plainServices).Entries.Single().Serializer;
36+
_compressed = ValueSerializerRegistration.BuildRegistry(_compressedServices).Entries.Single().Serializer;
37+
_value = Payload.OfSize(Bytes);
38+
_plainBytes = Write(_plain, out _);
39+
_compressedBytes = Write(_compressed, out _compressedId);
40+
Console.WriteLine($"size {Bytes}: plain {_plainBytes.Length}, compressed {_compressedBytes.Length} (id 0x{_compressedId:X2})");
41+
}
42+
43+
[GlobalCleanup]
44+
public void Cleanup()
45+
{
46+
_plainServices.Dispose();
47+
_compressedServices.Dispose();
48+
}
49+
50+
[BenchmarkCategory("Write"), Benchmark(Baseline = true)]
51+
public int Write_Plain()
52+
{
53+
_target.ResetWrittenCount();
54+
return _plain.Serialize(_value, _target);
55+
}
56+
57+
[BenchmarkCategory("Write"), Benchmark]
58+
public int Write_Compressed()
59+
{
60+
_target.ResetWrittenCount();
61+
return _compressed.Serialize(_value, _target);
62+
}
63+
64+
[BenchmarkCategory("Read"), Benchmark(Baseline = true)]
65+
public Payload? Read_Plain() => _plain.Deserialize<Payload>(CacheValueFormats.MessagePack, new ReadOnlySequence<byte>(_plainBytes));
66+
67+
[BenchmarkCategory("Read"), Benchmark]
68+
public Payload? Read_Compressed() => _compressed.Deserialize<Payload>(_compressedId, new ReadOnlySequence<byte>(_compressedBytes));
69+
70+
private static ServiceProvider Build(Action<MessagePackValueSerializerOptions> configure) =>
71+
new ServiceCollection()
72+
.AddCaching(b => b.AddMessagePackSerializer(configure: configure), o => o.AppShortName = "bench")
73+
.BuildServiceProvider();
74+
75+
private byte[] Write(ICacheValueSerializer serializer, out int id)
76+
{
77+
var target = new ArrayBufferWriter<byte>();
78+
id = serializer.Serialize(_value, target);
79+
return target.WrittenMemory.ToArray();
80+
}
81+
82+
public sealed class Payload
83+
{
84+
public List<Row> Rows { get; set; } = [];
85+
86+
public static Payload OfSize(int bytes)
87+
{
88+
var payload = new Payload();
89+
var random = new Random(42);
90+
string[] statuses = ["active", "pending", "suspended", "closed"];
91+
for (var size = 0; size < bytes; size += 60)
92+
{
93+
payload.Rows.Add(new Row
94+
{
95+
Id = payload.Rows.Count,
96+
Name = $"customer-{random.Next(100_000)}",
97+
Status = statuses[random.Next(statuses.Length)],
98+
Amount = Math.Round(random.NextDouble() * 1000, 2),
99+
Created = new DateTime(2026, 1, 1, 0, 0, 0, DateTimeKind.Utc).AddMinutes(random.Next(500_000)),
100+
});
101+
}
102+
103+
return payload;
104+
}
105+
}
106+
107+
public sealed class Row
108+
{
109+
public int Id { get; set; }
110+
111+
public string? Name { get; set; }
112+
113+
public string? Status { get; set; }
114+
115+
public double Amount { get; set; }
116+
117+
public DateTime Created { get; set; }
118+
}
119+
}

‎benchmarks/UiPath.Caching.Benchmarks/SerializerBenchmark.cs‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,11 @@
22
using System.Text.Json;
33
using BenchmarkDotNet.Attributes;
44
using BenchmarkDotNet.Configs;
5+
using Microsoft.Extensions.DependencyInjection;
56
using Microsoft.Extensions.Logging.Abstractions;
67
using StackExchange.Redis;
78
using UiPath.Caching.Config;
9+
using UiPath.Caching.MessagePack;
810
using UiPath.Caching.Policies;
911
using UiPath.Caching.Redis;
1012
using UiPath.Caching.Serialization;
@@ -109,3 +111,84 @@ private sealed class UnusedSerializer : ICacheValueSerializer
109111
public T? Deserialize<T>(int formatId, ReadOnlySequence<byte> source) => throw new NotSupportedException();
110112
}
111113
}
114+
115+
/// <summary>The same cache read and write under a policy that names <c>json</c> or <c>messagepack</c>, so the rows compare size, time and allocation of the two formats through <see cref="RedisCache"/>.</summary>
116+
[MemoryDiagnoser]
117+
[GroupBenchmarksBy(BenchmarkLogicalGroupRule.ByCategory)]
118+
[CategoriesColumn]
119+
public class MessagePackSerializerBenchmark
120+
{
121+
private static readonly TimeSpan Expiration = TimeSpan.FromMinutes(30);
122+
123+
private CustomObject _obj = default!;
124+
private FakeRedisConnector _redis = default!;
125+
private RedisCache _cache = default!;
126+
private ServiceProvider _services = default!;
127+
private CachePolicy _policy = default!;
128+
129+
[Params("Small", "Medium", "Large")]
130+
public string Size { get; set; } = "Medium";
131+
132+
[Params("json", "messagepack")]
133+
public string Format { get; set; } = "json";
134+
135+
[GlobalSetup]
136+
public void Setup()
137+
{
138+
_obj = Size switch
139+
{
140+
"Small" => CustomObject.RandomSmall(),
141+
"Large" => CustomObject.RandomLarge(),
142+
_ => CustomObject.RandomMedium(),
143+
};
144+
_services = new ServiceCollection()
145+
.AddCaching(b => b.AddMessagePackSerializer(), o => o.AppShortName = "bench")
146+
.BuildServiceProvider();
147+
var registry = ValueSerializerRegistration.BuildRegistry(_services);
148+
_policy = new CachePolicy { Serializer = new SerializerPolicy { Write = Format } };
149+
_redis = new FakeRedisConnector();
150+
_cache = new RedisCache(
151+
_redis,
152+
new SystemJsonByteSerializerProxy(),
153+
EmptyResiliencePipelineProvider.Instance,
154+
NullTelemetryProvider.Instance,
155+
new RedisCacheOptions(),
156+
new CacheOptions { AppShortName = "bench" },
157+
new DefaultCachePolicyFactory(null, null, valueSerializers: registry),
158+
TimeProvider.System,
159+
NullLogger<RedisCache>.Instance)
160+
{
161+
ValueSerializers = registry,
162+
};
163+
_cache.SetAsync("bench:format", _obj, Expiration, _policy).AsTask().GetAwaiter().GetResult();
164+
var written = new ArrayBufferWriter<byte>();
165+
if (Format == "json")
166+
{
167+
written.Write(JsonSerializer.SerializeToUtf8Bytes(_obj));
168+
}
169+
else
170+
{
171+
registry.Entries.Single().Serializer.Serialize(_obj, written);
172+
}
173+
174+
if (_cache.GetAsync<CustomObject>("bench:format", _policy).AsTask().GetAwaiter().GetResult() is null)
175+
{
176+
throw new InvalidOperationException("The fake connector did not serve the read");
177+
}
178+
179+
Console.WriteLine($"{Size} {Format}: {written.WrittenCount} bytes");
180+
}
181+
182+
[GlobalCleanup]
183+
public void Cleanup()
184+
{
185+
_redis.Dispose();
186+
_services.Dispose();
187+
}
188+
189+
[BenchmarkCategory("Get"), Benchmark]
190+
public ValueTask<CustomObject?> Get() => _cache.GetAsync<CustomObject>("bench:format", _policy);
191+
192+
[BenchmarkCategory("Set"), Benchmark]
193+
public ValueTask<bool> Set() => _cache.SetAsync("bench:format", _obj, Expiration, _policy);
194+
}

‎benchmarks/UiPath.Caching.Benchmarks/UiPath.Caching.Benchmarks.csproj‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
<ProjectReference Include="..\..\src\UiPath.Caching.CloudEvents\UiPath.Caching.CloudEvents.csproj" />
2121
<ProjectReference Include="..\..\src\UiPath.Caching.Polly\UiPath.Caching.Polly.csproj" />
2222
<ProjectReference Include="..\..\src\UiPath.Caching\UiPath.Caching.csproj" />
23+
<ProjectReference Include="..\..\src\UiPath.Caching.MessagePack\UiPath.Caching.MessagePack.csproj" />
2324
</ItemGroup>
2425

2526
</Project>

‎docs/how-to/extending.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -518,6 +518,44 @@ inspected under them.
518518

519519
A policy that sets no `Serializer` takes the default policy's `Write`, and one that sets only `Read` does too.
520520

521+
### MessagePack
522+
523+
`UiPath.Caching.MessagePack` is a ready `ICacheValueSerializer`: MessagePack, LZ4-compressed above a size threshold. It
524+
needs no attributes on your types. In this repo's benchmarks a small object went from 172 bytes as JSON to 102 as MessagePack, a medium one from 799 to 645, and a large one from 388,780 to 277,208. Compression then cuts repetitive rows to roughly a third at 16 KB and above: 1 KB of rows 1,257 to 626 bytes, 16 KB 19,327 to 7,124, 128 KB 156,651 to 56,385.
525+
526+
```csharp
527+
services.AddCaching(
528+
b =>
529+
{
530+
b.AddRedis(_ => { });
531+
b.AddMessagePackSerializer(); // registered as "messagepack"; pass a name and a callback to change either
532+
},
533+
o => o.Policies["Sessions"] = new CachePolicy { Serializer = new SerializerPolicy { Write = "messagepack" } });
534+
```
535+
536+
Or in configuration, with the serializer registered in code: `"Policies": { "Sessions": { "Serializer": { "Write": "messagepack" } } }`.
537+
Only the policies that name it write MessagePack; every other policy keeps writing JSON.
538+
The package depends on the exact `UiPath.Caching` version it was built with, so upgrade the two together.
539+
540+
| Option | Default | Notes |
541+
|---|---|---|
542+
| `CompressionThresholdBytes` | `1024` | A value whose MessagePack bytes reach this size is compressed when that makes it smaller, so an incompressible value is stored plain. `0` tries every value, `int.MaxValue` none. |
543+
| `MaxDecompressedBytes` | `67108864` (64 MiB) | A compressed value that claims more than this uncompressed is rejected on read, as is any claim above 255 times its compressed size. Deserializing can allocate several times the decompressed size (measured up to about 8x for typed collections, more for an `object[]` of nils), so size it to available memory. It replaces `MaximumDecompressedSize` on a supplied `MessagePackSecurity`. |
544+
| `SerializerOptions` | contractless resolver, `MessagePackSecurity.UntrustedData` | Replace it to use your own resolvers. `UntrustedData` adds hash-collision-resistant comparers; the object-graph depth limit is the same as `TrustedData`. A supplied instance that carries `MessagePackSecurity.TrustedData` is switched to `UntrustedData`; to run trusted, pass your own `MessagePackSecurity` instance. Where MessagePack has no resistant comparer for a key type (`TimeSpan`, `decimal`, `Uri`, tuples, custom structs), the default comparer is used instead of failing the read. Compression set on it is ignored: the threshold decides. A resolver you supply that resolves `object` by type name (Typeless) or polymorphically reopens type confusion on bytes read from Redis. |
545+
546+
The serializer owns format ids `0x02` (plain) and `0x03` (LZ4); the id stored with each value says which, so a node reads
547+
both whatever its threshold.
548+
549+
Roll it out readers first. A node reads a format only once the serializer is registered on it, so register
550+
`AddMessagePackSerializer` on every node and finish that deploy before any policy sets `Write = "messagepack"`; a node that
551+
cannot read the value misses and regenerates it (see [rolling a serializer out](../concepts.md#rolling-a-serializer-out)).
552+
Setting `Write` back to `json` keeps values already stored as MessagePack readable while the default JSON proxy is in use; with a custom `ISerializerProxy` registered, headers are only recognized under a policy that writes a non-JSON format, so under `Write = "json"` those values go to your proxy and read as misses.
553+
554+
The default resolver is contractless, which writes a type's public property names, as JSON does. Renaming a
555+
property, or changing its type, therefore silently loses that data for values written before the change, exactly as
556+
it would with JSON: the old values read back with the new property empty. Mark a type with `[MessagePackObject]` and
557+
`[Key(n)]` to make the format independent of the names.
558+
521559
## Swapping the default factories
522560

523561
`ICacheFactory` and `ICachePolicyFactory` each have a default DI registration set up by `AddCaching` — the concrete `CacheFactory` and `DefaultCachePolicyFactory` respectively. When you need to substitute either, use the fluent `Use*Factory` extensions on `ICachingBuilder`. They internally call `Services.Replace(...)` so the swap survives the rest of the `AddCaching` pipeline (which uses `TryAddSingleton` and would otherwise lose to the default registration).

‎docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ UiPath's internal multilayer caching library. L1 in-memory + L2 Redis, cross-nod
1313
| `UiPath.Caching.OpenTelemetry` | OpenTelemetry wiring for `ICachingTelemetryProvider` (`ActivitySource` + `Meter` named `UiPath.Caching`). |
1414
| `UiPath.Caching.Azure` | Microsoft Entra ID authentication for Azure Managed Redis / Azure Cache for Redis. |
1515
| `UiPath.Caching.Queue` | Set ("queue") caches on Redis sets — `ISetCache` / `ISetCache<T>`. |
16+
| `UiPath.Caching.MessagePack` | MessagePack value serializer with LZ4 compression above a size threshold. |
1617

1718
## Pick your path
1819

0 commit comments

Comments
 (0)