-
Notifications
You must be signed in to change notification settings - Fork 3
Readme and docs edits #52
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
seanparkross
wants to merge
2
commits into
main
Choose a base branch
from
readme-updates
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3,4 +3,5 @@ | |
| .vscode/ | ||
| vendor/ | ||
| scratch/ | ||
| src/test/vendor | ||
| src/test/vendor | ||
| .idea | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| [email protected]. 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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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/<repo>) 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 #<issue-no>` or `close #<issue-no>` 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 [[email protected]](mailto:[email protected]) 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). |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can we preserve the anchor?