Skip to content

Latest commit

 

History

History
143 lines (97 loc) · 4.52 KB

README.md

File metadata and controls

143 lines (97 loc) · 4.52 KB
Raw

htsget-actix

MIT licensed Build Status

Framework dependent code for a local instance of htsget-rs, using Actix Web.

Overview

This crate is used for running a local instance of htsget-rs. It is based on:

  • Actix Web for endpoints, routes, and middleware.
  • htsget-http for htsget-rs specific HTTP responses

Usage

For running htsget-rs as an application

This crate uses htsget-config for configuration. See htsget-config for details on how to configure this crate.

To run an instance of this crate, execute the following command:

cargo run -p htsget-actix

Using the default configuration, this will start a ticket server on 127.0.0.1:8080 and a data block server on 127.0.0.1:8081 with data accessible from the data directory.

To use S3Storage, compile with the s3-storage feature:

cargo run -p htsget-actix --features s3-storage

This will start a ticket server with S3Storage using a bucket called "data".

To use UrlStorage, compile with the url-storage feature.

See htsget-search for details on how to structure files.

Using TLS

There two server instances that are launched when running this crate. The ticket server, which returns a list of ticket URLs that a client must fetch. And the data block server, which responds to the URLs in the tickets. By default, the data block server runs without TLS. To run the data block server with TLS, pem formatted X.509 certificates are required.

For development and testing purposes, self-signed certificates can be used. For example, to generate self-signed certificates run:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 365 -nodes -subj '/CN=localhost'

It is not recommended to use self-signed certificates in a production environment as this is considered insecure.

Example requests

Using default configuration settings, this crate responds to queries referencing files in the data directory. Some example requests using curl are shown below:

  • GET
curl '127.0.0.1:8080/variants/data/vcf/sample1-bcbio-cancer'
  • POST
curl --header "Content-Type: application/json" -d '{}' '127.0.0.1:8080/variants/data/vcf/sample1-bcbio-cancer'
  • Parametrised GET
curl '127.0.0.1:8080/variants/data/vcf/sample1-bcbio-cancer?format=VCF&class=header'
  • Parametrised POST
curl --header "Content-Type: application/json" -d '{"format": "VCF", "regions": [{"referenceName": "chrM"}]}' '127.0.0.1:8080/variants/data/vcf/sample1-bcbio-cancer'
  • Service info
curl '127.0.0.1:8080/variants/service-info'

As a library

There shouldn't be any need to interact with this crate as a library, however some functions which deal with configuring routes are exposed in the public API.

Feature flags

This crate has the following features:

  • s3-storage: used to enable S3Storage functionality.
  • url-storage: used to enable UrlStorage functionality.

Benchmarks

Benchmarks for this crate written using Criterion.rs, and aim to compare the performance of this crate with the htsget Reference Server. There are a set of light benchmarks, and one heavy benchmark. Light benchmarks can be performed by executing:

cargo bench -p htsget-actix -- LIGHT

To run the heavy benchmark, an additional vcf file needs to be downloaded, and placed in the data/vcf directory:

curl ftp://ftp.1000genomes.ebi.ac.uk/vol1/ftp/data_collections/1000_genomes_project/release/20190312_biallelic_SNV_and_INDEL/ALL.chr14.shapeit2_integrated_snvindels_v2a_27022019.GRCh38.phased.vcf.gz > data/vcf/internationalgenomesample.vcf.gz

Then to run the heavy benchmark:

cargo bench -p htsget-actix -- HEAVY

License

This project is licensed under the MIT license.