Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)

### Added

- **`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).
- **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).

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

## Documentation

Expand Down
1 change: 1 addition & 0 deletions UiPath.Caching.slnx
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
<Project Path="src/UiPath.Caching.Analyzers/UiPath.Caching.Analyzers.csproj" />
<Project Path="src/UiPath.Caching.Azure/UiPath.Caching.Azure.csproj" />
<Project Path="src/UiPath.Caching.CloudEvents/UiPath.Caching.CloudEvents.csproj" />
<Project Path="src/UiPath.Caching.MessagePack/UiPath.Caching.MessagePack.csproj" />
<Project Path="src/UiPath.Caching.OpenTelemetry/UiPath.Caching.OpenTelemetry.csproj" />
<Project Path="src/UiPath.Caching.Polly/UiPath.Caching.Polly.csproj" />
<Project Path="src/UiPath.Caching.Queue/UiPath.Caching.Queue.csproj" />
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,8 @@ public static T Create(FakeRedisStore store)

if (method.Name == "StringSetAsync" && args is [RedisKey setKey, RedisValue value, ..])
{
_store.Values[setKey] = value;
// The caller returns a pooled buffer to its pool once the call completes, so the store keeps its own bytes.
_store.Values[setKey] = value.IsNull ? value : (byte[])value!;
_store.LastSet = setKey;
return Task.FromResult(true);
}
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
using System.Buffers;
using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Configs;
using Microsoft.Extensions.DependencyInjection;
using UiPath.Caching.Config;
using UiPath.Caching.MessagePack;
using UiPath.Caching.Serialization;

namespace UiPath.Caching.Benchmarks;

/// <summary>The MessagePack serializer with compression off against its default threshold, at three payload sizes of compressible rows.</summary>
[MemoryDiagnoser]
[GroupBenchmarksBy(BenchmarkLogicalGroupRule.ByCategory)]
[CategoriesColumn]
public class MessagePackCompressionBenchmark
{
private readonly ArrayBufferWriter<byte> _target = new();
private ServiceProvider _plainServices = default!;
private ServiceProvider _compressedServices = default!;
private ICacheValueSerializer _plain = default!;
private ICacheValueSerializer _compressed = default!;
private Payload _value = default!;
private byte[] _plainBytes = default!;
private byte[] _compressedBytes = default!;
private int _compressedId;

[Params(512, 1024, 16 * 1024, 128 * 1024)]
public int Bytes { get; set; }

[GlobalSetup]
public void Setup()
{
_plainServices = Build(o => o.CompressionThresholdBytes = int.MaxValue);
_compressedServices = Build(_ => { });
_plain = ValueSerializerRegistration.BuildRegistry(_plainServices).Entries.Single().Serializer;
_compressed = ValueSerializerRegistration.BuildRegistry(_compressedServices).Entries.Single().Serializer;
_value = Payload.OfSize(Bytes);
_plainBytes = Write(_plain, out _);
_compressedBytes = Write(_compressed, out _compressedId);
Console.WriteLine($"size {Bytes}: plain {_plainBytes.Length}, compressed {_compressedBytes.Length} (id 0x{_compressedId:X2})");
}

[GlobalCleanup]
public void Cleanup()
{
_plainServices.Dispose();
_compressedServices.Dispose();
}

[BenchmarkCategory("Write"), Benchmark(Baseline = true)]
public int Write_Plain()
{
_target.ResetWrittenCount();
return _plain.Serialize(_value, _target);
}

[BenchmarkCategory("Write"), Benchmark]
public int Write_Compressed()
{
_target.ResetWrittenCount();
return _compressed.Serialize(_value, _target);
}

[BenchmarkCategory("Read"), Benchmark(Baseline = true)]
public Payload? Read_Plain() => _plain.Deserialize<Payload>(CacheValueFormats.MessagePack, new ReadOnlySequence<byte>(_plainBytes));

[BenchmarkCategory("Read"), Benchmark]
public Payload? Read_Compressed() => _compressed.Deserialize<Payload>(_compressedId, new ReadOnlySequence<byte>(_compressedBytes));

private static ServiceProvider Build(Action<MessagePackValueSerializerOptions> configure) =>
new ServiceCollection()
.AddCaching(b => b.AddMessagePackSerializer(configure: configure), o => o.AppShortName = "bench")
.BuildServiceProvider();

private byte[] Write(ICacheValueSerializer serializer, out int id)
{
var target = new ArrayBufferWriter<byte>();
id = serializer.Serialize(_value, target);
return target.WrittenMemory.ToArray();
}

public sealed class Payload
{
public List<Row> Rows { get; set; } = [];

public static Payload OfSize(int bytes)
{
var payload = new Payload();
var random = new Random(42);
string[] statuses = ["active", "pending", "suspended", "closed"];
for (var size = 0; size < bytes; size += 60)
{
payload.Rows.Add(new Row
{
Id = payload.Rows.Count,
Name = $"customer-{random.Next(100_000)}",
Status = statuses[random.Next(statuses.Length)],
Amount = Math.Round(random.NextDouble() * 1000, 2),
Created = new DateTime(2026, 1, 1, 0, 0, 0, DateTimeKind.Utc).AddMinutes(random.Next(500_000)),
});
}

return payload;
}
}

public sealed class Row
{
public int Id { get; set; }

public string? Name { get; set; }

public string? Status { get; set; }

public double Amount { get; set; }

public DateTime Created { get; set; }
}
}
83 changes: 83 additions & 0 deletions benchmarks/UiPath.Caching.Benchmarks/SerializerBenchmark.cs
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,11 @@
using System.Text.Json;
using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Configs;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging.Abstractions;
using StackExchange.Redis;
using UiPath.Caching.Config;
using UiPath.Caching.MessagePack;
using UiPath.Caching.Policies;
using UiPath.Caching.Redis;
using UiPath.Caching.Serialization;
Expand Down Expand Up @@ -109,3 +111,84 @@ private sealed class UnusedSerializer : ICacheValueSerializer
public T? Deserialize<T>(int formatId, ReadOnlySequence<byte> source) => throw new NotSupportedException();
}
}

/// <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>
[MemoryDiagnoser]
[GroupBenchmarksBy(BenchmarkLogicalGroupRule.ByCategory)]
[CategoriesColumn]
public class MessagePackSerializerBenchmark
{
private static readonly TimeSpan Expiration = TimeSpan.FromMinutes(30);

private CustomObject _obj = default!;
private FakeRedisConnector _redis = default!;
private RedisCache _cache = default!;
private ServiceProvider _services = default!;
private CachePolicy _policy = default!;

[Params("Small", "Medium", "Large")]
public string Size { get; set; } = "Medium";

[Params("json", "messagepack")]
public string Format { get; set; } = "json";

[GlobalSetup]
public void Setup()
{
_obj = Size switch
{
"Small" => CustomObject.RandomSmall(),
"Large" => CustomObject.RandomLarge(),
_ => CustomObject.RandomMedium(),
};
_services = new ServiceCollection()
.AddCaching(b => b.AddMessagePackSerializer(), o => o.AppShortName = "bench")
.BuildServiceProvider();
var registry = ValueSerializerRegistration.BuildRegistry(_services);
_policy = new CachePolicy { Serializer = new SerializerPolicy { Write = Format } };
_redis = new FakeRedisConnector();
_cache = new RedisCache(
_redis,
new SystemJsonByteSerializerProxy(),
EmptyResiliencePipelineProvider.Instance,
NullTelemetryProvider.Instance,
new RedisCacheOptions(),
new CacheOptions { AppShortName = "bench" },
new DefaultCachePolicyFactory(null, null, valueSerializers: registry),
TimeProvider.System,
NullLogger<RedisCache>.Instance)
{
ValueSerializers = registry,
};
_cache.SetAsync("bench:format", _obj, Expiration, _policy).AsTask().GetAwaiter().GetResult();
var written = new ArrayBufferWriter<byte>();
if (Format == "json")
{
written.Write(JsonSerializer.SerializeToUtf8Bytes(_obj));
}
else
{
registry.Entries.Single().Serializer.Serialize(_obj, written);
}

if (_cache.GetAsync<CustomObject>("bench:format", _policy).AsTask().GetAwaiter().GetResult() is null)
{
throw new InvalidOperationException("The fake connector did not serve the read");
}

Console.WriteLine($"{Size} {Format}: {written.WrittenCount} bytes");
}

[GlobalCleanup]
public void Cleanup()
{
_redis.Dispose();
_services.Dispose();
}

[BenchmarkCategory("Get"), Benchmark]
public ValueTask<CustomObject?> Get() => _cache.GetAsync<CustomObject>("bench:format", _policy);

[BenchmarkCategory("Set"), Benchmark]
public ValueTask<bool> Set() => _cache.SetAsync("bench:format", _obj, Expiration, _policy);
}
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
<ProjectReference Include="..\..\src\UiPath.Caching.CloudEvents\UiPath.Caching.CloudEvents.csproj" />
<ProjectReference Include="..\..\src\UiPath.Caching.Polly\UiPath.Caching.Polly.csproj" />
<ProjectReference Include="..\..\src\UiPath.Caching\UiPath.Caching.csproj" />
<ProjectReference Include="..\..\src\UiPath.Caching.MessagePack\UiPath.Caching.MessagePack.csproj" />
</ItemGroup>

</Project>
38 changes: 38 additions & 0 deletions docs/how-to/extending.md
Original file line number Diff line number Diff line change
Expand Up @@ -518,6 +518,44 @@ inspected under them.

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

### MessagePack

`UiPath.Caching.MessagePack` is a ready `ICacheValueSerializer`: MessagePack, LZ4-compressed above a size threshold. It
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.

```csharp
services.AddCaching(
b =>
{
b.AddRedis(_ => { });
b.AddMessagePackSerializer(); // registered as "messagepack"; pass a name and a callback to change either
},
o => o.Policies["Sessions"] = new CachePolicy { Serializer = new SerializerPolicy { Write = "messagepack" } });
```

Or in configuration, with the serializer registered in code: `"Policies": { "Sessions": { "Serializer": { "Write": "messagepack" } } }`.
Only the policies that name it write MessagePack; every other policy keeps writing JSON.
The package depends on the exact `UiPath.Caching` version it was built with, so upgrade the two together.

| Option | Default | Notes |
|---|---|---|
| `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. |
| `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`. |
| `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. |

The serializer owns format ids `0x02` (plain) and `0x03` (LZ4); the id stored with each value says which, so a node reads
both whatever its threshold.

Roll it out readers first. A node reads a format only once the serializer is registered on it, so register
`AddMessagePackSerializer` on every node and finish that deploy before any policy sets `Write = "messagepack"`; a node that
cannot read the value misses and regenerates it (see [rolling a serializer out](../concepts.md#rolling-a-serializer-out)).
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.

The default resolver is contractless, which writes a type's public property names, as JSON does. Renaming a
property, or changing its type, therefore silently loses that data for values written before the change, exactly as
it would with JSON: the old values read back with the new property empty. Mark a type with `[MessagePackObject]` and
`[Key(n)]` to make the format independent of the names.

## Swapping the default factories

`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).
Expand Down
1 change: 1 addition & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ UiPath's internal multilayer caching library. L1 in-memory + L2 Redis, cross-nod
| `UiPath.Caching.OpenTelemetry` | OpenTelemetry wiring for `ICachingTelemetryProvider` (`ActivitySource` + `Meter` named `UiPath.Caching`). |
| `UiPath.Caching.Azure` | Microsoft Entra ID authentication for Azure Managed Redis / Azure Cache for Redis. |
| `UiPath.Caching.Queue` | Set ("queue") caches on Redis sets — `ISetCache` / `ISetCache<T>`. |
| `UiPath.Caching.MessagePack` | MessagePack value serializer with LZ4 compression above a size threshold. |

## Pick your path

Expand Down
Loading
Loading