TangoGQL Ariadne Implementation

The current implementation of TangoGQL, using Ariadne, integrates with Starlette for serving GraphQL queries and WebSocket subscriptions, providing modern and efficient queryable access to a Tango Control System. This documentation outlines the server setup, key routes, middleware configuration, and resolver functionality.

Server Setup

The production server is set up using Ariadne’s ASGI GraphQL handler integrated into a Starlette application. The handler manages both HTTP routes and WebSocket connections to serve GraphQL queries and subscriptions.

The key components include:

  • GraphQL Handler: This is responsible for processing incoming GraphQL queries and mutations.

  • Context: A custom get_context_value function is used to inject request-specific data into the resolver context.

  • Routes: The server supports HTTP requests via /db and WebSocket subscriptions via /socket.

  • Middleware: CORS middleware is added to handle cross-origin requests, allowing interactions from any origin.

Middleware

The CORS (Cross-Origin Resource Sharing) middleware is configured to:

  • Allow requests from any origin (allow_origins=[“*”]).

  • Allow credentials, methods, and headers to ensure full access from external clients.

GraphQL Resolvers

The implementation includes several key resolver functions that handle mutations for interacting with Tango devices. These are built using Ariadne’s ObjectType and decorated with authorization checks.

  • Mutations: The core mutations allow modification of Tango device properties and attributes, as well as execution of device commands.

    1. putDeviceProperty: Allows the setting of device properties using the async TangoDB.

    2. deleteDeviceProperty: Deletes properties from a Tango device.

    3. setAttributeValue: Updates a Tango device’s attribute with a new value and returns the previous value for reference.

    4. executeCommand: Executes a Tango device command, optionally with arguments.

Each mutation is wrapped with an authorization check using the @check_auth decorator to verify if the client has the required credentials and group memberships before proceeding with the operation.

Error Handling

Each resolver is designed to handle common errors, such as:

  • tango.DevFailed exceptions when device operations fail.

  • TypeError exceptions when the input argument types are invalid.

Error messages are logged for debugging purposes, and a standard response structure is returned to the client indicating the success or failure of the operation.

Authentication and Authorization

The authentication mechanism relies on JWT (JSON Web Tokens) stored in client cookies. These tokens are verified on each request to ensure that the user is logged in and belongs to the required groups.

  • Auth Claims: The authentication information is extracted from the taranta_jwt cookie and verified using the application’s secret key.

  • Authorization Checks: The check_auth decorator enforces that only authorized users (those belonging to the necessary groups) can perform certain operations. This can be disabled globally by setting the NO_AUTH environment variable, allowing all requests to bypass authentication.

Custom GraphQL errors are defined for handling authentication and authorization issues:

  • AuthenticationError: Raised when the user is not logged in.

  • AuthorizationError: Raised when the user does not belong to the required groups to execute a specific operation.

Summary of Key Functionalities:

  1. GraphQL Queries: Serve queries and mutations through HTTP and WebSocket routes using Ariadne’s GraphQL handler.

  2. Mutations: Support for key operations such as setting device properties, writing attributes, and executing commands on Tango devices.

  3. Authorization: JWT-based authentication with group membership enforcement to control access to resolvers.

  4. Error Handling: Robust logging and exception management for Tango device operations and input validation.