Summary

nf-drs is a Nextflow plugin for accessing GA4GH DRS objects with drs:// URIs — including Gen3 commons such as NCI CRDC, AnVIL, and BioData Catalyst.

Write file('drs://<host>/<object_id>') anywhere a path is expected (process inputs, samplesheets, Channel.fromPath) and the plugin resolves the object to a presigned URL and streams it, transparently. It registers a read-only NIO filesystem for the drs URI scheme, so no special syntax is needed.

DRS resolution is a GA4GH standard and identical across servers:

1. GET https://<host>/ga4gh/drs/v1/objects/<object_id> → object metadata + access methods
2. GET https://<host>/ga4gh/drs/v1/objects/<object_id>/access/<access_id> → presigned URL
3. stream the presigned URL

Only authentication differs between servers, so it is pluggable via drs.authProvider:

provider	behaviour	status
gen3 (default)	Exchanges a Gen3 api_key for a short-lived bearer token at the Fence token endpoint (/user/credentials/cdis/access_token), caches it per host, refreshes on expiry/401. Mirrors gen3.auth.Gen3Auth.	Implemented and verified end-to-end against NCI CRDC.
bearer	Sends a directly-supplied OAuth2 access token unchanged.	Implemented and unit-tested; not yet validated against a live server.
none	Public/open objects; no Authorization header.	Implemented and unit-tested; not yet validated against a live server.

The DRS server host is always taken from the URI — no commons is hardcoded.

Get Started

Enable the plugin and configure auth in nextflow.config:

plugins {
    id 'nf-drs@0.1.0'
}

drs {
    authProvider = 'gen3'          // 'gen3' | 'bearer' | 'none'
    authSecret = 'GEN3_API_KEY'    // Nextflow secret holding the credential
    // tokenEndpointPath = '/user/credentials/cdis/access_token'  // gen3 only
    // accessProtocol = 's3'       // prefer a specific access method (else: s3, gs, first)
}

Set the credential as a Nextflow secret:

# gen3: the "api_key" value from your Gen3 credentials.json
nextflow secrets set GEN3_API_KEY <api_key>

# bearer: an OAuth2 access token
nextflow secrets set GEN3_API_KEY <access_token>

For Gen3/CRDC controlled-access data you must first be authorized (e.g. dbGaP approval for the relevant study) and download an API key from the commons' portal.

Examples

Access a DRS object directly:

workflow {
    bam = file('drs://nci-crdc.datacommons.io/dg.4DFC/0123-4567-89ab')
    FASTQC(bam)
}

Read DRS URIs from a samplesheet:

Channel.fromPath('samples.csv')
    .splitCsv(header: true)
    .map { row -> tuple(row.sample_id, file(row.drs_uri)) }
    | FASTQC

sample_id,drs_uri
sample1,drs://nci-crdc.datacommons.io/dg.4DFC/0123-4567-89ab

A runnable validation pipeline is provided under validation/:

nextflow secrets set GEN3_API_KEY <api_key>
nextflow run validation/main.nf \
  --drs_host nci-crdc.datacommons.io \
  --object_id dg.4DFC/<guid>

License

Apache License 2.0. See COPYING.