[BUG] No documentation for FusionCacheInternalStrings

[Eshva]

Describe the bug

There is no documentation for FusionCacheInternalStrings class and its properties.

To Reproduce

Just try to find mentions for DistributedCacheWireFormatSeparator in this repository.

Expected behavior

A clear and concise description of FusionCacheInternalStrings present in docs.

Additional context

I implemented 2 IDistributedCache providers using key-value and object storages provided by NATS message bus. Key-value storage have some restrictions on characters could be used as entry keys. In short it should pass this regex: \A[-/_=\.a-zA-Z0-9]+\z. You actively use colon : in entry keys and I had hard time to find info about how to change these separators and prefixes. I found it only with help of Google search AI. It's even more challenging because you actively use cache entries to expire and remove entries (or something like that) with cryptic names like K:ab*. Anyway it's a very good library and I thank you for your contribution.

By the way I solved my problem with such code:

    services.AddFusionCache(CacheNames.Thumbnails)
      .WithOptions(options => options.InternalStrings = new FusionCacheInternalStrings {
        DistributedCacheWireFormatSeparator = "=WIRE=",
        CacheKeyPrefixSeparator = "=KEY=",
        TagCacheKeyPrefix = "=TAG=",
        BackplaneChannelNameSeparator = "=NAME=",
        BackplaneWireFormatSeparator = "=FORMAT=",
        ClearExpireTag = "_EXPIRE_",
        ClearRemoveTag = "_REMOVE_"
      })
...

[jodydonetti]

Hi @Eshva , you're right. I did not have time yet to add specifics docs for that.

I'll add a dedicated page for all the internal strings used in FusionCache, both for the cache keys and for the backplane, to group them all together (like, prefix, wire format versioning, etc).

Btw meanwhile I would suggest you take a read here, and in particular here:

Using SetToSafeStrings(...) would make your needed changes more future-proof.

Hope this helps, let me know.

[jodydonetti]

Oh, also, since you mentioned this effort:

I implemented 2 IDistributedCache providers using key-value and object storages provided by NATS message bus. Key-value storage have some restrictions on characters could be used as entry keys. In short it should pass this regex: \A[-/_=\.a-zA-Z0-9]+\z. You actively use colon : in entry keys and I had hard time to find info about how to change these separators and prefixes. I found it only with help of Google search AI. It's even more challenging because you actively use cache entries to expire and remove entries (or something like that) with cryptic names like K:ab*. Anyway it's a very good library and I thank you for your contribution.

First thing: that's an awesome idea!

I just wanted to point out this PR, where community user @stebet already created a NATS-based implementation of the backplane, and I have to finish reviewing it and merge it. It's a bit more difficult to merge because he also included a couple of changes to some core abstractions, in an effort to improve the library even more related to perf/allocations.

Btw he already created and published an IDistributedCache impl for NATS, see here.

Maybe there can be some inspirations or collaboration?

[Eshva]

First thing: that's an awesome idea!

I just wanted to point out this PR, where community user @stebet already created a NATS-based implementation of the backplane, and I have to finish reviewing it and merge it. It's a bit more difficult to merge because he also included a couple of changes to some core abstractions, in an effort to improve the library even more related to perf/allocations.

Btw he already created and published an IDistributedCache impl for NATS, see here.

Maybe there can be some inspirations or collaboration?

Thank you pointing me to this repo. I've quickly checked this code and I don't like it. First of all it isn't legitimate implementation of IDistributedCache, it breaks LSP. MS distributed cache implementation should support some behavior: sliding expiry and absolute expiry. This implementation doesn't support sliding expiry. The second point it uses TTL of NATS KV-entries. NATS doesn't support changing of entry TTL. I also evaluated TTL but very soon understood that it's a bad idea to use it in this regard. The only solution to fully provide behavior of MS distributed cache using NATS KV-storage is to use 2 storages: one for data and another for metadata. Object storage based variant doesn't need it because its entries have metadata attached.

I will investigate his solution more closely and give him my feedback in 'discussions' section.

I factored out time-related logic and base cache implementation into different package with abstractions (Eshva.Caching.Abstractions). Now I can implement other distributed caches with other providers very quick and easy. I have to add some documentation for both my caching packages but I just finished them and now give it a dry-run in my photo-site project fixing some bugs I found through this.