test: add more robust start/end range tests and document suppressed errors with diagrams.

Author: mmalenic

htsget-axum/src/middleware/auth.rs

@@ -9,43 +9,44 @@ use htsget_http::middleware::auth::Auth;
 use std::task::{Context, Poll};
 use tower::{Layer, Service};
 
-impl From<Auth> for AuthLayer {
+impl From<Auth> for AuthenticationLayer {
   fn from(auth: Auth) -> Self {
     Self { inner: auth }
   }
 }
 
 /// A wrapper around the authentication layer.
 #[derive(Clone)]
-pub struct AuthLayer {
+pub struct AuthenticationLayer {
   inner: Auth,
 }
 
-impl AuthLayer {
+impl AuthenticationLayer {
   /// Get the inner auth layer.
   pub fn inner(&self) -> &Auth {
     &self.inner
   }
 }
 
-impl<S> Layer<S> for AuthLayer {
-  type Service = AuthMiddleware<S>;
+impl<S> Layer<S> for AuthenticationLayer {
+  type Service = AuthenticationMiddleware<S>;
 
   fn layer(&self, inner: S) -> Self::Service {
-    AuthMiddleware::new(inner, self.clone())
+    AuthenticationMiddleware::new(inner, self.clone())
   }
 }
 
-/// A wrapper around the auth middleware.
+/// A wrapper around the authentication middleware. This middleware only handles
+/// authentication of a JWT token.
 #[derive(Clone)]
-pub struct AuthMiddleware<S> {
+pub struct AuthenticationMiddleware<S> {
   inner: S,
-  layer: AuthLayer,
+  layer: AuthenticationLayer,
 }
 
-impl<S> AuthMiddleware<S> {
+impl<S> AuthenticationMiddleware<S> {
   /// Create a new middleware auth.
-  pub fn new(inner: S, layer: AuthLayer) -> Self {
+  pub fn new(inner: S, layer: AuthenticationLayer) -> Self {
     Self { inner, layer }
   }
 
@@ -55,12 +56,12 @@ impl<S> AuthMiddleware<S> {
   }
 
   /// Get the layer.
-  pub fn layer(&self) -> &AuthLayer {
+  pub fn layer(&self) -> &AuthenticationLayer {
     &self.layer
   }
 }
 
-impl<S> Service<Request> for AuthMiddleware<S>
+impl<S> Service<Request> for AuthenticationMiddleware<S>
 where
   S: Service<Request, Response = Response> + Clone + Send + 'static + Sync,
   S::Future: Send + 'static,

htsget-config/README.md

@@ -422,8 +422,8 @@ following JSON structure, indicating whether the request is allowed, and any reg
         {
           "name": "chr1",
           "format": "BAM",
-          "start": 100,
-          "end": 1000
+          "start": 1000,
+          "end": 2000
         }
       ]
     }
@@ -439,18 +439,18 @@ An [example][auth-example] configuration file is available in the examples direc
 With this authorization logic, the server will respond with a `403 Forbidden` error if any of the requested reference
 names are not allowed according to the restrictions. For example, if using the above JSON restrictions, a user
 requesting `?referenceName=chr1&format=BAM&start=500&end=1500` will receive a `403` error, even though part of the range
-is satisfiable (i.e. according to the restrictions, from `start=500` to `end=1000`). In order to address this issue, the
+is satisfiable (i.e. according to the restrictions, from `start=1000` to `end=1500`). In order to address this issue, the
 following flag can be enabled under the `auth` table:
 
 | Option            | Description                                                                                      | Type    | Default |
 |-------------------|--------------------------------------------------------------------------------------------------|---------|---------|
 | `suppress_errors` | Return any available regions according to restrictions, even if the full request is not allowed. | Boolean | `false` |
 | `add_hint`        | Add a hint to the ticket response that indicates which regions the client is allowed to view.    | Boolean | `true`  |
 
-To enable this option, htsget-rs needs to be compiled with `--features experimental` as suppressed errors may lead to
-less regions being returned than requested, which may not follow the htsget protocol. When this option is used, the
-above example with the request: `?referenceName=chr1&format=BAM&start=500&end=1500`, would return reads between `start=500`
-and `end=1000` for the reference name. Additionally, there will be another field present in the JSON response which hints
+To enable this option, htsget-rs needs to be compiled with `--features experimental` as suppressed errors lead to as
+many regions as possible being returned, which may not follow the htsget protocol. When this option is used, the
+above example with the request: `?referenceName=chr1&format=BAM&start=500&end=1500`, would return reads between `start=1000`
+and `end=1500` for the reference name. Additionally, there will be another field present in the JSON response which hints
 to clients that the full range was not satisfied because of authorization restrictions:
 
 ```json
@@ -462,22 +462,43 @@ to clients that the full range was not satisfied because of authorization restri
       {
         "name": "chr1",
         "format": "BAM",
-        "start": 100,
-        "end": 1000
+        "start": 1000,
+        "end": 2000
       }
     ] 
   }
 }            
 ```
 
 The `allowed` field echos the rule defined in the restrictions, and allows clients to plan for a partially returned
-response. This field can be removed by setting `add_hint = false` in the `auth` table. 
+response. This field can be removed by setting `add_hint = false` in the `auth` table.
+
+The following diagram shows how the suppressed response behaves given restrictions based on the start and end restrictions
+and the requested range. The response shows the data that the user will receive.
+
+```
+Restriction:                 1000----------2000
+Request:             500------------1500
+Resulting response:          1000---1500
+
+Restriction:                 1000----------2000
+Request:                            1500------------2500
+Resulting response:                 1500---2000
+
+Restriction:                 1000----------2000
+Request:             500-----1000
+Resulting response:          empty header only
+```
+
+If `suppress_errors = true` was not used, all the above requests would result in an error instead.
 
 Note that when using `suppress_errors = true`, when a client is not authorization to view any of the requested regions,
-a non-error response is still returned with an empty reads/variants set. For example, if the client was not authorized
-to view `chr1` at all, the response would return urls that correspond to a valid file (with the file header and EOF block),
-but no actual reads data. Authorization error responses are still returned if the JWT is invalid or the client is not
-allowed to view the requested `<id>` path.
+a non-error response is still returned with an empty response containing the file header. For example, if the
+client was not authorized to view `chr1` at all, the response would return urls that correspond to a valid file
+(with the file header and EOF block), but no actual reads data. Authorization error responses are still returned if the
+JWT is invalid or the client is not allowed to view the requested `<id>` path. Parameters are only checked for validity
+after authorizing the request, so invalid requests may return an unauthorized or forbidden response instead of a bad
+request if the user lacks authorization.
 
 [auth-json]: docs/schemas/auth.schema.json
 [auth-example]: docs/examples/auth.toml