[FEATURE] ⚙️ Add options to change some string internals (used for cache keys + backplane channel)

[jodydonetti]

Problem

With some new and upcoming stuff (can't wait 🙂) something emerged: in some 3rd party distributed cache/backplane implementations there can be a series of special characters that are either not supported or have reserved, with a special meaning.

In the case of NATS we are talking about chars like "*", "!", "." and so on, which are reserved.

So what is emerging is the need to have the ability to change some of the internal strings used by FusionCache, both for cache keys and the backplane channel name.

Solution

I'll add some new options in the FusionCacheOptions type (so global per-cache instance, not per-key because it doesn't make sense) to allow changing the strings used internally by FusionCache: this will allow a clean result with some new integrations.

A note for 3rd parties

I think 3rd party implementers should anyway employ some sort of options to control how to deal with invalid/reserved characters, like in the case of NATS with "*", "!", "." and so on.

My personal idea for them is to offer an option like SpecialCharsHandlingMode or similar name, with 3 modes that come to mind:

• Error: in case of undesired chars, throws a specific exception
  • PROS: any problematic char can be spotted immediately, and if used with o11y this can reduce the time to fix. Also, the input ends up in the distributed cache exactly as-is, debugging sessions are "transparent"
  • CONS: in case of undesired chars the normal flow will be broken
• Normalize/Encode (default): in case of undesired chars, normalize them to something valid (eg: "*" -> "__star", etc). Not that it's strictly needed, but If this can be done in a bidirectional way it would be kinda like the encode/decode flow that happens with some chars in a url (eg: space char " " -> "%20" etc), but this is not mandatory
  • PROS: any problematic char can be automatically "fixed", so the normal flow will be never broken
  • CONS: the input does not necessarily end up in the distributed cache exactly as-is, so in some (not frequent) cases debugging sessions may be less "transparent". For example, the input is "ab:c" and in L2 ends up as "ab__colon__c" (or whatever). Finally, depending on the normalization scheme, there may be collisions (although reasonably rare) and the final normalized size will be slightly bigger
• Base64 (or similar): the entire string (either cache key or channel) is converted to base64 or something like this, so that it doesn't matter the input, it will always be turned into something valid
  • PROS: any problematic char can be automatically "fixed", so the normal flow will be never broken
  • CONS: the input will never end up in the distributed cache exactly as-is, so debugging sessions will be harder and less "transparent". For example, the input is "ab:c" will become something like "TWFueSBoYW5kcyBtYWtlIGxpZ2h0IHdvcmsu" (or whatever). There will not collisions, but the final encoded size will be around 33% bigger

This is just some ideas I like to share, of course implementers can choose what they want.

A question can be: if 3rd parties will in fact implement some sort of transformation, why the need to customize the internal strings inside FusionCache? Because at least the "starting point" can be made as clear as possible, and in case a user will pick the Error mode (if so implemented) they can know what a mistake has been made on their side (where they have total control), and not on FusionCache (where they would not have total control).

Another thing is that even with the new options to configure the internal strings, although FusionCache can be configured TODAY with the right ones, in the future I may come up with newer ones, so AFTER a new release of FusionCache but BEFORE the new release of the 3rd party package problems may happen. Because of this, I think the default mode should be Normalize (or whatever name will be picked).

Something important though is that any transformation MUST remain internal to the 3rd party system only: in practice this means that when FusionCache asks a backplane implementation to send a notification for a key "foo/bar?*!", the backplane MUST send a notification for precisely that key so that other FusionCache instances receiving those notifications can reason about them and handle them correctly.

[jodydonetti]

Tagging @stebet , since he's doing all the work for NATS.

[stebet]

I'm a fan of all of these really but a generic Encode method sounds best to me. If people want to replace characters, Base64 or whatever it's really up to them.

[jodydonetti]

Hi @stebet , so the NATS part will change the internal strings and allow for some Encode lambda to be specified, right?

The thing I'm thinking about though is this part:

Another thing is that even with the new options to configure the internal strings, although FusionCache can be configured TODAY with the right ones, in the future I may come up with newer ones, so AFTER a new release of FusionCache but BEFORE the new release of the 3rd party package problems may happen. Because of this, I think the default mode should be Normalize (or whatever name will be picked).

Let's say months from now I'll need to add a new "__fc:whatever" special cache key: I'll add it, expose it via an option, release the new version, and people using the NATS part will start getting errors.

Thoughts?

[stebet]

I don't think there is a way around that unless you somehow make these special characters part of the implementation interfaces, which would force implementers to release a new version when new ones are added, making adding new special cache keys a breaking change.

[jodydonetti]

As said my idea to tackle it with a combination of 2 things:

• OPTIONS: this allows to exactly pick the specific strings to use, to have granular control
• TRANSFORM: (eg: Normalize/Encode from above) this would ensure that, even if some specific string has not been configured (for example because introduced in a later version), it would still work by replacing specials chars with something else "safe"

My 2 cents, and anyway again: up to 3rd parties, of course.

[stebet]

Sounds great to me :)

[jodydonetti]

I'm on this, will update soon!

[jodydonetti]

Update: it's working well locally, I'm now playing with different shapes to pick the best one, and I'm also thinking about ready-made facilities for 3rd parties to work on it in the most easy and future-proof way.

Will update asap 💪

[jodydonetti]

Ok here's an update (mind you, no new package version published yet).

I just finished pushing the changes and now all the internal strings used by FusionCache have been put inside of a new FusionCacheInternalStrings class (see here), which is used by a new InternalStrings option (see here) on the FusionCacheOptions class.

Of course for backward compatibility I kept the default values the same, but now it's possible to change them manually.

Manual Setup

Now, changing them manually would give total control, but at the same time it would mean that if I'll add a new one in the future, and that new one may use a reserved character, it would most probably create problem.

Easy Setup

So, to avoid this problem, I also created a SetToLimited() method (see here) that accepts 2 optional parameters (separator which defaults to '-' and specialChar which defaults to '_') to automatically set all the internal strings to using only Latin alphanumeric characters + the separator/special char.

This means that if a 3rd party is not strictly interested to set each internal string specifically, but more on making sure that the characters used kinda "safe", by using this helper method they can just do that with the added benefit that, if I'll add new internal strings in the future, I'll also make sure to update that method so that also the new ones will use the restricted set of characters, making the approach totally future proof.

Makes sense?

Naming Is Hard etc

I published the updated code as soon as possible so that 3rd parties can play with it, but there's one small thing to keep in mind:

Note

The name of the method "SetToLimited" is not 100% final, since naming is hard etc and I'm not yet fully convinced of it (any idea?). Anyway when I'll publish the new version, rest assured I'll fix it in stone so no worries about it.

Again it's nothing really, a miniscule thing, but I prefer to say that upfront.

Let me know what you think, thanks!

[jodydonetti]

Oh, I almost forgot: a test that uses the new feature canbe seen here, and more precisely the call to setup the limited strings can be seen here.

[jodydonetti]

Hi all, v2.3.0 is finally out 🥳