From 238db50a12ffc6d406374ab81ef806834647cce1 Mon Sep 17 00:00:00 2001 From: Lyndon Maydwell Date: Wed, 11 Oct 2023 20:02:06 +1000 Subject: [PATCH 1/3] docs examples --- registry/typescript-deno/README.md | 102 ++++++++++++++++++++++------- 1 file changed, 79 insertions(+), 23 deletions(-) diff --git a/registry/typescript-deno/README.md b/registry/typescript-deno/README.md index 62e6e7cd..4a1cc4ac 100644 --- a/registry/typescript-deno/README.md +++ b/registry/typescript-deno/README.md @@ -6,11 +6,9 @@ The Typescript (Deno) Connector allows a running connector to be inferred from a The connector runs in the following manner: -* The typescript sources are assembled -* Dependencies are fetched into a vendor directory -* Inference is performed and output to schema.json -* The functions are served via HTTP locally in the background -* The connector is started in the foreground responding to requests +* Dependencies are fetched +* Inference is performed +* The functions are served via the [connector protocol](https://github.com/hasura/ndc-spec/tree/main#ndc-specification) It assumes that dependencies are specified in accordance with [Deno](https://deno.com) conventions. @@ -40,15 +38,70 @@ export function make_password_hash(pw: string): string { * Only exported functions are exposed * Functions tagged with `@pure` annotations are exposed as functions * Those without `@pure` annotations are exposed as procedures +* Optional parameters are supported +* Exceptions can be thrown and will be reported to the user + +## Function Development + +For the best user-experience you should develop your functions in the following manner: + +* Have [Deno](https://deno.com) installed +* Have [VSCode](https://code.visualstudio.com) installed +* Have the [Deno VSCode extension](https://marketplace.visualstudio.com/items?itemName=denoland.vscode-deno) installed + +An example session: + +``` +> tree +. +├── config.json +├── functions + ├── index.ts + └── schema.json + +> cat config.json +{ + "functions": "./functions/index.ts", + "vendor": "./vendor", + "preVendor": true, + "schemaMode": "INFER", + "schemaLocation": "./functions/schema.json" +} + +> cat functions/index.ts + +export function hello(): string { + return "hello world"; +} + +function foo() { +} + +> deno run --allow-sys --allow-run --allow-net --allow-read --allow-write --allow-env --watch --check https://deno.land/x/hasura_typescript_connector@0.9/mod.ts serve --configuration ./config.json +Watcher Process started. +Check https://deno.land/x/hasura_typescript_connector@0.9/mod.ts +Running Connector.start +Check file:///Users/me/hasura/ndc-typescript-deno/scratch/deno_land_test/functions/index.ts +Inferring schema with map location ./vendor +Vendoring dependencies: /Users/me/bin/binaries/deno vendor --output /Users/me/hasura/ndc-typescript-deno/scratch/deno_land_test/vendor --force /Users/me/hasura/ndc-typescript-deno/scratch/deno_land_test/functions/index.ts +Skipping non-exported function: foo +Writing schema to ./functions/schema.json +{"level":30,"time":1697018006809,"pid":89762,"hostname":"spaceship.local","msg":"Server listening at http://0.0.0.0:8100"} +``` + +Once your connector is running locally you can use the `hasura3 tunnel` commands to make it available to your cloud projects for testing. + +If you are happy with its behaviour you can deploy your connector vis `hasura3 connector` commands. + ## Deployment You will need: -* [V3 CLI](https://github.com/hasura/v3-cli) (With Logged in Session) +* [V3 CLI](https://github.com/hasura/v3-cli) (with a logged in session) * [Connector Plugin](https://hasura.io/docs/latest/hasura-cli/connector-plugin/) -* Secret service token -* A configuration file +* A connector configuration file +* Secret service token (optional) Your functions directory should be added as a volume to `/functions` @@ -60,9 +113,9 @@ Create the connector: ``` hasura3 connector create my-cool-connector:v1 \ - --github-repo-url https://github.com/hasura/ndc-typescript-deno/tree/v0.8 \ + --github-repo-url https://github.com/hasura/ndc-typescript-deno/tree/v0.9 \ --config-file config.json \ - --volume ./my-functions:/functions \ + --volume ./functions:/functions \ --env SERVICE_TOKEN_SECRET=MY-SERVICE-TOKEN ``` @@ -88,28 +141,31 @@ Include the connector URL in your Hasura V3 project metadata (hml format). Hasura cloud projects must also set a matching bearer token: ```yaml -kind: DataSource -name: sendgrid -dataConnectorUrl: +kind: DataConnector +version: v1 +definition: + name: sendgrid url: 'https://connector-9XXX7-hyc5v23h6a-ue.a.run.app' -auth: - type: Bearer - token: "SUPER_SECRET_TOKEN_XXX123" + headers: + Authorization: + value: "Bearer SUPER_SECRET_TOKEN_XXX123" ``` While you can specify the token inline as above, it is recommended to use the Hasura secrets functionality for this purpose: ```yaml -kind: DataSource -name: sendgrid -dataConnectorUrl: +kind: DataConnector +version: v1 +definition: + name: sendgrid url: 'https://connector-9XXX7-hyc5v23h6a-ue.a.run.app' -auth: - type: Bearer - token: - valueFromSecret: CONNECTOR_TOKEN + headers: + Authorization: + valueFromSecret: BEARER_TOKEN_SECRET ``` +(NOTE: This will require that the secret includes the `Bearer ` prefix.) + ## Troubleshooting From 2d1f02a7974b72300d4c55209be022480c0dabfe Mon Sep 17 00:00:00 2001 From: Lyndon Maydwell Date: Wed, 11 Oct 2023 20:08:23 +1000 Subject: [PATCH 2/3] updating URL --- registry/typescript-deno/README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/registry/typescript-deno/README.md b/registry/typescript-deno/README.md index 4a1cc4ac..6f2524f3 100644 --- a/registry/typescript-deno/README.md +++ b/registry/typescript-deno/README.md @@ -145,7 +145,8 @@ kind: DataConnector version: v1 definition: name: sendgrid - url: 'https://connector-9XXX7-hyc5v23h6a-ue.a.run.app' + url: + singleUrl: 'https://connector-9XXX7-hyc5v23h6a-ue.a.run.app' headers: Authorization: value: "Bearer SUPER_SECRET_TOKEN_XXX123" @@ -158,7 +159,8 @@ kind: DataConnector version: v1 definition: name: sendgrid - url: 'https://connector-9XXX7-hyc5v23h6a-ue.a.run.app' + url: + singleUrl: 'https://connector-9XXX7-hyc5v23h6a-ue.a.run.app' headers: Authorization: valueFromSecret: BEARER_TOKEN_SECRET From 898bcf2f67be1c4da34670a0181a5393d0f24695 Mon Sep 17 00:00:00 2001 From: Lyndon Maydwell Date: Thu, 12 Oct 2023 12:36:49 +1000 Subject: [PATCH 3/3] simplify `deno run` example --- registry/typescript-deno/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/registry/typescript-deno/README.md b/registry/typescript-deno/README.md index 6f2524f3..74958a7d 100644 --- a/registry/typescript-deno/README.md +++ b/registry/typescript-deno/README.md @@ -77,7 +77,7 @@ export function hello(): string { function foo() { } -> deno run --allow-sys --allow-run --allow-net --allow-read --allow-write --allow-env --watch --check https://deno.land/x/hasura_typescript_connector@0.9/mod.ts serve --configuration ./config.json +> deno run -A --watch --check https://deno.land/x/hasura_typescript_connector@0.9/mod.ts serve --configuration ./config.json Watcher Process started. Check https://deno.land/x/hasura_typescript_connector@0.9/mod.ts Running Connector.start