Phil/gql alert subs

[psFried]

Description:

Resolves #2589
Adds GraphQL queries and mutations for alert subscriptions, along with flowctl subcommands for managing alert subscriptions.

The graphql api is basic CRUD, and it treats the (prefix, email) as a unique key, so you can't have multiple subscriptions with the same prefix and email. This isn't strictly a technical requirement, since we already need to deduplicate the emails when sending notifications (because multiple subscriptions with different prefixes could still match the same alert).

One of the considerations in this design was trying to accommodate for webhook deliveries, which we plan to support soon. My thinking here is that we would make both email and webhook optional parameters of createAlertSubscription, and just require that one of them is provided. I added a destination field to AlertSubscription, which can represent both email and webhook destinations (and any future delivery mechanisms) as a URI. This is kind of speculative, and something we may wish to change once we actually start supporting multiple different delivery mechanisms. Please feel free to suggest better ideas.

Workflow steps:

The flowctl UX is slightly simpler, and mutations are done using either subscribe or unsubscribe commands. Subscribe will either add a new subscription, or add new alert types to an existing subscription. It never removes alert types. Unsubscribe similarly will either remove specific alert types from an existing subscription, or else remove the entire subscription.

All of the subcommands accept an optional --prefix argument. If not provided, we try to determine the prefix automatically, similar to how we do it for catalog list (the logic from there is now shared). The notable difference is that alert-subscriptions subcommands will require an explicit --prefix argument if the user has access to more than a single top-level prefix, whereas catalog list will use up to 5 prefixes by default.

Similarly, the --email argument is optional for subscribe and unsubscribe. If not provided, we parse the user's auth token claims and attempt to use the email from there as a default.

A goal was to keep the UX as simple as possible for basic use cases. So most new users could simply run flowctl alert-subscriptions (un)subscribe without additional arguments in order to start or stop receiving notifications. Here's the help messages for each of the subcommands (slightly abbreviated):

subscribe:

Subscribe to start receiving alerts, or alter an existing subscription to change which alert types it applies to

Usage: flowctl alert-subscriptions subscribe [OPTIONS]

Options:
      --email <EMAIL>            The email address you wish to subscribe. Provided as a plain address only, like `foo@example.test`. Defaults to the email address of the logged in user, if known
      --prefix <PREFIX>          The catalog prefix of the alerts you wish to subscribe to. This can be the tenant prefix (e.g. `acmeCo/`) or something more specific like `acmeCo/prod/sources/`
      --alert-type <ALERT_TYPE>  Add a subscription only for the specific alert type given by this argument. May be provided multiple times in order to subscribe to multiple alert types. If not provided, a comprehensive default list of alert types will be used [possible values: auto_discover_failed, shard_failed, data_movement_stalled, free_trial, free_trial_ending, free_trial_stalled, missing_payment_method]
      --detail <DETAIL>

unsubscribe:

Stop recieving alerts, either for a subset of alert types or everything

Usage: flowctl alert-subscriptions unsubscribe [OPTIONS]

Options:
      --prefix <PREFIX>          The catalog prefix of the alert subscription you wish to update. This is optional only if the user has access to only a single catalog prefix, in which case we'll use that prefix by default
      --email <EMAIL>            The email address you wish to unsubscribe. Provided as a plain address only, like `foo@example.test`. Defaults to the email address of the logged in user, if known
      --alert-type <ALERT_TYPE>  Remove only the specified alert type, leaving subscriptions for other alert types in place. May be provided multiple times in order to unsubscribe from multiple alert types. If not provided, then all alert types will be unsubscribed [possible values: auto_discover_failed, shard_failed, data_movement_stalled, free_trial, free_trial_ending, free_trial_stalled, missing_payment_method]

list:

Lists all the alert subscriptions under the given prefix

Usage: flowctl alert-subscriptions list [OPTIONS]

Options:
      --prefix <PREFIX>

Documentation links affected:

This didn't seem worth adding to the flowctl concepts page, but LMK if you disagree.

[jgraettinger]

LGTM % comments