From ccc734fbe7dbfcba745ee1190efb849365f94cc4 Mon Sep 17 00:00:00 2001 From: Vamshi Surabhi Date: Thu, 1 Feb 2024 17:06:56 -0800 Subject: [PATCH 1/4] rfc: rough guidelines for cli plugins --- rfcs/0002-cli-guidelines.md | 53 +++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 rfcs/0002-cli-guidelines.md diff --git a/rfcs/0002-cli-guidelines.md b/rfcs/0002-cli-guidelines.md new file mode 100644 index 00000000..1b04fe61 --- /dev/null +++ b/rfcs/0002-cli-guidelines.md @@ -0,0 +1,53 @@ +### CLI Plugin Guidelines + +Connectors can optionally provide a CLI plugin to help with author the +connector's configuration. These are the broad categories of commands that +could be useful: + +1. init (optional) + + Initializing the config directory for a connector. There could be + more than one template. + + Let's ignore this for now (out of beta's scope) as the cli's `add + ConnectorManifest` would also initialize the connector's config from the + connector's default template. + +2. update + + A category of commands that modifies connector's config. For example, when + working on Postgres, you may want to introspect the database and import all + the tables into the connector's config. + + These are just some examples (they are in no way prescriptive of what the + exact interface should be): + + ```bash + # 1. Imports the database and updates all the tables that are # not in pg_* + schemas or information_schema + # 2. Will also preserve the user written native queries + update-config --replace + + # Same as above but is restricting the introspection to 'public' schema + update-config --include-schema public + ``` + + The idea is that the user would specify a specific incantation of the update + command that cli would then call at a fixed interval when the user invokes + `h3 dev`. + + > [!NOTE] + > In the case of Postgres connector, the whole `configureOptions` section + > goes away from the connector's config because that doesn't affect the + > NDC interface's behaviour and ideally part of update-config's arguments + +3. validate + + This should help validate the config for the connector. Note that the + connector's deployment fails if the config is invalid. However for a user it + may be easier to have a command that validates the config before it is + deployed. It isn't strictly necessary for beta but a nice to have. + + In future, you could also have specific commands to validate parts of the + config such as native queries. + From 4d48c565e7536c8db184838a798092a7d3bf0490 Mon Sep 17 00:00:00 2001 From: Sandeep Date: Sun, 18 Feb 2024 13:08:39 +0530 Subject: [PATCH 2/4] Add Plugin Invocation Spec --- rfcs/0002-cli-guidelines.md | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/rfcs/0002-cli-guidelines.md b/rfcs/0002-cli-guidelines.md index 1b04fe61..0b9c5e21 100644 --- a/rfcs/0002-cli-guidelines.md +++ b/rfcs/0002-cli-guidelines.md @@ -32,10 +32,6 @@ could be useful: update-config --include-schema public ``` - The idea is that the user would specify a specific incantation of the update - command that cli would then call at a fixed interval when the user invokes - `h3 dev`. - > [!NOTE] > In the case of Postgres connector, the whole `configureOptions` section > goes away from the connector's config because that doesn't affect the @@ -51,3 +47,27 @@ could be useful: In future, you could also have specific commands to validate parts of the config such as native queries. +4. watch + + This is basically (for the most common use case) the update command run on loop. + This could also be a totally different implementation. This is a convenience + command for the CLI to use during `h3 dev` so that the CLI can invoke this once, + and terminate it once the `dev` command has ended. + +#### Inputs to the Plugin Invocation + + The main CLI invokes the above commands as sub-processes and passes all the Environment + variables specified in the `ConnectorManifest` (for eg. in the case of postgres, it will + pass `PG_URL` , etc) to the Plugin. In addition to these Env vars, the main CLI passes + the following ENV vars: + - `HASURA_PLUGIN_DDN_PAT` (string)- the PAT token which can be used to make authenticated + calls to Hasura Cloud. + - `HASURA_PLUGIN_DISABLE_TELEMETRY` (boolean string, `true` or `false`) - If the plugins + are sending any sort of telemetry back to Hasura, it should be disabled if this is `true`. + - `HASURA_PLUGIN_INSTANCE_ID` (string) - A UUID for every unique user. Can be used in + telemetry. + - `HASURA_PLUGIN_EXECUTION_ID` (string) - A UUID unique to every invocation of Hasura CLI. + - `HASURA_PLUGIN_LOG_LEVEL` (string) - Can be one of [these](https://github.com/rs/zerolog?tab=readme-ov-file#leveled-logging) + log levels. + - `HASURA_PLUGIN_CONNECTOR_CONTEXT_PATH` (string) - Fully qualified path to the context + directory of the connector. \ No newline at end of file From 7e98529fb04ca2e30864dd2479b3b4cd24d85355 Mon Sep 17 00:00:00 2001 From: Sandeep Date: Sun, 18 Feb 2024 13:10:29 +0530 Subject: [PATCH 3/4] Fix indent --- rfcs/0002-cli-guidelines.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/rfcs/0002-cli-guidelines.md b/rfcs/0002-cli-guidelines.md index 0b9c5e21..542b3c0b 100644 --- a/rfcs/0002-cli-guidelines.md +++ b/rfcs/0002-cli-guidelines.md @@ -60,14 +60,14 @@ could be useful: variables specified in the `ConnectorManifest` (for eg. in the case of postgres, it will pass `PG_URL` , etc) to the Plugin. In addition to these Env vars, the main CLI passes the following ENV vars: - - `HASURA_PLUGIN_DDN_PAT` (string)- the PAT token which can be used to make authenticated - calls to Hasura Cloud. - - `HASURA_PLUGIN_DISABLE_TELEMETRY` (boolean string, `true` or `false`) - If the plugins - are sending any sort of telemetry back to Hasura, it should be disabled if this is `true`. - - `HASURA_PLUGIN_INSTANCE_ID` (string) - A UUID for every unique user. Can be used in - telemetry. - - `HASURA_PLUGIN_EXECUTION_ID` (string) - A UUID unique to every invocation of Hasura CLI. - - `HASURA_PLUGIN_LOG_LEVEL` (string) - Can be one of [these](https://github.com/rs/zerolog?tab=readme-ov-file#leveled-logging) - log levels. - - `HASURA_PLUGIN_CONNECTOR_CONTEXT_PATH` (string) - Fully qualified path to the context - directory of the connector. \ No newline at end of file + - `HASURA_PLUGIN_DDN_PAT` (string)- the PAT token which can be used to make authenticated + calls to Hasura Cloud. + - `HASURA_PLUGIN_DISABLE_TELEMETRY` (boolean string, `true` or `false`) - If the plugins + are sending any sort of telemetry back to Hasura, it should be disabled if this is `true`. + - `HASURA_PLUGIN_INSTANCE_ID` (string) - A UUID for every unique user. Can be used in + telemetry. + - `HASURA_PLUGIN_EXECUTION_ID` (string) - A UUID unique to every invocation of Hasura CLI. + - `HASURA_PLUGIN_LOG_LEVEL` (string) - Can be one of [these](https://github.com/rs/zerolog?tab=readme-ov-file#leveled-logging) + log levels. + - `HASURA_PLUGIN_CONNECTOR_CONTEXT_PATH` (string) - Fully qualified path to the context + directory of the connector. \ No newline at end of file From 11be49aa671924c2f5ddcd18a3ff3cbfe9a2e5c3 Mon Sep 17 00:00:00 2001 From: Sandeep Date: Wed, 21 Feb 2024 20:34:55 +0530 Subject: [PATCH 4/4] Add CLI publishing spec --- rfcs/0002-cli-guidelines.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/rfcs/0002-cli-guidelines.md b/rfcs/0002-cli-guidelines.md index 542b3c0b..745faa4d 100644 --- a/rfcs/0002-cli-guidelines.md +++ b/rfcs/0002-cli-guidelines.md @@ -70,4 +70,14 @@ could be useful: - `HASURA_PLUGIN_LOG_LEVEL` (string) - Can be one of [these](https://github.com/rs/zerolog?tab=readme-ov-file#leveled-logging) log levels. - `HASURA_PLUGIN_CONNECTOR_CONTEXT_PATH` (string) - Fully qualified path to the context - directory of the connector. \ No newline at end of file + directory of the connector. + +#### Publishing the Plugin + The plugin details (name, version, download location, etc., what we call the plugin manifest) + should be published to the [cli-plugin-index](https://github.com/hasura/cli-plugins-index) repo. + The CLI will track the contents of the `master` branch of this repo and will be able to install + any version of the published plugin. (Version should be a CalVer of the format `YYYYMMDD` or a SemVer). + Also, we need plugin binaries for `linux/amd64`, `darwin/amd64`, `darwin/arm64`, `windows/amd64` platforms. + The name of the plugin must be `hasura-` for it to be recognized in by the CLI. + The plugin binary (preferably statically linked) should be pushed as a gzipped tarball and its URI + mentioned in the manifest for each platform. The sha256 value in the [manifest](https://github.com/hasura/cli-plugins-index/blob/master/plugins/connector/20240125/manifest.yaml) is the checksum of the gzipped tarball. \ No newline at end of file