Merge pull request #90 from Canner/feature/init-document

Official document

packages/doc/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

packages/doc/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

packages/doc/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

packages/doc/docs/api-building/access-control.mdx

@@ -0,0 +1,31 @@
+# Access Control
+
+This is an overview of VulcanSQL access control flow:
+
+![access control flow](./img/access-control-flow.png)
+
+## Authentication
+
+First, we need to know who sends the request, a common way is validating the credentials like tokens, cookies…etc. This process is done by [Authenticators](./access-control/authenticator), authenticators might validate the credentials themselves, or ask third-party auth providers about them. When the authentication process is fulfilled, we add some “attributes” to the request for the next step, these attributes can be users' names, departments, groups, statuses…etc., which depend on the authenticators.
+
+Please check [Authenticators](./access-control/authenticator) for the authenticators you can use.
+
+## Authorization
+
+After knowing our requesters, we need to determine what they can do, VulcanSQL implemented a simple [attribute-based access control](https://en.wikipedia.org/wiki/Attribute-based_access_control?oldformat=true) (ABAC) for it. We can set the policy on profiles, e.g. the profile “pg-admin” only allows the users who are in the administrator group to access. While evaluating requests, we check whether the attributes of users meet the requirements of profiles. If users can't access any of the profiles, we reject the request with “forbidden” error, otherwise, we give the profile to the request and push them to the next step.
+
+Please check [Authorization](./access-control/authorization) for who to set the policy.
+
+## Admission Control
+
+This step is optional, you may need some complex logic to decide the legality of the request, in these cases, you can check the request in [SQL Templates](./sql-template). For example, assume that we want to limit the size of the result for the requests from interns, we can add the following SQL at the top of our templates:
+
+```sql
+{% if context.user.attr.department = 'intern' and context.params.limit > 1000 %}
+	{% error "OUT_OF_LIMITED" %}
+{% endif %}
+```
+
+## Fetch data from warehouses
+
+After passing all of the access control steps, users can send queries to warehouses with the profile we gave.

packages/doc/docs/api-building/access-control/authenticator.mdx

@@ -0,0 +1,21 @@
+# Authenticators
+
+To enable authenticators, you need to set `auth.enabled` to true in `vulcan.yaml`.
+
+```yaml
+auth:
+  enabled: true
+```
+
+The following is the list of built-in authenticators, please check their documentation to learn how to enable and configure them.
+
+:::info
+You can enable multiple authenticators if they check different credentials.
+
+:::
+
+| Authenticator                                   | Description                                          |
+| ----------------------------------------------- | ---------------------------------------------------- |
+| [HTTP Basic](./authenticators/http-basic)       | Authenticate via HTTP basic auth.                    |
+| [Password File](./authenticators/password-file) | Using a password file to validate username/password. |
+| [Simple Token](./authenticators/simple-token)   | Using a static token to validate users.              |

packages/doc/docs/api-building/access-control/authenticators/http-basic.mdx

@@ -0,0 +1,96 @@
+# HTTP basic authenticator
+
+:::caution
+Hardcoded passwords in config files are not recommended for production environments, please use this authenticator only for development usage.
+
+:::
+
+Authenticate users via [HTTP basic auth](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).
+
+## Configuration
+
+```yaml
+auth:
+  enabled: true
+  options:
+    basic:
+      # Read users and passwords from a text file.
+      htpasswd-file:
+        path: passwd.txt # Path to the password file.
+        users: # (Optional) Add attributes for users
+          - name: jax
+            attr:
+              department: engineer
+      # Config users and their passwords in config (not recommended)
+      users-list:
+        - name: william
+          md5Password: 202cb962ac59075b964b07152d234b70
+          attr:
+            department: finance
+        - name: freda
+          md5Password: 202cb962ac59075b964b07152d234b70
+          attr:
+            department: engineer
+```
+
+### Password file
+
+You need to create a password file in format `<username>:<md5-password>`, one user per line. For example:
+
+```
+jax:202cb962ac59075b964b07152d234b70
+ivan:202cb962ac59075b964b07152d234b70
+```
+
+This file provides two users "jax" and "ivan" with password "123".
+
+If you want to add some attributes for these users, you can set them in the config file, for example,
+
+```yaml
+auth:
+  enabled: true
+  options:
+    basic:
+      htpasswd-file:
+        path: passwd.txt
+        users:
+          - name: jax
+            attr:
+              department: engineer
+```
+
+This config adds department=engineer for user "jax", but adds no attribute to user "ivan".
+
+### User list
+
+In the development environment, you can also hardcoded some users in the config file:
+
+```yaml
+auth:
+  enabled: true
+  options:
+    users-list:
+      - name: william
+        md5Password: 202cb962ac59075b964b07152d234b70
+        attr:
+          department: finance
+      - name: freda
+        md5Password: 202cb962ac59075b964b07152d234b70
+        attr:
+          department: engineer
+```
+
+This config adds two users "william" and "freda", along with corresponding attributes.
+
+:::info
+You can add both users-list and htpasswd-file at the same time, htpasswd-file has the higher priority.
+
+:::
+
+## Provide credentials
+
+You need to add a header `Authorization: basic base64(<username>:<password>)` when sending requests, for example, sending requests with username "ivan" and password "123".
+
+```yaml
+curl -H "Authorization: basic aXZhbjoxMjM=" http://localhost:3000/api/customer
+```

packages/doc/docs/api-building/access-control/authenticators/password-file.mdx

@@ -0,0 +1,61 @@
+# Password file authenticator
+
+Authenticate HTTP header with a password file.
+
+## Configuration
+
+```yaml
+auth:
+  enabled: true
+  options:
+    password-file:
+      path: passwd.txt
+      users:
+        - name: jax
+          attr:
+            department: engineer
+```
+
+### Password file
+
+You need to create a password file in format `<username>:<bcrypt-password>`, one user per line. For example:
+
+```
+jax:$2y$10$QUAOLtJb3C80sdbmrDIG7O833YU6YMJHNs5P/idwWjvJRsyGy22qa
+ivan:$2y$10$QUAOLtJb3C80sdbmrDIG7O833YU6YMJHNs5P/idwWjvJRsyGy22qa
+```
+
+This file provides two users "jax” and "ivan” with password "123”.
+
+:::info
+To generate bcrypt-password, you can use htpasswd command, for example, to generate user "ivan” and password "123”:
+
+```bash
+htpasswd -bnBC 10 "ivan" 123
+```
+
+:::
+
+If you want to add some attributes for these users, you can set them in the config file, for example,
+
+```yaml
+auth:
+  enabled: true
+  options:
+    password-file:
+      path: passwd.txt
+      users:
+        - name: jax
+          attr:
+            department: engineer
+```
+
+This config adds department=engineer for user "jax”, but adds no attribute to user "ivan”.
+
+## Provide credentials
+
+You need to add a header `Authorization: password-file base64(<username>:<password>)` when sending requests, for example, sending requests with username "ivan” and password "123”.
+
+```yaml
+curl -H "Authorization: password-file aXZhbjoxMjM=" http://localhost:3000/api/customer
+```

packages/doc/docs/api-building/access-control/authenticators/simple-token.mdx

@@ -0,0 +1,35 @@
+# Simple token authenticator
+
+Using a static token to validate users.
+
+## Configuration
+
+```yaml
+auth:
+  enabled: true
+  options:
+    simple-token:
+      - name: jax # User name
+        token: some-secret # Token to authenticate
+        attr: # (optional) attributes for this user
+          department: engineer
+      - name: ivan
+        token: another-secret
+        attr:
+          department: intern
+```
+
+Simple token authenticator requires a user list to authenticate. You must set the name and token for each user, and give them some optional attributes.
+
+:::caution
+The tokens for every user should be different, otherwise, the last configured user overrides all the previous.
+
+:::
+
+## Provide credentials
+
+You need to add a header `Authorization: sample-token <token>` when sending requests, for example, sending requests with the token “another-secret”.
+
+```yaml
+curl -H "Authorization: simple-token another-secret" http://localhost:3000/api/customer
+```