Intro

An implementation of the GA4GH Discovery Data Connect API, on top of Trino. This software enables users to enumerate and query data surfaced by an instance of Trino in a manner compliant with the GA4GH Discovery Data Connect specification, and receive responses compliant with the Table specification.

Updating This README

Any structural changes to this README should be checked against the README_TEMPLATE available in dnastack-development-tools, with that document updated as necessary.

Quick Start

Get started in 30s.

Prerequisites

• Java 21+
• A trino server you can access anonymously over HTTP(S).
• Maven credentials for DNAstack's GitHub Packages repository. See Maven Repository Credentials.

Build

mvn clean package

Configure

Set these environment variables.

TRINO_DATASOURCE_URL=https://<your-trino-server>
SPRING_PROFILES_ACTIVE=no-auth

The data connect adapter requires a Postgres database. To start the app locally quickly with the default settings, you can spin up the database with this docker command:

docker run -d -p 5432:5432 --name dataconnecttrino -e POSTGRES_USER=dataconnecttrino -e POSTGRES_PASSWORD=dataconnecttrino postgres

Or if you already have a local postgres installed, configure a user and a database:

CREATE USER dataconnecttrino PASSWORD 'dataconnecttrino' CREATEDB CREATEROLE;
CREATE DATABASE dataconnecttrino OWNER dataconnecttrino;

Run

mvn clean spring-boot:run

Maven Repository Credentials

This project's parent POM (com.dnastack.starter:spring-boot-parent) and its multi-tenancy libraries (com.dnastack:spring-boot-tenancy-*) are published to https://maven.pkg.github.com/DNAstack/dnastack-packages. GitHub Packages requires an authenticated identity to read a Maven package, so the build cannot resolve them anonymously and fails while reading the POM, before it compiles anything.

Put a GitHub personal access token with read:packages in your ~/.m2/settings.xml. The repository and the server must share an id.

<profiles>
    <profile>
        <id>github</id>
        <repositories>
            <repository>
                <id>github</id>
                <name>Github DNAstack Maven Packages</name>
                <url>https://maven.pkg.github.com/DNAstack/dnastack-packages</url>
            </repository>
        </repositories>
    </profile>
</profiles>
<servers>
    <server>
        <id>github</id>
        <username>$GITHUB_USERNAME</username>
        <password>$PERSONAL_ACCESS_TOKEN</password>
    </server>
</servers>
<activeProfiles>
    <activeProfile>github</activeProfile>
</activeProfiles>

The ci/build-docker-* scripts copy ~/.m2/*.xml into the Docker build context so that the Maven runs inside each image build resolve against the same credentials. Every Dockerfile that receives the file deletes it once dependencies are resolved, and the stage holding it is discarded before the shipped image is assembled.

Configuring (Advanced)

Auth Profiles

The app can be deployed using one of 3 different spring profiles which configure the authentication expectations. The default profile will be used if no other profile is activated.

Each profile also enables the following set of spring configuration variables:

APP_AUTH_AUTHORIZATIONTYPE="bearer" or "basic" or "none"
APP_AUTH_ACCESSEVALUATOR="wallet" # only applies when AUTHORIZATIONTYPE=bearer
APP_AUTH_GLOBALMETHODSECURITY_ENABLED=true or false # enables security annotations on REST endpoints 

To set a profile simply set the SPRING_PROFILES_ACTIVE environment variable to one of the three profiles outlined below:

wallet-auth (Wallet Authentication - DNAstack)

The wallet-auth profile requires every inbound request to include a JWT, validated by the settings configured below. The configuration is described by the AuthConfig class. This is the profile used if no profile is set.

# (Required) The STS which issued this token.
APP_AUTH_TOKENISSUERS_0_ISSUERURI="https://your.expected.issuer.com"
# (Required) The Json Web Key Set URI (where to find token validation keys)
APP_AUTH_TOKENISSUERS_0_JWKSETURI="https://your.expected.issuer/oauth/jwks"
# (Optional) Set audience if you want your token's audience to be validated.
APP_AUTH_TOKENISSUERS_0_AUDIENCES_0_="ga4gh-search-adapter-presto"
# (Optional) Set scopes if you want your token's scopes to be validated. Set multiple with _SCOPES_1_, SCOPES_2_...
APP_AUTH_TOKENISSUERS_0_SCOPES_0_="read:*"

Token validation in this mode requires resource and action claims issued in the form of DNAstack's Wallet authorization server.

no-auth (No Authentication)

DO NOT USE IN PRODUCTION

This profile will publicly expose all routes and does not require any authentication. Best left in your dev environment.

basic-auth (Basic Authentication)

This profile will protect API routes with basic authentication. Additionally, when a user makes a request, if they have not logged in they will be redirected to a login screen. The default username is user, and the default password is set in the application.yaml.

To configure the username and password, set the following environment variables:

SPRING_SECURITY_USER_NAME={some-user-name}
SPRING_SECURITY_USER_PASSWORD={some-password}

Multi-Tenancy

Every API path has a tenant-scoped form alongside it: /tenants/{tenantId}/search, /tenants/{tenantId}/tables, and so on. The un-prefixed paths remain, and act as the management tenant, so callers that predate tenancy are unaffected. service-info and the actuator endpoints are instance-scoped so they have no tenant.

Using the spring-boot-tenancy-lifecycle library, this service maintains a local copy of wallet's tenant directory and keeps it current by polling Wallet's tenant changefeed endpoint. This service rejects requests for unknown and disabled tenants with a 404 before invoking any controller methods.

This service uses the validated tenantId to scope queries, and to propagate the requested tenant in onward calls.

Two switches, both disabled by default, control the behavior of the service with respect to tenancy.

# LOG_ONLY -> ACCEPT_TENANTLESS -> REQUIRE_TENANT
APP_TENANCY_ENFORCEMENT=LOG_ONLY
# The poller that mirrors wallet's tenant directory. Tenant-scoped paths 404 until this has run.
TENANTLIFECYCLE_ENABLED=false

Postgres Configuration

The data connect adapter uses a PostgreSQL database to save queries, so that it can reparse them during pagination to re-evaluate functions that need to be processed prior to submitting queries to trino.

The following is a quick start for local development:

docker pull postgres:latest
docker run -p 5432:5432 --rm --name ga4ghsearchadapterpresto -e POSTGRES_USER=ga4ghsearchadapterpresto -e POSTGRES_DB=ga4ghsearchadapterpresto -e POSTGRES_PASSWORD=ga4ghsearchadapterpresto postgres

Trino Source Configuration

There are a number of required configuration properties that need to be set in order to communicate with a trino deployment.

Connectivity

Point the service to a trino server by setting the following environment variable:

TRINO_DATASOURCE_URL

Authentication

If your trino instance is also protected, this adapter supports performing OAuth 2.0 Client Credential grants in order to retrieve access tokens for its configured Trino instance.

Configuration of the trino auth setup is quite easy and can be done directly through the following environment variables.

APP_AUTH_TRINOOAUTHCLIENT_TOKENURI="https://your.sts/oauth/token"
APP_AUTH_TRINOOAUTHCLIENT_CLIENTID="your-client-id"
APP_AUTH_TRINOOAUTHCLIENT_CLIENTSECRET="your-client-secret"
APP_AUTH_TRINOOAUTHCLIENT_AUDIENCE="your-requested-audience"
APP_AUTH_TRINOOAUTHCLIENT_SCOPES="your space delimited requested scopes"