Add Base64DecodingStream (#8226)

## Summary of changes

Adds `Base64DecodingStream` helper class

## Reason for change

In a few places (particularly Remote Config and Newtonsoft.JSON) we have
code like this:

```csharp
string someValue = // 
var contentDecode = Convert.FromBase64String(someValue);
using var stream = new MemoryStream(contentDecode);
```

This takes an existing `string`, decodes it from base64 to a `byte[]`,
then feeds that `byte[]` into a `MemoryStream`. For big strings, that's
a potentially large extra array allocation we can avoid. Instead,
`Base64DecodingStream` acts effectively as a `MemoryStream` over the
`string`, doing the decode either on the fly (.NET Core), or by using a
pooled buffer to decode the input string in chunks.

## Implementation details

Basically asked 🤖 Claude to do this, then reviewed and tidied up and
iterated. The general idea is:

- Keep track of where in the string we are
- **.NET Framework/.NET Standard only**
- Decode the next section of the string into an array-pool rented
buffer, using the vendored `Base64.DecodeFromUtf8InPlace`
  - Copy the buffer into the destination `byte[]`
- **.NET Core only**
- Decode the next section of the string directly into the destination
`Span<T>`

It didn't seem worth trying to unify these two paths, given the lack of
`Convert.TryFromBase64Chars` in .NET Framework. We _could_ use
`Base64.DecodeFromUtf8` to write directly to the destination span
instead, but we would still need to do the narrowing, and doing that in
the destination span is a little risky, as it would mean we write a
bunch of bytes which are then leftover junk. It's _probably_ still fine,
but I don't know that it's worth the complexity/risk.

> [!WARNING]
> Rather than handle the case where you're passed a destination buffer
that's <3 bytes, this implementation currently just throws. Otherwise we
have to decode into a stackallocated buffer, and hang onto the
"overflow" bytes to avoid returning 0 when we're not EOF, which is a bit
of a pain. For the places we currently use it, I don't think this will
be a problem, but if others disagree, we can handle the edge case too.

## Test coverage

Added a variety of unit tests for the implementation

## Other details

https://datadoghq.atlassian.net/browse/LANGPLAT-940

This will be part of a Remote config stack, but for now kept it agnostic

Author: andrewlock

tracer/src/Datadog.Trace/Util/Streams/Base64DecodingStream.cs

@@ -0,0 +1,248 @@
+// <copyright file="Base64DecodingStream.cs" company="Datadog">
+// Unless explicitly stated otherwise all files in this repository are licensed under the Apache 2 License.
+// This product includes software developed at Datadog (https://www.datadoghq.com/). Copyright 2017 Datadog, Inc.
+// </copyright>
+
+#nullable enable
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using System.IO;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Datadog.Trace.Util.Streams;
+
+/// <summary>
+/// A read-only, forward-only <see cref="Stream"/> that decodes a base64-encoded <see cref="string"/>
+/// into its raw bytes on-the-fly, without allocating the full decoded byte array.
+/// </summary>
+/// <remarks>
+/// This stream processes base64 input in chunks, decoding only as much as
+/// the caller requests via <see cref="Read(byte[], int, int)"/>.
+/// The input must be valid base64 with standard padding (no embedded whitespace).
+/// On .NET Core, decodes directly into the caller's buffer with no intermediate allocation.
+/// On .NET Framework, uses <see cref="ArrayPool{T}"/> internally to avoid GC pressure.
+/// </remarks>
+internal sealed class Base64DecodingStream : Stream
+{
+#if !NETCOREAPP
+    /// <summary>
+    /// Maximum number of base64 characters to process per decode operation.
+    /// Must be a multiple of 4 (the base64 quantum size).
+    /// The internal buffer also holds the narrowed ASCII bytes before
+    /// in-place decode, so the buffer size equals this value.
+    /// </summary>
+    private const int CharsPerChunk = 4096;
+#endif
+
+    private readonly string _base64;
+    private int _charPosition;
+
+#if !NETCOREAPP
+    private byte[] _buffer;
+    private int _bufferOffset;
+    private int _bufferCount;
+#endif
+
+    public Base64DecodingStream(string base64)
+    {
+        _base64 = base64 ?? throw new ArgumentNullException(nameof(base64));
+#if !NETCOREAPP
+        _buffer = ArrayPool<byte>.Shared.Rent(CharsPerChunk);
+#endif
+    }
+
+    public override bool CanRead => true;
+
+    public override bool CanSeek => false;
+
+    public override bool CanWrite => false;
+
+    public override long Length => throw new NotSupportedException();
+
+    public override long Position
+    {
+        get => throw new NotSupportedException();
+        set => throw new NotSupportedException();
+    }
+
+#if NETCOREAPP
+    public override int Read(byte[] buffer, int offset, int count)
+        => Read(buffer.AsSpan(offset, count));
+
+    public override int Read(Span<byte> destination)
+    {
+        if (destination.Length == 0 || _charPosition >= _base64.Length)
+        {
+            return 0;
+        }
+
+        var remainingChars = _base64.Length - _charPosition;
+        var maxQuanta = destination.Length / 3;
+
+        if (maxQuanta == 0)
+        {
+            ThrowDestinationTooSmall();
+        }
+
+        var charsToProcess = maxQuanta * 4;
+        if (charsToProcess >= remainingChars)
+        {
+            charsToProcess = remainingChars;
+        }
+
+        if (!Convert.TryFromBase64Chars(
+                _base64.AsSpan(_charPosition, charsToProcess),
+                destination,
+                out var bytesWritten))
+        {
+            ThrowFormatException();
+        }
+
+        _charPosition += charsToProcess;
+        return bytesWritten;
+    }
+
+    public override ValueTask<int> ReadAsync(Memory<byte> buffer, CancellationToken cancellationToken = default)
+    {
+        return cancellationToken.IsCancellationRequested
+                   ? new ValueTask<int>(Task.FromCanceled<int>(cancellationToken))
+                   : new ValueTask<int>(Read(buffer.Span));
+    }
+#else
+    public override int Read(byte[] buffer, int offset, int count)
+    {
+        if (count == 0)
+        {
+            return 0;
+        }
+
+        // Added for consistency with .NET Core case
+        if (count < 3)
+        {
+            ThrowDestinationTooSmall();
+        }
+
+        var totalRead = 0;
+
+        while (count > 0)
+        {
+            // Drain any previously decoded bytes still in the internal buffer
+            var available = _bufferCount - _bufferOffset;
+            if (available > 0)
+            {
+                var toCopy = Math.Min(count, available);
+                Buffer.BlockCopy(_buffer, _bufferOffset, buffer, offset, toCopy);
+                _bufferOffset += toCopy;
+                offset += toCopy;
+                count -= toCopy;
+                totalRead += toCopy;
+                continue;
+            }
+
+            // No buffered bytes remain — decode another chunk from the input string
+            if (_charPosition >= _base64.Length)
+            {
+                break;
+            }
+
+            DecodeNextChunk();
+        }
+
+        return totalRead;
+    }
+#endif
+
+    public override Task<int> ReadAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken)
+    {
+        return cancellationToken.IsCancellationRequested
+                   ? Task.FromCanceled<int>(cancellationToken)
+                   : Task.FromResult(Read(buffer, offset, count));
+    }
+
+    public override void Flush()
+    {
+    }
+
+    public override long Seek(long offset, SeekOrigin origin) => throw new NotSupportedException();
+
+    public override void SetLength(long value) => throw new NotSupportedException();
+
+    public override void Write(byte[] buffer, int offset, int count) => throw new NotSupportedException();
+
+    protected override void Dispose(bool disposing)
+    {
+#if !NETCOREAPP
+        if (_buffer is { } buffer)
+        {
+            _buffer = null!;
+            ArrayPool<byte>.Shared.Return(buffer);
+        }
+#endif
+
+        base.Dispose(disposing);
+    }
+
+    [DoesNotReturn]
+    private static void ThrowFormatException() => throw new FormatException("The input is not a valid base64 string.");
+
+    [DoesNotReturn]
+    private static void ThrowDestinationTooSmall() => throw new ArgumentException("Destination buffer must be at least 3 bytes to hold a decoded base64 quantum.");
+
+#if !NETCOREAPP
+    private void DecodeNextChunk()
+    {
+        var remainingChars = _base64.Length - _charPosition;
+        var charsToProcess = Math.Min(remainingChars, CharsPerChunk);
+
+        // Round down to a multiple of 4 for non-final chunks.
+        // Base64 decoding operates on 4-character quanta; the final chunk
+        // may include padding characters and is always a valid quantum boundary.
+        if (charsToProcess < remainingChars)
+        {
+            charsToProcess &= ~3;
+        }
+
+        if (charsToProcess == 0)
+        {
+            // Remaining chars < 4 and this is not the final chunk — shouldn't happen
+            // for valid base64, but guard against infinite loops.
+            _charPosition = _base64.Length;
+            return;
+        }
+
+        // All valid base64 characters are in the ASCII range (0–127),
+        // so we can safely narrow each char to a byte for the UTF-8 decoder.
+        // OR-accumulate all chars to detect non-ASCII input without branching per character.
+        var buf = _buffer;
+        var str = _base64;
+        var offset = _charPosition;
+        var nonAscii = 0;
+
+        for (var i = 0; i < charsToProcess; i++)
+        {
+            var c = str[offset + i];
+            nonAscii |= c;
+            buf[i] = (byte)c;
+        }
+
+        if (nonAscii > 127)
+        {
+            ThrowFormatException();
+        }
+
+        // Decode the UTF-8 base64 bytes in-place. The decoded output is always
+        // shorter than the input (3 bytes per 4 input bytes), so in-place is safe.
+        var status = Base64.DecodeFromUtf8InPlace(buf.AsSpan(0, charsToProcess), out var bytesWritten);
+        if (status != OperationStatus.Done)
+        {
+            ThrowFormatException();
+        }
+
+        _bufferOffset = 0;
+        _bufferCount = bytesWritten;
+        _charPosition += charsToProcess;
+    }
+#endif
+}