From 6fc44a67b911cead1513e6ddb517f56dd509663b Mon Sep 17 00:00:00 2001
From: Tom Clegg <tom@curoverse.com>
Date: Fri, 1 May 2015 00:59:20 -0400
Subject: [PATCH] 5724: Add blobSignatureTtl to discovery doc. Add config
 comment/explanation.

---
 .../arvados/v1/schema_controller.rb           |  1 +
 services/api/app/models/collection.rb         |  4 ++--
 services/api/config/application.default.yml   | 20 ++++++++++++++++---
 3 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/services/api/app/controllers/arvados/v1/schema_controller.rb b/services/api/app/controllers/arvados/v1/schema_controller.rb
index dcc9c63979..62d5e59c8d 100644
--- a/services/api/app/controllers/arvados/v1/schema_controller.rb
+++ b/services/api/app/controllers/arvados/v1/schema_controller.rb
@@ -35,6 +35,7 @@ class Arvados::V1::SchemaController < ApplicationController
         servicePath: "arvados/v1/",
         batchPath: "batch",
         defaultTrashLifetime: Rails.application.config.default_trash_lifetime,
+        blobSignatureTtl: Rails.application.config.blob_signature_ttl,
         maxRequestSize: Rails.application.config.max_request_size,
         parameters: {
           alt: {
diff --git a/services/api/app/models/collection.rb b/services/api/app/models/collection.rb
index 89ad874cd7..ccfb35e496 100644
--- a/services/api/app/models/collection.rb
+++ b/services/api/app/models/collection.rb
@@ -60,7 +60,7 @@ class Collection < ArvadosModel
       signing_opts = {
         key: Rails.configuration.blob_signing_key,
         api_token: api_token,
-        ttl: Rails.configuration.blob_signing_ttl,
+        ttl: Rails.configuration.blob_signature_ttl,
       }
       self.manifest_text.lines.each do |entry|
         entry.split[1..-1].each do |tok|
@@ -195,7 +195,7 @@ class Collection < ArvadosModel
     signing_opts = {
       key: Rails.configuration.blob_signing_key,
       api_token: token,
-      ttl: Rails.configuration.blob_signing_ttl,
+      ttl: Rails.configuration.blob_signature_ttl,
     }
     m = manifest.dup
     munge_manifest_locators!(m) do |loc|
diff --git a/services/api/config/application.default.yml b/services/api/config/application.default.yml
index e7dbf29c59..b57c0165cf 100644
--- a/services/api/config/application.default.yml
+++ b/services/api/config/application.default.yml
@@ -220,9 +220,23 @@ common:
   # a site secret. It should be at least 50 characters.
   blob_signing_key: ~
 
-  # Amount of time (in seconds) for which a blob permission signature
-  # remains valid.  Default: 2 weeks (1209600 seconds)
-  blob_signing_ttl: 1209600
+  # Lifetime (in seconds) of blob permission signatures generated by
+  # the API server. This determines how long a client can take (after
+  # retrieving a collection record) to retrieve the collection data
+  # from Keep. If the client needs more time than that (assuming the
+  # collection still has the same content and the relevant user/token
+  # still has permission) the client can retrieve the collection again
+  # to get fresh signatures.
+  #
+  # Datamanager considers an unreferenced block older than this to be
+  # eligible for garbage collection. Therefore, it should never be
+  # smaller than the corresponding value used by any local keepstore
+  # service (see keepstore -blob-signing-ttl flag). This rule prevents
+  # datamanager from trying to garbage-collect recently written blocks
+  # while clients are still holding valid signatures.
+  #
+  # The default is 2 weeks.
+  blob_signature_ttl: 1209600
 
   # Allow clients to create collections by providing a manifest with
   # unsigned data blob locators. IMPORTANT: This effectively disables
-- 
2.30.2