Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tarantool/graphqlide
Tarantool Cartridge WebUI GraphiQL IDE module
https://github.com/tarantool/graphqlide
cartridge graphql lua tarantool typescript
Last synced: 4 days ago
JSON representation
Tarantool Cartridge WebUI GraphiQL IDE module
- Host: GitHub
- URL: https://github.com/tarantool/graphqlide
- Owner: tarantool
- Created: 2020-04-18T11:07:03.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2022-05-26T15:38:40.000Z (over 2 years ago)
- Last Synced: 2023-03-11T01:33:42.076Z (over 1 year ago)
- Topics: cartridge, graphql, lua, tarantool, typescript
- Language: TypeScript
- Homepage:
- Size: 3.4 MB
- Stars: 6
- Watchers: 15
- Forks: 1
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# Tarantool Cartridge WebUI GraphQL IDE module
- [Tarantool Cartridge WebUI GraphQL IDE module](#tarantool-cartridge-webui-graphql-ide-module)
- [Main menu](#main-menu)
- [Install pre-built rock](#install-pre-built-rock)
- [Lua API](#lua-api)
- [Init](#init)
- [Stop](#stop)
- [Set endpoint](#set-endpoint)
- [Get endpoints](#get-endpoints)
- [Remove endpoints](#remove-endpoints)
- [Front init](#front-init)
- [Set default schema](#set-default-schema)
- [Add Tarantool Cartridge GraphQL API schema endpoint](#add-tarantool-cartridge-graphql-api-schema-endpoint)
- [Remove Tarantool Cartridge GraphQL API schema endpoint](#remove-tarantool-cartridge-graphql-api-schema-endpoint)
- [Version](#version)
- [Adding GraphQL IDE to your Tarantool Cartridge App](#adding-graphql-ide-to-your-tarantool-cartridge-app)
- [Use GraphQL IDE with pure Tarantool (without Tarantool Cartridge)](#use-graphql-ide-with-pure-tarantool-without-tarantool-cartridge)
- [Build from sources](#build-from-sources)
- [Prerequisites](#prerequisites)
- [Clone repo and install nodejs modules](#clone-repo-and-install-nodejs-modules)
- [Build rock](#build-rock)
- [Install built rock](#install-built-rock)
- [Development](#development)
GraphQL IDE module is used to add GraphQL IDE functionality into Tarantool Cartridge WebUI or pure Tarantool (without Tarantool Cartridge). Module it self and Cartridge role are hot-reloadable.
Based on:
- [Tarantool 1.10.x or 2.x.x](https://www.tarantool.io/en/download/)
- [Tarantool Cartridge 2.7.4+](https://github.com/tarantool/cartridge) (optional, module can work without Tarantool Cartridge)
- [Tarantool Frontend Core 8+](https://github.com/tarantool/frontend-core)
- [Tarantool Http 1.1.0+](https://github.com/tarantool/http)
- [GraphiQL 1.8.10](https://github.com/graphql/graphiql)
- [GraphiQL Explorer 0.6.3+](https://github.com/OneGraph/graphiql-explorer)
GraphQL IDE interface:
## Main menu
GraphQL IDE main menu contains the following items:
Items description:
- `Play` - execute request. Keyboard shortcut: `Ctrl-Enter`;
- `Explorer` - toggle Explorer window. Keyboard shortcut Windows/Linux: `Alt-Shift-E`, MacOS: `Option-Shift-E`;
- `History` - toggle History window. Keyboard shortcut Windows/Linux: `Alt-Shift-H`, MacOS: `Option-Shift-H`;
- `Prettify` - prettify request. Keyboard shortcut Windows/Linux: `Alt-Shift-P`, MacOS: `Option-Shift-P`;
- `Merge` - merge request fragments. Keyboard shortcut Windows/Linux: `Alt-Shift-M`, MacOS: `Option-Shift-M`;
- `Copy` - group of copy to clipboard items:
- `Query` - copy query to clipboard. Keyboard shortcut Windows/Linux: `Alt-Shift-C`, MacOS: `Option-Shift-C`;
- `Response` - copy response to clipboard. Keyboard shortcut Windows/Linux: `Alt-Shift-X`, MacOS: `Option-Shift-X`;
- `Save`
- `Query` - save query to *.graphql file. Keyboard shortcut Windows/Linux: `Alt-Shift-Q`, MacOS: `Option-Shift-Q`;
- `Response` - save response to *.json file. Keyboard shortcut Windows/Linux: `Alt-Shift-R`, MacOS: `Option-Shift-R`;
- `Doc` - toggle Documentation Explorer. Keyboard shortcut Windows/Linux: `Alt-Shift-D`, MacOS: `Option-Shift-D`.
## Install pre-built rock
Simply run from the root of Tarantool Cartridge App root the following:
```sh
cd
tarantoolctl rocks install graphqlide
```
## Lua API
Note: **This module is still under heavy development. API may be changed in further versions without notice and may be not backward compatible. Use in production environments at your own risk.**
### Init
`init()` - used to initialize graphqlide module for non-Cartridge Tarantool Applications.
### Stop
`stop()` - used to deinitialize graphqlide module for non-Cartridge Tarantool Applications.
### Set endpoint
`set_endpoint(endpoint)` - used to set GraphQL Web UI schema endpoint in runtime.
where:
- `endpoint` (`table`) - mandatory, endpoint of GraphQL API description with the following options:
- `name` (`string`) - mandatory, schema display name;
- `path` (`string`) - mandatory, URI-path to graphql endpoint;
- `default` (`boolean`) - optional, flag to indicate that this endpoint is default, false - if not;
- `options` (`table`) - optional, set of flags to enable or disable extended graphql schema fields,
where:
- `descriptions` (`boolean`) - optional, option to request or not for input fields `descriptions`, default is `true`;
- `specifiedByUrl` - optional, option to request or not for `specifiedByUrl` field for `Scalars`, default is `true`;
- `directiveIsRepeatable` - optional, option to request or not for `directiveIsRepeatable` field of `Directives`, default is `true`;
- `schemaDescription` - optional, option to request or not for `schemaDescription` field for `schema`, default is `false`;
- `inputValueDeprecation` - optional, option to deprecate or not for deprecated input fields, default is `false`;
Example:
```lua
graphqlide.set_endpoint({ name = 'Spaces', path = '/admin/graphql', default = true })
graphqlide.set_endpoint({
name = 'Admin',
path = '/admin/api',
options = {
specifiedByUrl = false,
directiveIsRepeatable = false,
}
})
```
Note: **Since Tarantool Cartridge WebUI doesn't support sending notifications to WebUI front after any changes feel free to reload page in browser**
### Get endpoints
`get_endpoints()` - method is used to get schemas endpoints.
Method returns `endpoints` (`table`) with the following structure:
```lua
{
[""] = {
default = true/false,
path = "",
options = {
descriptions = true/false,
specifiedByUrl = true/false,
directiveIsRepeatable = true/false,
schemaDescription = true/false,
inputValueDeprecation = true/false,
}
},
...
}
```
### Remove endpoints
`remove_endpoint(name)` - method is used to remove schema endpoint,
where:
- `name` (`string`) - mandatory, schema display name.
Example:
```lua
graphqlide.set_endpoint({ name = 'Spaces', path = '/admin/graphql', default = true })
...
graphqlide.remove_endpoint('Spaces')
```
### Front init
`front_init(httpd, opts)` - method to init frontend core. This method must be used only for non-Cartridge Tarantool Applications since Tarantool Cartridge do this job for you under the hood,
where:
- `httpd` (`table`) - instance of a Tarantool HTTP server (only 1.x versions is supported).
- `opts` (`table`) - optional, additional front-end initialization options:
- `enforce_root_redirect` (`boolean`) - optional key which controls redirection to frontend core app from '/' path, default true;
- `prefix` (`string`) - optional, adds path prefix to frontend core app;
- `force_init` (`boolean`) - optional, flag to force frontend module initialization. By default front_init() checks whether frontend core module initialized or not, but if force_init == true front_init() will skip checks and init frontend core module anyways.
### Set default schema
`set_default(name)` - method to set default schema,
where:
- `name` (`string`) - mandatory, schema display name to be set as default.
### Add Tarantool Cartridge GraphQL API schema endpoint
`add_cartridge_api_endpoint(name, default)` - method to add Tarantool Cartridge GraphQL API schema endpoint,
where:
- `name` (`string`) - mandatory, Tarantool Cartridge GraphQL API schema name to be displayed in UI;
- `default` (`boolean`) - optional, flag to set this schema to be default in list of GraphQL schemas in UI.
Note: **This method will not be available if executed in non-Cartridge Tarantool Application.**
### Remove Tarantool Cartridge GraphQL API schema endpoint
`remove_cartridge_api_endpoint()` - method to remove Tarantool Cartridge GraphQL API schema endpoint from list of schemas in GraphQL IDE UI.
Note: **This method will not be available if executed in non-Cartridge Tarantool Application.**
### Version
`VERSION` - is a constant to determine which version of GraphQL IDE is installed.
Example:
```lua
local graphqlide = require('graphqlide')
local log = require('log')
log.info('GraphQL IDE version: %s', graphqlide.VERSION)
```
## Adding GraphQL IDE to your Tarantool Cartridge App
There are 3 ways to add GraphQL IDE to Tarantool Cartridge application:
1. Add GraphQL IDE initialization code to Tarantool Cartridge application init.lua:
```lua
...
local ok, err = cartridge.cfg({
roles = {
...
},
})
assert(ok, tostring(err))
-- Init GraphQL IDE
local endpoint = '/admin/graphql'
require('graphqlide').init()
graphqlide.set_endpoint({ name = 'Spaces', path = '/admin/graphql', default = true })
...
```
**Note:** graphqlide.init() must be called after cartridge.cfg()
2. Add GraphQL IDE initialization code into desired Tarantool Cartridge role init() function:
```lua
local graphqlide = require('graphqlide')
...
local function init(opts) -- luacheck: no unused args
if opts.is_master then
...
end
...
-- Init GraphQL IDE
graphqlide.init()
-- Set GraphQL endpoint
graphqlide.set_endpoint({ name = 'Spaces', path = '/admin/graphql', default = true })
return true
end
local function stop()
-- Deinit GraphQL IDE
graphqlide.stop()
...
end
...
return {
role_name = 'app.roles.custom',
init = init,
stop = stop,
dependencies = {
'cartridge.roles.graphqlide',
}
}
```
3. Add GraphQL IDE Tarantool Cartridge role as dependency of desired Tarantool Cartridge role:
```lua
...
local function init(opts) -- luacheck: no unused args
if opts.is_master then
...
end
...
-- Init GraphQL IDE
graphqlide.init()
graphqlide.set_endpoint({ name = 'Spaces', path = '/admin/graphql', default = true })
return true
end
local function stop()
-- Deinit GraphQL IDE
graphqlide.stop()
...
end
...
return {
role_name = 'app.roles.custom',
init = init,
stop = stop,
dependencies = {
'cartridge.roles.graphqlide',
}
}
```
In this case may need to set endpoint of GraphQL API. The best way to it simply call `set_endpoint()` method from `init()` of Tarantool Cartridge role:
```lua
local graphqlide = require('graphqlide')
...
local function init(opts)
if opts.is_master then
...
end
...
graphqlide.set_endpoint('/admin/graphql')
...
end
```
## Use GraphQL IDE with pure Tarantool (without Tarantool Cartridge)
This module can be used with pure Tarantool (without Tarantool Cartridge).
Caution: GraphQL IDE module is compatible only with 1.x branch of http module [http](https://github.com/tarantool/http)
Example:
```lua
local http = require('http.server')
local graphqlide = require('graphqlide')
local HOST = '0.0.0.0'
local PORT = 8081
local ENDPOINT = '/graphqlide'
local httpd = http.new(HOST, PORT,{ log_requests = false })
httpd:start()
-- Init frontend-core module if it was not initialized before
graphqlide.front_init(httpd)
-- Init graphqlide module if it was not initialized before
graphqlide.init()
-- set default "Default" GraphQL endpoint
graphqlide.set_endpoint({ name = 'Default', path = ENDPOINT, default = true })
box.cfg({work_dir = './tmp'})
```
## Build from sources
### Prerequisites
To build rock you will need the following to be installed:
- [nodejs](https://nodejs.org/)
- [Tarantool 2.x.x](https://www.tarantool.io/en/download/)
### Clone repo and install nodejs modules
```sh
git clone [email protected]:tarantool/graphqlide.git graphqlide
cd graphqlide
npm i
```
### Build rock
```sh
tarantoolctl rocks make
tarantoolctl rocks pack graphqlide
```
Also you can use `npm run build-rock` to build the rock.
After build completion you will get:
- packed graphqlide rock: `graphqlide/graphqlide-scm-1.all.rock`
- graphqlide rock installed to: graphqlide/.rocks/tarantool
### Install built rock
Simply run from the root of Tarantool Cartridge App root the following:
```sh
cd
tarantoolctl rocks install /graphqlide-scm-1.all.rock
```
## Development
For debug & development purposes VSCode may be used.
Use F5 to run app or Shift-Crtl-B to run production build task.
Useful commands:
- `npm run build - to build production module`
- `npm run start - run application without need to integrate it into Tarantool Cartridge App. Useful for development purposes`
- `npm run build-rock - builds production module and bundles it into the rock`