nextline-graphql

nextline-graphql

The plugin-based framework of a Python API server.

Table of Contents

• Introduction
• Citation
• Packages
  • Backend API server (Python)
    • Core package
    • Plugin system
    • Plugins
    • Utility
  • Frontend web app (TypeScript)
• How to run the Nextline backend API server
  • As a Docker container
  • In a virtual environment
• Configuration
  • CORS
  • Logging
  • graphql plugin
  • ctrl plugin
• Check out code for development

Introduction

This package provides the framework for a plugin-based Python API server. Plugins can implement endpoints and services.

Packages

Nextline consists of multiple packages. This package, nextline-graphql, provides the framework for the backend API server.

Package	Language	Release	Build	Coverage
nextline	Python
apluggy	Python
nextline‑graphql	Python
nextline‑rdb	Python
nextline‑schedule	Python
nextline‑alert	Python
nextline‑test‑utils	Python
nextline‑web	TypeScript

Backend API server (Python)

Core package

• nextline: The core functionality of Nextline. It controls the execution of the Python scripts. It is used by the plugin ctrl.

Plugin system

The plugin system of nextline-graphql is apluggy.

• apluggy: A wrapper of pluggy to support asyncio and context managers.

Plugins

Internal plugins

These plugins are included in this package.

• graphql: The entry point of the GraphQL API, implemented with strawberry-graphql.
• ctrl: The core plugin that controls the execution of the Python scripts. It uses the package nextline.

External plugins

These plugins are not included in this package. They can be installed separately.

• nextline-rdb: A relational database for nextline. It stores configuration, execution history, and other information. It is implemented with SQLAlchemy 2.
• nextline-schedule: The auto mode. The queue system. An interface to the SO scheduler.
• nextline-alert: An interface to the alert system campana.

Utility

• nextline-test-utils: A collection of test utilities for backend development

Frontend web app (TypeScript)

The frontend web app is currently in a single package. The development of a plugin-based system is planned.

• nextline-web: The frontend web app of Nextline. It is a Vue.js app.

How to run the Nextline backend API server

The section shows how to run the Nextline backend API server. How to run the frontend web app is described elsewhere.

As a Docker container

Docker images of the Nextline backend API server are created as ghcr.io/simonsobs/nextline-graphql. These images are created by the Dockerfile. No external plugins are included in the images.

Use, for example, the following command to run as a Docker container.

docker run -p 8080:8000 ghcr.io/simonsobs/nextline-graphql

If you access to the API server with a web browser, you will see the GraphQL IDE: http://localhost:8080/.

To include external plugins, you can create a new Docker image with ghcr.io/simonsobs/nextline-graphql as the base image. For example, nextline-rdb shows how to create a new Docker image with nextline-rdb as an external plugin.

In a virtual environment

You can create a virtual environment, install packages, and run the API server as follows.

python -m venv venv
source venv/bin/activate
pip install nextline-graphql
pip install uvicorn
uvicorn --lifespan on --factory --port 8080 nextlinegraphql:create_app

Check with a web browser at http://localhost:8080/.

If you check out external plugins, nextline-graphql automatically detects them as plugins. An example can be described in nextline-rdb.

Configuration

nextline-graphql uses dynaconf for configuration management. The nextline-graphql framework itself has configuration for CORS and logging. The internal plugins have configurations. External plugins can extend the configuration.

CORS

These CORS (Cross-Origin Resource Sharing) settings will be given to allow_origin and allow_headers of Starlette's CORSMiddleware.

Environment variable	Default value	Description
NEXTLINE_CORS__ALLOW_ORIGINS	['*']	A list of allowed origins, e.g., ["http://example.com:8080"]. The default value ("*") allows any origins.
NEXTLINE_CORS__ALLOW_HEADERS	['*']	A list of allowed HTTP request headers. For example, ['remote-user', 'remote-name', 'remote-email'] can be appropriate values if Authelia is used. Some headers such as Content-Type are always allowed (See the Starlette doc). The default value ("*") allows any headers.
NEXTLINE_CORS__ALLOW_CREDENTIALS	false	Whether to support cookies. If true, the wildcard ("*") cannot be used for NEXTLINE_CORS__ALLOW_ORIGINS or NEXTLINE_CORS__ALLOW_HEADERS. They need to be listed explicitly.

Logging

See default.toml.

graphql plugin

Environment variable	Default value	Description
NEXTLINE_GRAPHQL__MUTATION_ALLOW_ORIGINS	[*]	A list of allowed origins for GraphQL Mutations. The default value ("*") allows any origins.*

• In addition to the CORS settings above, this setting provides further access control for GraphQL Mutations. With this setting, you can allow only GraphQL Queries and Subscriptions from certain origins while prohibiting Mutations.

ctrl plugin

Environment variable	Default value	Description
NEXTLINE_CTRL__TRACE_MODULES	false	By default (false), Nextline only traces the main Python script. If true, Nextline traces execution of imported Python modules as well.
NEXTLINE_CTRL__TRACE_THREADS	false	By default (false), Nextline only traces the main thread. If true, Nextline traces execution of other threads as well.

Check out code for development

How to check out code from GitHub for development:

git clone [e-mail]:simonsobs/nextline-graphql.git
cd nextline-graphql/
python -m venv venv
source venv/bin/activate
pip install -e ./"[tests,dev]"

To run

uvicorn --port 8080 --lifespan on --factory --reload nextlinegraphql:create_app