diff --git a/.gitignore b/.gitignore index e3e2f7c..e5b85c9 100644 --- a/.gitignore +++ b/.gitignore @@ -3,4 +3,5 @@ .vscode/ vendor/ scratch/ -src/test/vendor \ No newline at end of file +src/test/vendor +.idea \ No newline at end of file diff --git a/README.md b/README.md index 7780bad..f029ae4 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,12 @@ -# ndc-typescript-deno +# Typescript (Deno) Connector ![image](https://github.com/hasura/ndc-typescript-deno/assets/92299/9f139964-d0ed-4c92-b01f-9fda255717d4) -The Typescript (Deno) Connector allows a running connector to be inferred from a Typescript file (optionally with dependencies). +The Typescript (Deno) Connector allows you to write your functions in Typescript and have them deployed as a Hasura DDN +connector. ![image](https://github.com/hasura/ndc-typescript-deno/assets/92299/fb7f4afd-0302-432b-b7ce-3cc7d1f3546b) -Useful Links: - * [Typescript Deno Connector on the NDC Hub](https://hasura.io/connectors/typescript-deno) * [Typescript Deno Connector on deno.com](https://deno.land/x/hasura_typescript_connector) * [Hasura V3 Documentation](https://hasura.io/docs/3.0) @@ -18,18 +17,15 @@ Useful Links: * [Native Data Connector Specification](https://hasura.github.io/ndc-spec/) * [Typescript NDC SDK](https://github.com/hasura/ndc-sdk-typescript/) +The connector runs in the following order: -## Overview - -The connector runs in the following manner: - -* Typescript sources are assembled (with `index.ts` acting as your interface definition) -* Dependencies are fetched -* Inference is performed and made available via the `/schema` endpoint -* Functions are served via the connector protocol - -Note: The Deno runtime is used and this connector assumes that dependencies are specified in accordance with [Deno](https://deno.com) conventions. +1. Typescript sources are assembled (with `index.ts` acting as your interface definition) +2. Dependencies are fetched +3. Inference is performed and made available via the `/schema` endpoint +4. Functions are served via the connector protocol +Note: The Deno runtime is used and this connector assumes that dependencies are specified in accordance with +[Deno](https://deno.com) conventions. ## Before you get Started @@ -219,7 +215,7 @@ View logs from your running connector: ## Usage -This connector is intended to be used with Hasura v3 projects. +This connector is intended to be used with Hasura DDN projects. Find the URL of your connector once deployed: @@ -260,86 +256,12 @@ hasura3 cloud build create --project-id my-project-id --metadata-file metadata.h ## Service Authentication -If you don't wish to have your connector publically accessible then you must set a service token by specifying the `SERVICE_TOKEN_SECRET` environment variable when creating your connector: - -* `--env SERVICE_TOKEN_SECRET=SUPER_SECRET_TOKEN_XXX123` - -Your Hasura project metadata must then set a matching bearer token: - -```yaml -kind: DataConnector -version: v1 -definition: - name: my_connector - url: - singleUrl: 'https://connector-9XXX7-hyc5v23h6a-ue.a.run.app' - 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: DataConnector -version: v1 -definition: - name: my_connector - url: - singleUrl: 'https://connector-9XXX7-hyc5v23h6a-ue.a.run.app' - headers: - Authorization: - valueFromSecret: BEARER_TOKEN_SECRET -``` - -NOTE: This secret should contain the `Bearer ` prefix. +Find more information on service authentication [here](./docs/authentication.md). ## Debugging Issues -Errors may arrise from any of the following: - -* Dependency errors in your functions -* Type errors in your functions -* Implementation errors in your functions -* Invalid connector configuration -* Invalid project metadata -* Connector Deployment Failure -* Misconfigured project authentication -* Misconfigured service authentication -* Insufficient query permissions -* Invalid queries -* Unanticipated bug in connector implementation - -For a botton-up debugging approach: - -* First check your functions: - * Run `deno check` on your functions to determine if there are any obvious errors - * Write a `deno test` harness to ensure that your functions are correctly implemented -* Then check your connector: - * Check that the connctor deployed successfully with `hasura3 connector status my-cool-connector:v1` - * Check the build/runtime logs of your connector with `hasura3 connector logs my-cool-connector:v1` -* Then check your project: - * Ensure that your metadata and project build were successful -* Then check end-to-end integration: - * Run test queries and view the connector logs to ensure that your queries are propagating correctly - - -## Development - -For contribution to this connector you will want to have the following dependencies: - -* [Deno](https://deno.com) -* (Optionally) [Docker](https://www.docker.com) - -In order to perform local development on this codebase: - -* Check out the repository: `git clone https://github.com/hasura/ndc-typescript-deno.git` -* This assumes that you will be testing against function in `./functions` -* Vendor the dependencies with `cd ./function && deno vendor -f index.ts` -* Serve your functions with `deno run -A --watch --check ./src/mod.ts serve --configuration <(echo '{"functions": "./functions/index.ts", "vendor": "./functions/vendor", "schemaMode": "INFER"}')` -* The connector should now be running on localhost:8100 and respond to any changes to the your functions and the connector source -* Use the `hasura3` tunnel commands to reference this connector from a Hasura Cloud project +For debugging issues with your connector, please see the [debugging guide](./docs/debugging.md). -If you are fixing a bug, then please consider adding a test case to `./src/test/data`. +## Contributing -Please [file an issue](https://github.com/hasura/ndc-typescript-deno/issues/new) for any problems you encounter during usage and development of this connector. +Check out our [contributing guide](./docs/contributing.md) for more details. diff --git a/docs/authentication.md b/docs/authentication.md new file mode 100644 index 0000000..04f378e --- /dev/null +++ b/docs/authentication.md @@ -0,0 +1,37 @@ +# Authentication + +If you don't wish to have your connector publicly accessible then you must set a service token by specifying the +`SERVICE_TOKEN_SECRET` environment variable when creating your connector: + +* `--env SERVICE_TOKEN_SECRET=SUPER_SECRET_TOKEN_XXX123` + +Your Hasura project metadata must then set a matching bearer token: + +```yaml +kind: DataConnector +version: v1 +definition: + name: my_connector + url: + singleUrl: 'https://connector-9XXX7-hyc5v23h6a-ue.a.run.app' + 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: DataConnector +version: v1 +definition: + name: my_connector + url: + singleUrl: 'https://connector-9XXX7-hyc5v23h6a-ue.a.run.app' + headers: + Authorization: + valueFromSecret: BEARER_TOKEN_SECRET +``` + +NOTE: This secret should contain the `Bearer ` prefix. \ No newline at end of file diff --git a/docs/code-of-conduct.md b/docs/code-of-conduct.md new file mode 100644 index 0000000..03c982f --- /dev/null +++ b/docs/code-of-conduct.md @@ -0,0 +1,60 @@ +# Hasura GraphQL Engine Community Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make +participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, +disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, +socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment include: + +* Using welcoming, inclusive and gender-neutral language (example: instead of "Hey guys", you could use "Hey folks" or + "Hey all") +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take +appropriate and fair corrective action in response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, +issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any +contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the +project or its community. Examples of representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed representative at an online or offline +event. Representation of a project may be further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at +community@hasura.io. All complaints will be reviewed and investigated and will result in a response that is deemed +necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to +the reporter of an incident. Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent +repercussions as determined by other members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at +https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org \ No newline at end of file diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..2bccf25 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,59 @@ +# Contributing +_First_: if you feel insecure about how to start contributing, feel free to ask us on our [Discord +channel](https://discordapp.com/invite/hasura) in the #contrib channel. You can also just go ahead with your +contribution and we'll give you feedback. Don't worry - the worst that can happen is that you'll be politely asked to +change something. We appreciate any contributions, and we don't want a wall of rules to stand in the way of that. + +However, for those individuals who want a bit more guidance on the best way to contribute to the project, read on. This +document will cover what we're looking for. By addressing the points below, the chances that we can quickly merge or +address your contributions will increase. + +## 1. Code of conduct + +Please follow our [Code of conduct](./code-of-conduct.md) in the context of any contributions made to Hasura. + +## 2. CLA + +For all contributions, a CLA (Contributor License Agreement) needs to be signed +[here](https://cla-assistant.io/hasura/) before (or after) the pull request has been submitted. A bot will prompt +contributors to sign the CLA via a pull request comment, if necessary. + +## 3. Ways of contributing + +For contribution to this connector you will want to have the following dependencies: + +* [Deno](https://deno.com) +* (Optionally) [Docker](https://www.docker.com) + +In order to perform local development on this codebase: + +* Check out the repository: `git clone https://github.com/hasura/ndc-typescript-deno.git` +* This assumes that you will be testing against function in `./functions` +* Vendor the dependencies with `cd ./function && deno vendor -f index.ts` +* Serve your functions with `deno run -A --watch --check ./src/mod.ts serve --configuration <(echo '{"functions": "./functions/index.ts", "vendor": "./functions/vendor", "schemaMode": "INFER"}')` +* The connector should now be running on localhost:8100 and respond to any changes to your functions and the connector source +* Use the `hasura3` tunnel commands to reference this connector from a Hasura Cloud project + +If you are fixing a bug, then please consider adding a test case to `./src/test/data`. + +### Reporting an Issue + +- Make sure you test against the latest released cloud version. It is possible that we may have already fixed the bug you're experiencing. +- Provide steps to reproduce the issue, including Database (e.g. Postgres) version and Hasura DDN version. +- Please include logs, if relevant. +- Create a [issue](https://github.com/hasura/ndc-typescript-deno/issues/new/choose). + +### Working on an issue + +- We use the [fork-and-branch git workflow](https://blog.scottlowe.org/2015/01/27/using-fork-branch-git-workflow/). +- Please make sure there is an issue associated with the work that you're doing. +- If you're working on an issue, please comment that you are doing so to prevent duplicate work by others also. +- Squash your commits and refer to the issue using `fix #` or `close #` in the commit message, at the end. For example: `resolve answers to everything (fix #42)` or `resolve answers to everything, fix #42` +- Rebase master with your branch before submitting a pull request. + +## 6. Commit messages + +- The first line should be a summary of the changes, not exceeding 50 characters, followed by an optional body which has more details about the changes. Refer to [this link](https://github.com/erlang/otp/wiki/writing-good-commit-messages) for more information on writing good commit messages. +- Use the imperative present tense: "add/fix/change", not "added/fixed/changed" nor "adds/fixes/changes". +- Don't capitalize the first letter of the summary line. +- Don't add a period/dot (.) at the end of the summary line. diff --git a/docs/debugging.md b/docs/debugging.md new file mode 100644 index 0000000..4e8f1fa --- /dev/null +++ b/docs/debugging.md @@ -0,0 +1,28 @@ +# Debugging + +Errors may arise from any of the following: + +* Dependency errors in your functions +* Type errors in your functions +* Implementation errors in your functions +* Invalid connector configuration +* Invalid project metadata +* Connector Deployment Failure +* Misconfigured project authentication +* Misconfigured service authentication +* Insufficient query permissions +* Invalid queries +* Unanticipated bug in connector implementation + +For a botton-up debugging approach: + +* First check your functions: + * Run `deno check` on your functions to determine if there are any obvious errors + * Write a `deno test` harness to ensure that your functions are correctly implemented +* Then check your connector: + * Check that the connctor deployed successfully with `hasura3 connector status my-cool-connector:v1` + * Check the build/runtime logs of your connector with `hasura3 connector logs my-cool-connector:v1` +* Then check your project: + * Ensure that your metadata and project build were successful +* Then check end-to-end integration: + * Run test queries and view the connector logs to ensure that your queries are propagating correctly \ No newline at end of file diff --git a/docs/index.mdx b/docs/index.mdx new file mode 100644 index 0000000..d6da007 --- /dev/null +++ b/docs/index.mdx @@ -0,0 +1,10 @@ +# Typescript (Deno) Connector Documentation + +Typescript (Deno) Connector is a [Hasura](https://hasura.io/) Native Data Connector. + +- [Code of Conduct](./code-of-conduct.md) +- [Contributing](./contributing.md) +- [Authentication](./authentication.md) +- [Debugging](./debugging.md) +- [Support](./support.md) +- [Security](./security.md) \ No newline at end of file diff --git a/docs/security.md b/docs/security.md new file mode 100644 index 0000000..495d8f2 --- /dev/null +++ b/docs/security.md @@ -0,0 +1,33 @@ +# Security + +## Reporting Vulnerabilities + +We’re extremely grateful for security researchers and users that report vulnerabilities to the Hasura Community. All reports are thoroughly investigated by a set of community volunteers and the Hasura team. + +To report a security issue, please email us at [security@hasura.io](mailto:security@hasura.io) with all the details, attaching all necessary information. + +### When Should I Report a Vulnerability? + +- You think you have discovered a potential security vulnerability in the Hasura GraphQL Engine or related components. +- You are unsure how a vulnerability affects the Hasura GraphQL Engine. +- You think you discovered a vulnerability in another project that Hasura GraphQL Engine depends on (e.g. Heroku, Docker, etc). +- You want to report any other security risk that could potentially harm Hasura GraphQL Engine users. + +### When Should I NOT Report a Vulnerability? + +- You need help tuning Hasura GraphQL Engine components for security. +- You need help applying security related updates. +- Your issue is not security related. + +## Security Vulnerability Response + +Each report is acknowledged and analyzed by the project's maintainers and the security team within 3 working days. + +The reporter will be kept updated at every stage of the issue's analysis and resolution (triage -> fix -> release). + +## Public Disclosure Timing + +A public disclosure date is negotiated by the Hasura product security team and the bug submitter. We prefer to fully disclose the bug as soon as possible once a user mitigation is available. It is reasonable to delay disclosure when the bug or the fix is not yet fully understood, the solution is not well-tested, or for vendor coordination. The timeframe for disclosure is from immediate (especially if it's already publicly known) to a few weeks. We expect the time-frame between a report to a public disclosure to typically be in the order of 7 days. The Hasura GraphQL Engine maintainers and the security team will take the final call on setting a disclosure date. + +(Some sections have been inspired and adapted from +[https://github.com/kubernetes/website/blob/master/content/en/docs/reference/issues-security/security.md](https://github.com/kubernetes/website/blob/master/content/en/docs/reference/issues-security/security.md). \ No newline at end of file diff --git a/docs/support.md b/docs/support.md new file mode 100644 index 0000000..5f9eb62 --- /dev/null +++ b/docs/support.md @@ -0,0 +1,11 @@ +# Support & Troubleshooting + +The documentation and community will help you troubleshoot most issues. If you have encountered a bug or need to get in touch with us, you can contact us using one of the following channels: +* Support & feedback: [Discord](https://discord.gg/hasura) +* Issue & bug tracking: [GitHub issues](https://github.com/hasura/ndc-typescript-deno/issues) +* Follow product updates: [@HasuraHQ](https://twitter.com/hasurahq) +* Talk to us on our [website chat](https://hasura.io) + +We are committed to fostering an open and welcoming environment in the community. Please see the [Code of Conduct](code-of-conduct.md). + +If you want to report a security issue, please [read this](security.md). \ No newline at end of file