From 86e8cf47d4a92afbf720c03104413ea5b4ed8f33 Mon Sep 17 00:00:00 2001
From: Paschalis Tsilias <tpaschalis@users.noreply.github.com>
Date: Tue, 30 Jul 2024 18:08:16 +0300
Subject: [PATCH] Allow setting Headers in DownloadableFile message (#197)

Fixes #194

This PR amends the spec and protos to include an optional set of headers in DownloadableFile, to be used in the download GET request to set up auth parameters.

This is only one of the ways we could implement setting authentication paramaters to be used by Agents when downloading packages, but it is consistent with other uses of the headers field and generic enough to cover different use cases so I feel it's worth considering.
---
 proto/opamp.proto |  8 ++++++++
 specification.md  | 16 +++++++++++++++-
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/proto/opamp.proto b/proto/opamp.proto
index e8d9dfa..1e233c4 100644
--- a/proto/opamp.proto
+++ b/proto/opamp.proto
@@ -515,6 +515,14 @@ message DownloadableFile {
     // https://github.com/open-telemetry/opamp-spec/blob/main/specification.md#code-signing
     // for recommendations.
     bytes signature = 3;
+
+    // Optional headers to use when downloading a file. Typically used to set
+    // access tokens or other authorization headers. For HTTP-based protocols
+    // the Agent should set these in the request headers.
+    // For example:
+    // key="Authorization", Value="Basic YWxhZGRpbjpvcGVuc2VzYW1l".
+    // Status: [Development]
+    Headers headers = 4;
 }
 
 message ServerErrorResponse {
diff --git a/specification.md b/specification.md
index a9027d9..e86953a 100644
--- a/specification.md
+++ b/specification.md
@@ -154,6 +154,7 @@ Status: [Beta]
       - [DownloadableFile.download_url](#downloadablefiledownload_url)
       - [DownloadableFile.content_hash](#downloadablefilecontent_hash)
       - [DownloadableFile.signature](#downloadablefilesignature)
+      - [DownloadableFile.headers](#downloadablefileheaders)
   * [Custom Messages](#custom-messages)
     + [Motivation](#motivation)
     + [CustomCapabilities](#customcapabilities)
@@ -2412,7 +2413,9 @@ should download the file:
   and the file SHOULD be downloaded from the location specified in the
   [download_url](#downloadablefiledownload_url) field of the
   [DownloadableFile](#downloadablefile-message) message. The Agent SHOULD use an
-  HTTP GET message to download the file.
+  HTTP GET message to download the file. The Agent SHOULD include the HTTP
+  headers provided in the [headers](#downloadablefileheaders) field for the GET
+  request.
 
 The procedure outlined above allows the Agent to efficiently download only new
 or changed packages and only download new or changed files.
@@ -2605,6 +2608,7 @@ message DownloadableFile {
     string download_url = 1;
     bytes content_hash = 2;
     bytes signature = 3;
+    headers headers = 4; // Status: [Development]
 }
 ```
 
@@ -2627,6 +2631,16 @@ authenticity of the downloaded file, for example can be the
 The exact signing and verification method is Agent specific. See
 [Code Signing](#code-signing) for recommendations.
 
+##### DownloadableFile.headers
+
+Status: [Development]
+
+Optional headers to use for the HTTP GET request. Typically used to set access
+tokens or other authorization headers. For HTTP-based protocols the Agent
+should set these in the request headers.
+For example:
+key="Authorization", Value="Basic YWxhZGRpbjpvcGVuc2VzYW1l".
+
 ### Custom Messages
 
 Status: [Development]