Add callback to NatsAuthOpts that allows refreshing a Token

[garrett-sutton]

Adds the following to NatsAuthOpts

• Func<Uri, CancellationToken, ValueTask<NatsAuthCred>>? AuthCredCallback

The purpose of this PR is to allow for use cases to refresh a Token, JWT, or NKey associated with their NatsConnection during a reconnect scenario.

resolves #356

[garrett-sutton]

@mtmk are you the right person to review this? Or is there someone else that might be good to reach out to? Thanks!

[mtmk]

to be consistent with other callbacks should we make this ValueTask. Can't remember if we also pass cancellation token. Also what about JWT? would that benefit from a callback like this?

[garrett-sutton]

I modified my initial commit to be a ValueTask rather than a Task: 21c6654
From what I can tell in other places, it doesn't appear that a cancellation token is passed.

In 58864dc, I added callbacks for JWT, NKey, and seed. Based on my understanding, if the JWT is being refreshed, the seed also needs to be refreshed. And the same goes with NKeys. I added unit tests to show that the callbacks will take precedence over any raw values that are set on initialization of NatsAuthOpts.

[mtmk]

@garrett-sutton could you sign your commits please?

[garrett-sutton]

@garrett-sutton could you sign your commits please?

Done. As a note, this should probably be called out in CONTRIBUTING.md. I missed this initially because I was only looking there.

[mtmk]

API usability point: should there be a single callback rather than individual ones? would there be a case where application might want to change its auth method? should we also pass in the host, is that helpful in any way?

[darkwatchuk]

+1 for single callback on this....

[garrett-sutton]

I used your latest suggestion in the other thread in beedf42 to consolidate things into a single callback.

I ended up calling the new structure a NatsAuthCred and largely chose that because you mentioned you weren't thrilled about the idea of NatsAuthKey. I'm open to other ideas on it though.

[caleblloyd]

The most recent options callback I reviewed did supply a URI and a CancellationToken as an argument

nats.net/src/NATS.Client.Core/NatsWebSocketOpts.cs

Lines 24 to 28 in caa4bef

	/// <summary>
	/// An optional async callback handler for manipulation of ClientWebSocketOptions used for WebSocket connections.
	/// Implementors should use the passed CancellationToken for async operations called by this handler.
	/// </summary>
	public Func<Uri, ClientWebSocketOptions, CancellationToken, ValueTask>? ConfigureClientWebSocketOptions { get; init; } = null;

API usability point: should there be a single callback rather than individual ones?

Sounds like a good idea, a signature could be

In NatsAuthOpts:

   Func<Uri, CancellationToken, ValueTask<NatsAuthOpts>? Callback { get; init; } = null;

This would have to come with the caveat that a Callback could not return another NatsOptsAuth with a Callback

Or in NatsOpts:

   Func<Uri, CancellationToken, ValueTask<NatsAuthOpts>? AuthOptsCallback { get; init; } = null;

Could also be a slipper slope though, what other options could be updated between reconnects? And which ones could be updated after knowing the URI that will be connected to? Is it worth putting just the auth ones in now, or coming up with a broader approach to allow for updating all potential options

[mtmk]

Yes we have started to pass in CT in our callbacks only recently so we should carry on with that. I agree passing back the whole NatsAuthOpts is tricky. I was thinking of a simpler enum with a new type:

enum NatsAuthType { Token, Jwt, NKey, Seed }

struct NatsAuthKey(NatsAuthType type, string Value)

Func<Uri, CancellationToken, ValueTask<NatsAuthKey>? AuthKeyCallback { get; init; } = null;

I feel name AuthKey may not be the name we end up with but this structure would be my proposal.

[garrett-sutton]

Yes we have started to pass in CT in our callbacks only recently so we should carry on with that. I agree passing back the whole NatsAuthOpts is tricky. I was thinking of a simpler enum with a new type:

enum NatsAuthType { Token, Jwt, NKey, Seed }

struct NatsAuthKey(NatsAuthType type, string Value)

Func<Uri, CancellationToken, ValueTask<NatsAuthKey>? AuthKeyCallback { get; init; } = null;

I feel name AuthKey may not be the name we end up with but this structure would be my proposal.

I like this approach. One follow-up question though. For using something like this, do we actually need to return an array of NatsAuthKey from the callback?

I expect that if the JWT or the NKey change that the Seed should also change. Is that correct? If so, I think we need to provide a way for implementers to specify that multiple things need to be updated.

[mtmk]

Yes we have started to pass in CT in our callbacks only recently so we should carry on with that. I agree passing back the whole NatsAuthOpts is tricky. I was thinking of a simpler enum with a new type:

enum NatsAuthType { Token, Jwt, NKey, Seed }

struct NatsAuthKey(NatsAuthType type, string Value)

Func<Uri, CancellationToken, ValueTask<NatsAuthKey>? AuthKeyCallback { get; init; } = null;

I feel name AuthKey may not be the name we end up with but this structure would be my proposal.

I like this approach. One follow-up question though. For using something like this, do we actually need to return an array of NatsAuthKey from the callback?

I expect that if the JWT or the NKey change that the Seed should also change. Is that correct? If so, I think we need to provide a way for implementers to specify that multiple things need to be updated.

you're right. we'd need to pass seed/secret next to value. how about this?

enum NatsAuthType { Token, Jwt, NKey, UserInfo }
 
struct NatsAuthKey(NatsAuthType type, string Value, string Secret)

[caleblloyd]

you're right. we'd need to pass seed/secret next to value. how about this?

I think the combination of things they may want to supply is:

• Username + Password at same time
• Token
• Seed (from which we can derive the NKey, so no need to really supply the NKey)
• Jwt + Seed at same time
• NkeyFile
• CredsFile
• No Auth

Too bad TypeUnions aren't in C# yet, it'd be nice to have records for

• NatsAuthenticator.UsernamePassword(string Username, string Password)
• NatsAuthenticator.Token(string Token)
• NatsAuthenticator.NKey(string Seed)
• NatsAuthenticator.Jwt(string Jwt, string Seed)
• NatsAuthenticator.NkeyFile(string NKeyFile)
• NatsAuthenticator.CredsFile(string CredsFile)

[caleblloyd]

NKeys and Seeds are a pair. It was probably a mistake in the initial implementation to require passing both, as the NKey can be derived from the seed. I guess it acts as a discriminator so we can tell it apart from JWT + Seed

[garrett-sutton]

In the latest, I used the "add a seed" and we can derive the nkey from it approach: 21c5e74

[caleblloyd]

JWTs and Seeds are a pair, the Sub in the JWT is the public NKey for the seed

[garrett-sutton]

In the static factory methods, I implemented it such that you need to input the jwt and seed for jwt auth but only the seed for nkey auth: 21c5e74

[mtmk]

you're right. we'd need to pass seed/secret next to value. how about this?

I think the combination of things they may want to supply is:

• Username + Password at same time
• Token
• Seed (from which we can derive the NKey, so no need to really supply the NKey)
• Jwt + Seed at same time
• NkeyFile
• CredsFile
• No Auth

Too bad TypeUnions aren't in C# yet, it'd be nice to have records for

• NatsAuthenticator.UsernamePassword(string Username, string Password)
• NatsAuthenticator.Token(string Token)
• NatsAuthenticator.NKey(string Seed)
• NatsAuthenticator.Jwt(string Jwt, string Seed)
• NatsAuthenticator.NkeyFile(string NKeyFile)
• NatsAuthenticator.CredsFile(string CredsFile)

that's good analysis! I'm happy with the name NatsAuthenticator (see edit). we can achieve the same syntax using the above enum + struct combo with these static helpers. One question about JWTs: does the seed change as well or just JWT in which case we could have an overload for that:

enum NatsAuthType { None, Token, Jwt, UserInfo, CredFile .... }

struct NatsAuthenticator
{
    NatsAuthType _type;
    string? _value;
    string? _secret;

    private NatsAuthenticator(NatsAuthType, string?, string?) { ... }
    
    public static NatsAuthenticator NoAuth() { ... }

    public static NatsAuthenticator UsernamePassword(string Username, string Password) { ... }

    public static NatsAuthenticator Token(string Token) { ... }

    public static NatsAuthenticator Jwt(string Jwt, string Seed) { ... }

    public static NatsAuthenticator Jwt(string Jwt) { ... } // maybe?

    ...
}

EDIT: actually just scanned through the changes quick. I feel NatsAuthCred and AuthCredCallback are more inline with our minimalist naming scheme.

[mtmk]

We should take in CT from above as param and use it here. if we need the timeout we should link the tokens. The idea is if we're e.g. shutting down callbacks should get the signal as well and quit whatever they might be doing and not hanging.

[garrett-sutton]

A question about this. I don't necessarily object to this comment, but I'm not sure of whether 1) we need the timeout and if we do 2) what token to link it to. 3) Otherwise, I'm not sure if it is just OK to pass in CancellationToken.None to this method?

Do you have thoughts on these points?

I took the current approach because it seems to be what other AuthenticateAsync type methods did (i.e. sslConnection.AuthenticateAsClientAsync

[mtmk]

We should use a private .ctor and hide the fields. We can expose static factory methods as public only to minimize the API surface not exposing internals.

edit: also I'm guessing it can be a readonly struct

[garrett-sutton]

This is done in 21c5e74