From 3678f9d2981f8951c84e3c295f614718821af406 Mon Sep 17 00:00:00 2001 From: Raghd Hamzeh Date: Thu, 28 Sep 2023 16:32:53 -0400 Subject: [PATCH] chore: mode developer docs to a different page --- .gitignore | 3 +- README.md | 128 ++++++++++++++++++++++++++------------------ docs/DEVELOPMENT.md | 51 ++++++++++++++++++ 3 files changed, 129 insertions(+), 53 deletions(-) create mode 100644 docs/DEVELOPMENT.md diff --git a/.gitignore b/.gitignore index fa23410..97dd806 100644 --- a/.gitignore +++ b/.gitignore @@ -4,4 +4,5 @@ node_modules client/server .vscode-test .vscode-test-web -.DS_Store \ No newline at end of file +.DS_Store +.idea/ \ No newline at end of file diff --git a/README.md b/README.md index 0b61eb4..d34fdc3 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ VS Code extension that provides syntax highlighting for the [OpenFGA](https://op [![Open VSX Version](https://img.shields.io/open-vsx/v/OpenFGA/openfga-vscode)](https://open-vsx.org/extension/OpenFGA/openfga-vscode) [![Release](https://img.shields.io/github/v/release/openfga/vscode-ext?sort=semver&color=green)](https://github.com/openfga/vscode-ext/releases) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/openfga/vscode-ext/blob/main/LICENSE) -[![Discord Server](https://img.shields.io/discord/759188666072825867?color=7289da&logo=discord "Discord Server")](https://discord.gg/8naAwJfWN6) +[![Discord Community](https://img.shields.io/discord/759188666072825867?color=7289da&logo=discord "Discord Community")](https://discord.gg/8naAwJfWN6) [![Twitter](https://img.shields.io/twitter/follow/openfga?color=%23179CF0&logo=twitter&style=flat-square "@openfga on Twitter")](https://twitter.com/openfga) ## About @@ -19,8 +19,8 @@ OpenFGA is designed to make it easy for application builders to model their perm - [OpenFGA Documentation](https://openfga.dev/docs) - [OpenFGA API Documentation](https://openfga.dev/api/service) -- [Twitter](https://twitter.com/openfga) -- [OpenFGA Discord Community](https://discord.gg/8naAwJfWN6) +- [OpenFGA on Twitter](https://twitter.com/openfga) +- [Discord Community](https://discord.gg/8naAwJfWN6) - [Zanzibar Academy](https://zanzibar.academy) - [Google's Zanzibar Paper (2019)](https://research.google/pubs/pub48190/) @@ -36,7 +36,7 @@ You can install the OpenFGA VS Code plugin from: ## Usage -The extension currently offers 3 core features, with more to come. +The extension currently offers 4 core features, with more to come. - Syntax Highlighting for OpenFGA files - A unique theme for OpenFGA for VS Code @@ -46,61 +46,85 @@ The extension currently offers 3 core features, with more to come. ![Prompt to set OpenFGA Dark color scheme](resources/set-color-scheme.png) -- A command to transform `OpenFGA` files to `JSON` - - Open an `OpenFGA` file in the editor +- A command to transform `.fga` OpenFGA files to `JSON` + - Open a `.fga` OpenFGA file in the editor - Open the `Command Pallette` using Ctrl+Shift+P (Windows) or Command+Shift+P (OSX) - Select `OpenFGA: Transform DSL to JSON` - A new tab will open with the transformed code ![Prompt to execute OpenFGA: Transform DSL to JSON command](resources/transform-command-select.png) -## Development - -- Run `npm install` in the root directory. This installs all necessary npm modules. -- Run `npm run compile && npm run test-node` to execute the client node test suite. - -### Distribution (Optional) - -To generate an installable build of this extension, you can do the following: - -- Run `npm install --global @vscode/vsce` to get the latest version of `vsce` for packaging -- Run `vsce package` to generate an installable `VISX` artifact for testing or distribution - -### Structure - -``` -. -├── client // Language Client -│ ├── src -│ │ ├── test // End to End tests for Language Client / Server -│ │ ├── extension.node.ts // Language Client node entry point -│ │ └── extension.browser.ts // Language CLient web entry point -├── package.json // The extension manifest. -└── server // Language Server - └── src - ├── server.node.ts // Language Server node entry point - ├── server.browser.ts // Language Server web entry point - └── server.common.ts // Language Server common code +- Validation of OpenFGA's `.fga` files + - As you type in a `.fga` OpenFGA file in the editor, the extension will highlight errors that make your models invalid + +## Workflow to use it with the FGA CLI + +The extension works great when combined with the [FGA CLI](https://github.com/openfga/cli) to iterate on your model and test it. + +In order to do that: +1- Create a working directory to house the files for your store +2- Inside this directory, create a `model.fga` file with your model +3- Alongside the `model.fga`, create a `store.yaml` file with the following syntax + +```yaml +--- +name: Store Name # store name, optional +model_file: ./model.fga # a global model that would apply to all tests +tuples: # global tuples that would apply to all tests, optional + - user: folder:1 + relation: parent + object: folder:2 + - user: user:anne + relation: editor + object: folder:1 +tests: # required + - name: test-1 + description: testing that the model works # optional + tuples: # tuples that only apply within the scope of this test + - user: user:beth + relation: viewer + object: folder:2 + check: # a set of checks to run + - user: user:anne + object: folder:1 + assertions: + # a set of expected results for each relation + can_view: true + can_write: true + can_share: false + - user: user:beth + object: folder:2 + assertions: + # a set of expected results for each relation + can_view: true + can_write: false + can_share: false + list_objects: # a set of list objects to run + - user: user:anne + type: folder + assertions: + # a set of expected results for each relation + can_view: + - folder:1 + - folder:2 + can_write: + - folder:1 + - folder:2 + can_share: [] + - user: user:beth + type: folder + assertions: + # a set of expected results for each relation + can_view: + - folder:2 + can_write: [] + can_share: [] ``` -### Running the Client - -- Run `npm install` in the root directory. This installs all necessary npm modules. -- Open the root directory in VS Code. -- Press Ctrl+Shift+B (Windows) or Command+Shift+B (OSX) to start compiling the client and server in [watch mode](https://code.visualstudio.com/docs/editor/tasks#:~:text=The%20first%20entry%20executes,the%20HelloWorld.js%20file.). -- Switch to the Run and Debug View in the Sidebar (Ctrl+Shift+D on Windows, Command+Shift+D on OSX). -- Select `Launch Client` from the drop down (if it is not already). -- Press ▷ to run the launch config (F5). - -### Testing - -- Run `npm install` in the root directory. This installs all necessary npm modules. -- Run `npm run compile` to compile the code & client for testing. -- Run `npm run test-node` to execute the client node test suite. - -#### Remote Testing the Web functionality - -- To manually test the extension in the browser for [VS Code for the Web](https://vscode.dev/) before publishing, follow [these instructions](https://code.visualstudio.com/api/extension-guides/web-extensions#test-your-web-extension-in-vscode.dev) to setup a VS Code for the Web instance with your local extension, and then proceed with the normal testing flow. +When ready to test, from the terminal, and while inside your working directory, run: +```shell +fga model test --tests=./store.yaml +``` ## Roadmap @@ -108,7 +132,7 @@ A rough [roadmap](https://github.com/orgs/openfga/projects/3) for development pr ## Contributing -See [CONTRIBUTING](https://github.com/openfga/.github/blob/main/CONTRIBUTING.md). +See the [DEVELOPMENT](./docs/DEVELOPMENT.md) and [CONTRIBUTING](https://github.com/openfga/.github/blob/main/CONTRIBUTING.md). ## Author diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md new file mode 100644 index 0000000..02240a1 --- /dev/null +++ b/docs/DEVELOPMENT.md @@ -0,0 +1,51 @@ +# Development and Contributing to the OpenFGA VS Code Extension + +Read the [OpenFGA Contribution Process](https://github.com/openfga/.github/blob/main/CONTRIBUTING.md) and the [OpenFGA Code of Conduct](https://github.com/openfga/.github/blob/main/CODE_OF_CONDUCT.md). + +## Getting Started + +- Run `npm install` in the root directory. This installs all necessary npm modules. +- Run `npm run compile && npm run test-node` to execute the client node test suite. + +## Distribution (Optional) + +To generate an installable build of this extension, you can do the following: + +- Run `npm install --global @vscode/vsce` to get the latest version of `vsce` for packaging +- Run `vsce package` to generate an installable `VISX` artifact for testing or distribution + +## Structure + +``` +. +├── client // Language Client +│ ├── src +│ │ ├── test // End to End tests for Language Client / Server +│ │ ├── extension.node.ts // Language Client node entry point +│ │ └── extension.browser.ts // Language CLient web entry point +├── package.json // The extension manifest. +└── server // Language Server + └── src + ├── server.node.ts // Language Server node entry point + ├── server.browser.ts // Language Server web entry point + └── server.common.ts // Language Server common code +``` + +## Running the Client + +- Run `npm install` in the root directory. This installs all necessary npm modules. +- Open the root directory in VS Code. +- Press Ctrl+Shift+B (Windows) or Command+Shift+B (OSX) to start compiling the client and server in [watch mode](https://code.visualstudio.com/docs/editor/tasks#:~:text=The%20first%20entry%20executes,the%20HelloWorld.js%20file.). +- Switch to the Run and Debug View in the Sidebar (Ctrl+Shift+D on Windows, Command+Shift+D on OSX). +- Select `Launch Client` from the drop down (if it is not already). +- Press ▷ to run the launch config (F5). + +## Testing + +- Run `npm install` in the root directory. This installs all necessary npm modules. +- Run `npm run compile` to compile the code & client for testing. +- Run `npm run test-node` to execute the client node test suite. + +### Remote Testing the Web functionality + +- To manually test the extension in the browser for [VS Code for the Web](https://vscode.dev/) before publishing, follow [these instructions](https://code.visualstudio.com/api/extension-guides/web-extensions#test-your-web-extension-in-vscode.dev) to setup a VS Code for the Web instance with your local extension, and then proceed with the normal testing flow.