Provide guidance on how users should be doing "freshness" checks on install scripts

[richlander]

We would like to be able to write a test that validates if our CDN copy matches repo copy. I know that GitHub Actions does this as well. This would help ensure that users only pickup up copies that we have high confidence in and only feel compelled to update their script at (no more than) a monthly cadence. Basing that all off of main seems like not the best model.

[richlander]

@heavymachinery @zaataylor @mmitche

[baronfel]

Some of the assets we serve are artifacts from an internal pipeline - I'm specifically thinking of dotnet-install.ps1 in its signed form and dotnet-install.sig, both of which are changed/computed by the act of signing.

Are you thinking of something like a completely separate branch that contains the derived assets that gets tagged or something? Similar to how gh-pages deployments kind of work?

[richlander]

Let's back up. There should be a way for users to do an update to date check to determine if their private copy of the install script is stale. My question is whether doing that on main is the best approach.

[richlander]

I just wrote a diff script and found that the repo and the CDN don't match. It's due to this change: #562. It's a fine change, just not something we should bother anyone with, who does freshness checks.

Script: https://gist.github.com/richlander/7a78d0421b68554e8cccab33704937c8

[baronfel]

Yep! We were planning on rolling this out with this week's release (which will also include the no_cdn and azureedge removals). We've historically treated the scripts as an evergreen kind of asset, so versioning has been mostly focused on compatibility.

[JanProvaznik]

historically we did not treat main as a reliable source of most up to date released version, there could be merged undeployed changes until one that's worth deploying for comes or enough small things accumulate (usually 1-2 weeks lag). The source of truth was https://dot.net/v1/dotnet-install.sh but that's not versioned here, but in the website.

[richlander]

I changed the title of the issue.

I'm happy with the model proposed by @JanProvaznik. That didn't occur to me. I can add that to a guidance doc that I need to write.

[richlander]

Can I make you a deal @baronfel? I'll write the guidance. Can you write a sample Actions workflow that does a freshness check and fails a PR (if that's the right model) if the check fails?

[baronfel]

@richlander do you know if we've got ETags turned on for this content? I was doing some curling and while we send ETags on the requests, I can't seem to get a consistent HTTP 304 response (which is what I would expect when the correct ETag is sent in the If-None-Match header.

Here's what I would expect to work (note: the ETag value provided in the If-None-Match header):

> curl -v --header 'If-None-Match: 0x8DD2F3D8D65F264'  https://builds.dotnet.microsoft.com/dotnet/scripts/v1/dotnet-install.sh -o dotnet-install.sh
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0* Host builds.dotnet.microsoft.com:443 was resolved.
* IPv6: 2600:1404:ec00:59::1735:7f64, 2600:1404:ec00:59::1735:7f6e
* IPv4: 13.107.246.51
*   Trying 13.107.246.51:443...
* Connected to builds.dotnet.microsoft.com (13.107.246.51) port 443
* ALPN: curl offers h2,http/1.1
} [5 bytes data]
* TLSv1.3 (OUT), TLS handshake, Client hello (1):
} [512 bytes data]
*  CAfile: /etc/ssl/certs/ca-certificates.crt
*  CApath: /etc/ssl/certs
{ [5 bytes data]
* TLSv1.3 (IN), TLS handshake, Server hello (2):
{ [88 bytes data]
* TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1):
} [1 bytes data]
* TLSv1.3 (OUT), TLS handshake, Client hello (1):
} [512 bytes data]
* TLSv1.3 (IN), TLS handshake, Server hello (2):
{ [155 bytes data]
* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8):
{ [19 bytes data]
* TLSv1.3 (IN), TLS handshake, Certificate (11):
{ [4419 bytes data]
* TLSv1.3 (IN), TLS handshake, CERT verify (15):
{ [264 bytes data]
* TLSv1.3 (IN), TLS handshake, Finished (20):
{ [52 bytes data]
* TLSv1.3 (OUT), TLS handshake, Finished (20):
} [52 bytes data]
* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384 / prime256v1 / RSASSA-PSS
* ALPN: server accepted h2
* Server certificate:
*  subject: CN=builds.dotnet.microsoft.com
*  start date: Dec 23 00:00:00 2024 GMT
*  expire date: Jun 23 23:59:59 2025 GMT
*  subjectAltName: host "builds.dotnet.microsoft.com" matched cert's "builds.dotnet.microsoft.com"
*  issuer: C=US; O=DigiCert, Inc.; CN=GeoTrust Global TLS RSA4096 SHA256 2022 CA1
*  SSL certificate verify ok.
*   Certificate level 0: Public key type RSA (2048/112 Bits/secBits), signed using sha256WithRSAEncryption
*   Certificate level 1: Public key type RSA (4096/152 Bits/secBits), signed using sha256WithRSAEncryption
*   Certificate level 2: Public key type RSA (2048/112 Bits/secBits), signed using sha1WithRSAEncryption
} [5 bytes data]
* using HTTP/2
* [HTTP/2] [1] OPENED stream for https://builds.dotnet.microsoft.com/dotnet/scripts/v1/dotnet-install.sh
* [HTTP/2] [1] [:method: GET]
* [HTTP/2] [1] [:scheme: https]
* [HTTP/2] [1] [:authority: builds.dotnet.microsoft.com]
* [HTTP/2] [1] [:path: /dotnet/scripts/v1/dotnet-install.sh]
* [HTTP/2] [1] [user-agent: curl/8.5.0]
* [HTTP/2] [1] [accept: */*]
* [HTTP/2] [1] [if-none-match: 0x8DD2F3D8D65F264]
} [5 bytes data]
> GET /dotnet/scripts/v1/dotnet-install.sh HTTP/2
> Host: builds.dotnet.microsoft.com
> User-Agent: curl/8.5.0
> Accept: */*
> If-None-Match: 0x8DD2F3D8D65F264
>
{ [5 bytes data]
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
{ [281 bytes data]
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
{ [281 bytes data]
* old SSL session ID is stale, removing
{ [5 bytes data]
< HTTP/2 304
< date: Thu, 09 Jan 2025 02:45:31 GMT
< last-modified: Tue, 07 Jan 2025 17:05:56 GMT
< etag: 0x8DD2F3D8D65F264
< x-ms-request-id: db4f3541-a01e-0036-4f21-62e810000000
< x-ms-version: 2009-09-19
< x-ms-lease-status: unlocked
< x-ms-blob-type: BlockBlob
< x-azure-ref: 20250109T024531Z-18664c4f4d4fjq94hC1CH195dn000000146000000000fe2f
< x-fd-int-roxy-purgeid: 0
< x-cache: TCP_HIT
< x-cache-info: L1_T2
<
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
* Connection #0 to host builds.dotnet.microsoft.com left intact

This returns a 304 as expected (Not Modified). However, for me, repeated execution of this curl command often returns 200 codes, redownloading the script.

It's very flaky. I'm wondering a) CDN setup, but also B) the Etag in use is malformed - it should be quoted. Per Akamai's docs the CDN might need configured to allow out-of-spec Etags (though of course we should figure out what's generating this etag value...).

[baronfel]

I did some testing locally and ASP.NET does correctly compute a valid ETag and response with 304's out-of-the-box, so I'm wondering if there's some configuration at the storage bucket or CDN layer that's not correct?