Public NotInheritable Class UtilKvdb
 
    ''' <summary>
    ''' Asynchronously retrieves a list of keys (and optionally their values) from the specified bucket storage 
    ''' on the remote <c>kvdb.io</c> service.
    ''' </summary>
    ''' 
    ''' <param name="bucketId">
    ''' The unique identifier pointing to the bucket storage. The bucket storage must exist on the server.
    ''' <para></para>
    ''' <i>Typically, the bucket identifier is an alphanumeric string with 22 character length, 
    ''' such as: <c>"JjSDG9KgFrBMbKgjRwmnAd"</c></i>
    ''' </param>
    ''' 
    ''' <param name="secretKey">
    ''' Optional. The secret key required to authorize the request if the bucket is protected.
    ''' <para></para>
    ''' Default value is null.
    ''' </param>
    ''' 
    ''' <param name="prefix">
    ''' Optional. Only return keys matching the given prefix.
    ''' <para></para>
    ''' Default value is null.
    ''' </param>
    ''' 
    ''' <param name="includeValues">
    ''' Optional. If set to <see langword="True"/>, returns values in addition to keys.
    ''' <para></para>
    ''' Default value is <see langword="False"/>.
    ''' </param>
    ''' 
    ''' <param name="limit">
    ''' Optional. Maximum number of keys to return.
    ''' <para></para>
    ''' Default value is 10000.
    ''' </param>
    ''' 
    ''' <param name="skip">
    ''' Optional. Number of keys to skip before returning the first result.
    ''' <para></para>
    ''' Default value is zero (no keys are skipped).
    ''' </param>
    ''' 
    ''' <param name="reverse">
    ''' Optional. If set to <see langword="True"/>, reverses the lexicographic sort order.
    ''' <para></para>
    ''' Default value is <see langword="False"/>.
    ''' </param>
    ''' 
    ''' <param name="outputFormat">
    ''' Optional. The preferred output format.
    ''' <para></para>
    ''' Default value is <see cref="KvdbOutputFormat.Text"/>.
    ''' </param>
    ''' 
    ''' <returns>
    ''' A <see cref="Task(Of String)"/> representing the asynchronous operation, containing the raw server response.
    ''' </returns>
    <DebuggerStepThrough>
    Public Shared Async Function ListBucketKeysAsync(bucketId As String,
                                            Optional secretKey As String = Nothing,
                                            Optional prefix As String = Nothing,
                                            Optional includeValues As Boolean = False,
                                            Optional limit As Integer = 10000,
                                            Optional skip As Integer = 0,
                                            Optional reverse As Boolean = False,
                                            Optional outputFormat As KvdbOutputFormat = KvdbOutputFormat.Text) As Task(Of String)
 
#If NETCOREAPP Then
        ArgumentNullException.ThrowIfNullOrWhiteSpace(bucketId, paramName:=NameOf(bucketId))
#Else
        If String.IsNullOrWhiteSpace(bucketId) Then : Throw New ArgumentNullException(paramName:=NameOf(bucketId)) : End If
#End If
        If limit <= 0 Then
            Throw New ArgumentOutOfRangeException(paramName:=NameOf(limit),
                "The maximum number of keys to return must be greather than zero.")
        End If
 
        If skip < 0 Then
            Throw New ArgumentOutOfRangeException(paramName:=NameOf(skip),
                "The number of keys to skip cannot be smaller than zero.")
        End If
 
        If outputFormat <> KvdbOutputFormat.Text AndAlso
           outputFormat <> KvdbOutputFormat.Json AndAlso
           outputFormat <> KvdbOutputFormat.Jsonl Then
 
            Throw New InvalidEnumArgumentException(NameOf(outputFormat), outputFormat, GetType(KvdbOutputFormat))
        End If
 
        Dim queryParams As New List(Of String)(capacity:=6) From {
            $"format={outputFormat.ToString().ToLowerInvariant()}",
            $"limit={limit}",
            $"skip={skip}",
            $"values={includeValues.ToString().ToLowerInvariant()}",
            $"reverse={reverse.ToString().ToLowerInvariant()}"
        }
 
        If Not String.IsNullOrWhiteSpace(prefix) Then
            queryParams.Add($"prefix={Uri.EscapeDataString(prefix)}")
        End If
 
        Dim queryString As String = String.Join("&", queryParams)
        Dim relativeUrl As String = $"{bucketId}/?{queryString}"
 
        Dim policy As New KvdbBucketPolicy With {
            .SecretKey = secretKey
        }
 
        Using client As HttpClient = UtilKvdb.BuildHttpClient(policy),
              response As HttpResponseMessage = Await client.GetAsync(relativeUrl).
                                                             ConfigureAwait(continueOnCapturedContext:=False)
            If response.IsSuccessStatusCode Then
                Dim rawResult As String = Await response.Content.ReadAsStringAsync().
                                                                 ConfigureAwait(continueOnCapturedContext:=False)
                Return rawResult
            Else
                Throw New HttpRequestException(
                    $"Failed to list bucket keys from the server. Status Code: {CInt(response.StatusCode)} ({response.StatusCode})")
            End If
        End Using
    End Function
 
End Class

''' <summary>
''' Specifies the data serialization formats supported by the <c>kvdb.io</c> API for listing keys and values.
''' </summary>
Public Enum KvdbOutputFormat
 
    ' DO NOT CHANGE VALUE NAMES (Text, Json, JSonl).
    ' They are converted to string for writing the list query.
 
    ''' <summary>
    ''' Plain text representation. 
    ''' <para></para>
    ''' Returns newline-delimited (<c>\n</c>) keys, 
    ''' or <c>key=value</c> pairs if values are requested.
    ''' </summary>
    Text
 
    ''' <summary>
    ''' Standard JSON format. 
    ''' <para></para>
    ''' Returns a valid JSON array of strings <c>["key"]</c>, 
    ''' or an array of arrays <c>[["key", value]]</c> if values are requested.
    ''' </summary>
    Json
 
    ''' <summary>
    ''' JSON Lines. 
    ''' <para></para>
    ''' Returns newline-delimited JSON, a format easy to process with 
    ''' command-line and other tools expecting one JSON object per line.
    ''' </summary>
    Jsonl
 
End Enum
 

''' <summary>
''' Represents the access policy for a bucket storage on the <c>kvdb.io</c> service.
''' </summary>
Public Class KvdbBucketPolicy : Implements IEquatable(Of KvdbBucketPolicy)
 
#Region " Properties "
 
    ''' <summary>
    ''' Gets or sets the key used to manage policy and other keys in a bucket storage.
    ''' </summary>
    ''' 
    ''' <exception cref="ArgumentException">
    ''' </exception>
    <Browsable(True)>
    <DisplayName("Secret Key")>
    <Description("The key used to manage policy and other keys in a bucket storage.")>
    <Category("Master Key")>
    Public Overridable Property SecretKey As String
        Get
            Return Me.secretKey_
        End Get
        Set(value As String)
            UtilKvdb.ValidateTokenSize(value, NameOf(KvdbBucketPolicy.SecretKey))
            Me.secretKey_ = value
        End Set
    End Property
    ''' <summary>
    ''' Backing field for <see cref="KvdbBucketPolicy.SecretKey"/>.
    ''' <para></para>
    ''' The key used to manage policy and other keys in a bucket storage.
    ''' </summary>
    Protected secretKey_ As String
 
    ''' <summary>
    ''' Gets or sets the key used to authorize read access to keys in a bucket storage.
    ''' </summary>
    ''' 
    ''' <exception cref="ArgumentException">
    ''' </exception>
    <Browsable(True)>
    <DisplayName("Read-Access Key")>
    <Description("The key used to authorize read access to keys in a bucket storage.")>
    <Category("Access Keys")>
    Public Overridable Property ReadKey As String
        Get
            Return Me.readKey_
        End Get
        Set(value As String)
            UtilKvdb.ValidateTokenSize(value, NameOf(KvdbBucketPolicy.ReadKey))
            Me.readKey_ = value
        End Set
    End Property
    ''' <summary>
    ''' Backing field for <see cref="KvdbBucketPolicy.ReadKey"/>.
    ''' <para></para>
    ''' The key used to authorize read access to keys in a bucket storage.
    ''' </summary>
    Protected readKey_ As String
 
    ''' <summary>
    ''' Gets or sets the key used to authorize write access to keys in a bucket storage.
    ''' </summary>
    ''' 
    ''' <exception cref="ArgumentException">
    ''' </exception>
    <Browsable(True)>
    <DisplayName("Write-Access Key")>
    <Description("The key used to authorize write access to keys in a bucket storage.")>
    <Category("Access Keys")>
    Public Overridable Property WriteKey As String
        Get
            Return Me.writeKey_
        End Get
        Set(value As String)
            UtilKvdb.ValidateTokenSize(value, NameOf(KvdbBucketPolicy.WriteKey))
            Me.writeKey_ = value
        End Set
    End Property
    ''' <summary>
    ''' Backing field for <see cref="KvdbBucketPolicy.WriteKey"/>.
    ''' <para></para>
    ''' The key used to authorize write access to keys in a bucket storage.
    ''' </summary>
    Protected writeKey_ As String
 
    ''' <summary>
    ''' Gets or sets the key used to generate cryptographically signed access tokens. 
    ''' <para></para>
    ''' <i>Changing the signing_key in a HTTP request will immediately invalidate all previously issued access tokens.</i>
    ''' </summary>
    ''' 
    ''' <exception cref="ArgumentException">
    ''' </exception>
    <Browsable(True)>
    <DisplayName("Token Signing Key")>
    <Description("The key used to generate cryptographically signed access tokens.")>
    <Category("Token Signing")>
    Public Overridable Property SigningKey As String
        Get
            Return Me.signingKey_
        End Get
        Set(value As String)
            UtilKvdb.ValidateTokenSize(value, NameOf(KvdbBucketPolicy.SigningKey))
            Me.signingKey_ = value
        End Set
    End Property
    ''' <summary>
    ''' Backing field for <see cref="KvdbBucketPolicy.SigningKey"/>.
    ''' <para></para>
    ''' The key used to generate cryptographically signed access tokens. 
    ''' <para></para>
    ''' <i>Changing the signing_key in a request will immediately invalidate all previously issued access tokens.</i>
    ''' </summary>
    Protected signingKey_ As String
 
    ''' <summary>
    ''' Gets or sets the time duration after which the keys created in a bucket storage will expire and be automatically deleted.
    ''' <para></para>
    ''' Note than on free accounts, if you set this property to <see cref="TimeSpan.Zero"/>, 
    ''' the server will override it to 2,592,000 seconds (30 days).
    ''' </summary>
    ''' 
    ''' <exception cref="ArgumentException">
    ''' </exception>
    <Browsable(True)>
    <DisplayName("Key-Value Expiration")>
    <Description("The time duration after which the keys created in a bucket storage will expire and be automatically deleted.")>
    <Category("Expiration")>
    Public Overridable Property KeyExpiration As TimeSpan
        Get
            Return Me.keyExpiration_
        End Get
        Set(value As TimeSpan)
            If value <> TimeSpan.Zero AndAlso value.TotalSeconds <= 0 Then
                Throw New ArgumentException(
                        $"{NameOf(KvdbBucketPolicy.KeyExpiration)} must be greather than zero", NameOf(value))
            End If
            Me.keyExpiration_ = value
        End Set
    End Property
    ''' <summary>
    ''' Backing field for <see cref="KvdbBucketPolicy.KeyExpiration"/>.
    ''' <para></para>
    ''' The time duration after which the keys created in a bucket storage will expire and be automatically deleted.
    ''' </summary>
    Protected keyExpiration_ As TimeSpan
 
#End Region
 
#Region " Constructors "
 
    ''' <summary>
    ''' Prevents a default instance of the <see cref="KvdbBucketPolicy"/> class from being created.
    ''' </summary>
    Private Sub New()
    End Sub
 
    ''' <summary>
    ''' Initializes a new instance of the <see cref="KvdbBucketPolicy"/> class.
    ''' </summary>
    ''' 
    ''' <param name="secretKey">
    ''' Optional. The key used to manage policy and other keys in a bucket storage.
    ''' <para></para>
    ''' Default value is null.
    ''' </param>
    ''' 
    ''' <param name="readKey">
    ''' Optional. The key used to authorize read access to keys in a bucket storage.
    ''' <para></para>
    ''' Default value is null.
    ''' </param>
    ''' 
    ''' <param name="writeKey">
    ''' Optional. The key used to authorize write access to keys in a bucket storage.
    ''' <para></para>
    ''' Default value is null.
    ''' </param>
    ''' 
    ''' <param name="signingKey">
    ''' Optional. The key used to generate cryptographically signed access tokens. 
    ''' <para></para>
    ''' <i>Changing the signing_key in a HTTP request will immediately invalidate all previously issued access tokens.</i>
    ''' <para></para>
    ''' Default value is null.
    ''' </param>
    ''' 
    ''' <param name="keyExpiration">
    ''' Optional. The time duration after which the keys created in a bucket storage will expire and be automatically deleted.
    ''' <para></para>
    ''' Default value is <see cref="TimeSpan.Zero"/>, which indicates that the keys will never expire.
    ''' <para></para>
    ''' Note than on free accounts, if you set this value to <see cref="TimeSpan.Zero"/>, 
    ''' the server will override it to 2,592,000 seconds (30 days).
    ''' </param>
    Public Sub New(Optional secretKey As String = Nothing,
                   Optional readKey As String = Nothing,
                   Optional writeKey As String = Nothing,
                   Optional signingKey As String = Nothing,
                   Optional keyExpiration As TimeSpan = Nothing)
 
        Me.SecretKey = secretKey
        Me.ReadKey = readKey
        Me.WriteKey = writeKey
        Me.SigningKey = signingKey
        Me.KeyExpiration = keyExpiration
    End Sub
 
#End Region
 
#Region " Public Methods "
 
    ''' <summary>
    ''' Returns a string that represents the current object.
    ''' </summary>
    ''' 
    ''' <returns>
    ''' A <see cref="String" /> that represents this instance.
    ''' </returns>
    <EditorBrowsable(EditorBrowsableState.Advanced)>
    Public Overrides Function ToString() As String
 
        Return MyBase.ToString()
    End Function
 
    ''' <summary>
    ''' Returns a string that represents the current policy configuration, formatted as a URL query string
    ''' </summary>
    ''' 
    ''' <param name="escaped">
    ''' A value indicating whether the resulting string should be URL-encoded.
    ''' <para></para>
    ''' If set to <see langword="True"/>, all value components will be encoded using 
    ''' <see cref="Uri.EscapeDataString"/> to ensure the resulting string is safe for use in URLs.
    ''' <para></para>
    ''' If set to <see langword="False"/>, raw values will be returned without any URL encoding,
    ''' for internal use or debugging scenarios where encoding is not required.
    ''' </param>
    ''' 
    ''' <returns>
    ''' A <see cref="String" /> that represents this instance.
    ''' </returns>
    <EditorBrowsable(EditorBrowsableState.Always)>
    Public Overridable Overloads Function ToString(escaped As Boolean) As String
 
        ' We call property getters rather than comparing fields to support any overriden properties.
 
        Dim secretKeyValue As String = If(Me.SecretKey, String.Empty)
        Dim readKeyValue As String = If(Me.ReadKey, String.Empty)
        Dim writeKeyValue As String = If(Me.WriteKey, String.Empty)
        Dim signingKeyValue As String = If(Me.SigningKey, String.Empty)
        Dim ttlValue As String = CInt(Me.KeyExpiration.TotalSeconds).ToString()
 
        Dim parts As New List(Of String)(capacity:=5) From {
            $"secret_key={If(escaped, Uri.EscapeDataString(secretKeyValue), secretKeyValue)}",
            $"read_key={If(escaped, Uri.EscapeDataString(readKeyValue), readKeyValue)}",
            $"write_key={If(escaped, Uri.EscapeDataString(writeKeyValue), writeKeyValue)}",
            $"signing_key={If(escaped, Uri.EscapeDataString(signingKeyValue), signingKeyValue)}",
            $"default_ttl={ttlValue}"
        }
 
        Return String.Join("&", parts)
    End Function
 
#End Region
 
#Region " IEquatable implementation and equality operators "
 
    ''' <summary>
    ''' Determines whether the current <see cref="KvdbBucketPolicy"/> is equal to another <see cref="KvdbBucketPolicy"/>.
    ''' </summary>
    ''' 
    ''' <param name="other">
    ''' A <see cref="KvdbBucketPolicy"/> to compare with this <see cref="KvdbBucketPolicy"/>.
    ''' </param>
    ''' 
    ''' <returns>
    ''' <see langword="True" /> if the current <see cref="KvdbBucketPolicy"/> is equal to the <paramref name="other" /> parameter; 
    ''' Otherwise, <see langword="False" />.
    ''' </returns>
    Public Overridable Overloads Function Equals(other As KvdbBucketPolicy) As Boolean _
    Implements IEquatable(Of KvdbBucketPolicy).Equals
 
        ' We call property getters rather than comparing fields to support any overriden properties.
 
        Return (other IsNot Nothing) AndAlso (
                  System.Object.ReferenceEquals(Me, other) OrElse
                  (
                    String.Equals(Me.SecretKey, other.SecretKey, StringComparison.Ordinal) AndAlso
                    String.Equals(Me.ReadKey, other.ReadKey, StringComparison.Ordinal) AndAlso
                    String.Equals(Me.WriteKey, other.WriteKey, StringComparison.Ordinal) AndAlso
                    String.Equals(Me.SigningKey, other.SigningKey, StringComparison.Ordinal) AndAlso
                    Me.KeyExpiration = other.KeyExpiration
                  )
               )
 
        ' Alternatively, we could compare the string representations of both instances using 
        ' the KvdbBucketPolicy.ToString() method instead of comparing each field individually, 
        ' which is simpler but it will be less efficient in memory and performance, 
        ' especially in scenarios involving indexed collections or frequent equality checks.
    End Function
 
    ''' <summary>
    ''' Determines whether the specified <see cref="Object" />, is equal to this instance.
    ''' </summary>
    ''' 
    ''' <param name="obj">
    ''' The <see cref="Object" /> to compare with this instance.
    ''' </param>
    ''' 
    ''' <returns>
    ''' <see langword="True"/> if the specified <see cref="Object" /> is equal to this instance; 
    ''' Otherwise, <see langword="False"/>.
    ''' </returns>
    Public Overrides Function Equals(obj As Object) As Boolean
 
        Dim other As KvdbBucketPolicy = TryCast(obj, KvdbBucketPolicy)
 
        Return Me.Equals(other)
    End Function
 
    ''' <summary>
    ''' Returns the hash code for the current <see cref="KvdbBucketPolicy"/>.
    ''' </summary>
    ''' 
    ''' <returns>
    ''' The hash code for the current <see cref="KvdbBucketPolicy"/>,
    ''' suitable for use in hashing algorithms and data structures like a hash table. 
    ''' </returns>
    Public Overrides Function GetHashCode() As Integer
 
        ' We call property getters rather than comparing fields to support any overriden properties.
 
#If NETCOREAPP Then
        Dim hash As New HashCode()
 
        hash.Add(Me.SecretKey)
        hash.Add(Me.ReadKey)
        hash.Add(Me.WriteKey)
        hash.Add(Me.SigningKey)
        hash.Add(Me.KeyExpiration)
 
        Return hash.ToHashCode()
#Else
        ' We avoid the complexity of manually combining hash codes and potential issues with overflow 
        ' by leveraging the built-in functionality of Tuple to generate a combined hash code from all relevant fields.
        Return Tuple.Create(
            Me.SecretKey,
            Me.ReadKey,
            Me.WriteKey,
            Me.SigningKey,
            Me.KeyExpiration
        ).GetHashCode()
#End If
 
    End Function
 
    ''' <summary>
    ''' Compares two <see cref="KvdbBucketPolicy"/> instances for equality.
    ''' </summary>
    ''' 
    ''' <param name="first">
    ''' The first <see cref="KvdbBucketPolicy"/> object to compare.
    ''' </param>
    ''' 
    ''' <param name="second">
    ''' The second <see cref="KvdbBucketPolicy"/> object to compare.
    ''' </param>
    ''' 
    ''' <returns>
    ''' Returns <see langword="True"/> if the instances are equal; otherwise, <see langword="False"/>.
    ''' </returns>
    Public Shared Operator =(first As KvdbBucketPolicy, second As KvdbBucketPolicy) As Boolean
 
        Return first IsNot Nothing AndAlso
               second IsNot Nothing AndAlso
               first.Equals(second)
    End Operator
 
    ''' <summary>
    ''' Compares two <see cref="KvdbBucketPolicy"/> instances for inequality.
    ''' </summary>
    ''' 
    ''' <param name="first">
    ''' The first <see cref="KvdbBucketPolicy"/> object to compare.
    ''' </param>
    ''' 
    ''' <param name="second">
    ''' The second <see cref="KvdbBucketPolicy"/> object to compare.
    ''' </param>
    ''' 
    ''' <returns>
    ''' Returns <see langword="True"/> if the instances are not equal; otherwise, <see langword="False"/>.
    ''' </returns>
    Public Shared Operator <>(first As KvdbBucketPolicy, second As KvdbBucketPolicy) As Boolean
 
        Return Not (first = second)
    End Operator
 
#End Region
 
End Class
 

Imports System.Net
Imports System.Net.Http
Imports System.Net.Http.Headers
Imports System.Security.Authentication
Imports System.Text.Json
 
''' <summary>
''' Provides utility methods for interacting with the <c>kvdb.io</c> key-value storage service. 
''' </summary>
Public NotInheritable Class UtilKvdb
 
#Region " Constructors "
 
    ''' <summary>
    ''' Prevents a default instance of the <see cref="UtilKvdb"/> class from being created.
    ''' </summary>
    Private Sub New()
    End Sub
 
#End Region
 
#Region " Public Methods "
 
    ''' <summary>
    ''' Asynchronously creates and retrieves a newly server-generated bucket storage 
    ''' with random ID on the remote <c>kvdb.io</c> service.
    ''' </summary>
    ''' 
    ''' <example> This is a code example.
    ''' <code language="VB">
    ''' Dim mailAddress As String = "your_address@gmail.com"
    ''' 
    ''' Dim policy As New KvdbBucketPolicy With {
    '''     .SecretKey = Nothing,
    '''     .ReadKey = Nothing,
    '''     .WriteKey = Nothing,
    '''     .SigningKey = Nothing,
    '''     .KeyExpiration = TimeSpan.FromHours(1)
    ''' }
    ''' 
    ''' Dim newlyBucketId As String = Await GenerateBucketAsync(mailAddress, policy)
    ''' 
    ''' Console.WriteLine($"Server-generated bucket with random ID : {newlyBucketId}")
    ''' Console.WriteLine($"Access URL to keys collection in bucket: https://kvdb.io/{newlyBucketId}")
    ''' </code>
    ''' </example>
    ''' 
    ''' <param name="associatedEmailAddress">
    ''' The associated email address required by <c>kvdb.io</c> to generate a new bucket.
    ''' <para></para>
    ''' If the email address is not registered on the server, you will receive
    ''' a notification email from <c>kvdb.io</c> with a confirmation link 
    ''' to validate the email address and activate your (free)account.
    ''' </param>
    ''' 
    ''' <param name="policy">
    ''' Optional. The <see cref="KvdbBucketPolicy"/> object containing the access keys 
    ''' and key expiration time to be applied to the newly server-generated bucket.
    ''' <para></para>
    ''' If no policy is provided or does not contain access keys, 
    ''' the server-generated bucket will have no configured access keys.
    ''' </param>
    ''' 
    ''' <returns>
    ''' A <see cref="Task(Of String)"/> containing the unique identifier for the newly server-generated bucket.
    ''' <para></para>
    ''' <i>Typically, the bucket identifier is an alphanumeric string with 22 character length, 
    ''' such as: <c>"JjSDG9KgFrBMbKgjRwmnAd"</c></i>
    ''' </returns>
    ''' 
    ''' <exception cref="HttpRequestException">
    ''' </exception>
    <DebuggerStepThrough>
    Public Shared Async Function GenerateBucketAsync(associatedEmailAddress As String,
                                            Optional policy As KvdbBucketPolicy = Nothing) As Task(Of String)
 
#If NETCOREAPP Then
        ArgumentNullException.ThrowIfNullOrWhiteSpace(associatedEmailAddress, paramName:=NameOf(associatedEmailAddress))
#Else
        If String.IsNullOrWhiteSpace(associatedEmailAddress) Then : Throw New ArgumentNullException(paramName:=NameOf(associatedEmailAddress)) : End If
#End If
 
        Dim query As String = $"email={Uri.EscapeDataString(associatedEmailAddress)}"
        If policy IsNot Nothing Then
            query &= $"&{policy.ToString(escaped:=True)}"
        End If
 
        Using content As New StringContent(query, Encoding.UTF8, "application/x-www-form-urlencoded"),
              client As HttpClient = UtilKvdb.BuildHttpClient(policy:=Nothing),
              response As HttpResponseMessage = Await client.PostAsync(requestUri:=String.Empty, content).
                                                             ConfigureAwait(continueOnCapturedContext:=False)
            If response.IsSuccessStatusCode Then
                Dim rawId As String = Await response.Content.ReadAsStringAsync().
                                                             ConfigureAwait(continueOnCapturedContext:=False)
                Return rawId?.Trim()
            Else
                Throw New HttpRequestException(
                    $"Failed to create bucket on the server. Status Code: {CInt(response.StatusCode)} ({response.StatusCode})")
            End If
        End Using
    End Function
 
    ''' <summary>
    ''' Asynchronously updates the policy for an existing bucket storage 
    ''' on the remote <c>kvdb.io</c> service using the provided <see cref="KvdbBucketPolicy"/>.
    ''' </summary>
    ''' 
    ''' <remarks>
    ''' <b>Important Limitation:</b> 
    ''' Once a <c>secret key</c>, <c>read key</c>, <c>write key</c> or <c>signing key</c> has been established for a bucket,
    ''' <para></para> 
    ''' the <c>kvdb.io</c> API does not seem to support clearing any of these keys to null (public state).
    ''' </remarks>
    ''' 
    ''' <example> This is a code example.
    ''' <code language="VB">
    ''' Dim mailAddress As String = "your_address@gmail.com"
    ''' 
    ''' Dim defaultPolicy As New KvdbBucketPolicy()
    ''' 
    ''' Dim newlyBucketId As String = Await GenerateBucketAsync(mailAddress, defaultPolicy)
    ''' 
    ''' Console.WriteLine($"Server-generated bucket with random ID: {newlyBucketId}")
    ''' 
    ''' Dim newPolicy As New KvdbBucketPolicy With {
    '''     .SecretKey = "My Secret Key",
    '''     .ReadKey = "My Read Key",
    '''     .WriteKey = "My Write Key",
    '''     .SigningKey = Nothing,
    '''     .KeyExpiration = TimeSpan.FromHours(1)
    ''' }
    ''' 
    ''' Await UpdateBucketPolicyAsync(newlyBucketId, newPolicy)
    ''' 
    ''' Console.WriteLine($"Policty updated for bucket: https://kvdb.io/{newlyBucketId}")
    ''' </code>
    ''' </example>
    ''' 
    ''' <param name="policy">
    ''' The <see cref="KvdbBucketPolicy"/> object containing the access keys 
    ''' and key expiration time to be applied to the specified bucket.
    ''' </param>
    ''' 
    ''' <returns>
    ''' A <see cref="Task(Of String)"/> representing the asynchronous operation. 
    ''' <para></para>
    ''' If the task completes successfully, it indicates that 
    ''' the bucket policy was successfully updated on the server.
    ''' </returns>
    ''' 
    ''' <exception cref="HttpRequestException">
    ''' </exception>
    <DebuggerStepThrough>
    Public Shared Async Function UpdateBucketPolicyAsync(bucketId As String, policy As KvdbBucketPolicy) As Task
 
#If NETCOREAPP Then
    ArgumentNullException.ThrowIfNullOrWhiteSpace(bucketId, paramName:=NameOf(bucketId))
    ArgumentNullException.ThrowIfNull(policy, paramName:=NameOf(policy))
#Else
        If String.IsNullOrWhiteSpace(bucketId) Then : Throw New ArgumentNullException(paramName:=NameOf(bucketId)) : End If
        If policy Is Nothing Then : Throw New ArgumentNullException(paramName:=NameOf(policy)) : End If
#End If
 
        Dim policyQuery As String = policy.ToString(escaped:=True)
        Dim relativeUrl As String = $"{bucketId}?{policyQuery}"
 
        Using content As New StringContent(policyQuery, Encoding.UTF8, "application/x-www-form-urlencoded"),
              client As HttpClient = UtilKvdb.BuildHttpClient(policy),
              request As New HttpRequestMessage(New HttpMethod("PATCH"), relativeUrl) With {.Content = content},
              response As HttpResponseMessage = Await client.SendAsync(request).
                                                             ConfigureAwait(continueOnCapturedContext:=False)
            If response.IsSuccessStatusCode Then
                Return
            Else
                Throw New HttpRequestException(
                    $"Failed to update bucket policy on the server. Status Code: {CInt(response.StatusCode)} ({response.StatusCode})")
            End If
        End Using
    End Function
 
    ''' <summary>
    ''' Asynchronously deletes an existing bucket storage and its associated collection of keys 
    ''' from the remote <c>kvdb.io</c> service.
    ''' </summary>
    ''' 
    ''' <example> This is a code example.
    ''' <code language="VB">
    ''' Dim bucketId As String = "JjSDG9KgFrBMbKgjRwmnAd"
    ''' 
    ''' Await DeleteBucketAsync(bucketId)
    ''' </code>
    ''' </example>
    ''' 
    ''' <param name="bucketId">
    ''' The unique identifier pointing to the bucket storage to delete. The bucket storage must exist on the server.
    ''' <para></para>
    ''' <i>Typically, the bucket identifier is an alphanumeric string with 22 character length, 
    ''' such as: <c>"JjSDG9KgFrBMbKgjRwmnAd"</c></i>
    ''' </param>
    ''' 
    ''' <param name="policy">
    ''' Optional. The <see cref="KvdbBucketPolicy"/> object containing the access keys 
    ''' to authorize the deletion request for the specified bucket.
    ''' <para></para>
    ''' If no policy is provided or does not contain access keys, 
    ''' the deletion request will be sent without authentication.
    ''' </param>
    ''' 
    ''' <returns>
    ''' A <see cref="Task"/> representing the asynchronous operation.
    ''' <para></para>
    ''' If the task completes successfully, it indicates that the server accepted the deletion request 
    ''' (<see cref="HttpStatusCode.Accepted"/>) to remove the bucket storage.
    ''' </returns>
    ''' 
    ''' <exception cref="HttpRequestException">
    ''' </exception>
    <DebuggerStepThrough>
    Public Shared Async Function DeleteBucketAsync(bucketId As String,
                                          Optional policy As KvdbBucketPolicy = Nothing) As Task
 
#If NETCOREAPP Then
        ArgumentNullException.ThrowIfNullOrWhiteSpace(bucketId, paramName:=NameOf(bucketId))
#Else
        If String.IsNullOrWhiteSpace(bucketId) Then : Throw New ArgumentNullException(paramName:=NameOf(bucketId)) : End If
#End If
 
        Using client As HttpClient = UtilKvdb.BuildHttpClient(policy),
              response As HttpResponseMessage = Await client.DeleteAsync(bucketId).
                                                             ConfigureAwait(continueOnCapturedContext:=False)
            If response.IsSuccessStatusCode Then
                Return
            Else
                Throw New HttpRequestException(
                    $"Failed to delete bucket from the server. Status Code: {CInt(response.StatusCode)} ({response.StatusCode})")
            End If
        End Using
    End Function
 
    ''' <summary>
    ''' Asynchronously creates or overwrites a key-value slot inside the specified bucket storage 
    ''' from the remote <c>kvdb.io</c> service using the provided <see cref="StringContent"/>.
    ''' </summary>
    ''' 
    ''' <example> This is a code example.
    ''' <code language="VB">
    ''' Dim bucketId As String = "JjSDG9KgFrBMbKgjRwmnAd"
    ''' Dim key As String = "Name of the key to create"
    ''' Dim value As String = "Value of the key"
    ''' 
    ''' Dim payloadData As New Dictionary(Of String, Object)(StringComparer.Ordinal) From {
    '''     {"Key", key},
    '''     {"Value", value}
    ''' }
    ''' 
    ''' Dim jsonString As String = JsonSerializer.Serialize(payloadData)
    ''' 
    ''' Using content As New StringContent(jsonString, Encoding.UTF8, "application/json")
    ''' 
    '''     Await CreateKeyAsync(bucketId, key, content)
    ''' End Using
    ''' </code>
    ''' </example>
    ''' 
    ''' <param name="bucketId">
    ''' The unique identifier pointing to the bucket storage. The bucket storage must exist on the server.
    ''' <para></para>
    ''' <i>Typically, the bucket identifier is an alphanumeric string with 22 character length, 
    ''' such as: <c>"JjSDG9KgFrBMbKgjRwmnAd"</c></i>
    ''' </param>
    ''' 
    ''' <param name="key">
    ''' The name of the key to create or overwrite.
    ''' </param>
    ''' 
    ''' <param name="content">
    ''' The <see cref="StringContent"/> object containing the data to be stored in the key.
    ''' <para></para>
    ''' For example, to store JSON data, the <see cref="StringContent"/> can be initialized as follows:
    ''' <code>
    '''     Dim jsonString As String = JsonSerializer.Serialize(myObject)
    '''     Dim content As New StringContent(jsonString, Encoding.UTF8, "application/json")
    ''' </code>
    ''' </param>
    ''' 
    ''' <param name="policy">
    ''' Optional. The <see cref="KvdbBucketPolicy"/> object containing the access keys 
    ''' to authorize the creation or overwriting request for the specified key, 
    ''' and the expiration time to be applied to the key.
    ''' <para></para>
    ''' If no policy is provided or does not contain access keys, 
    ''' the creation request will be sent without authentication.
    ''' </param>
    ''' 
    ''' <returns>
    ''' A <see cref="Task"/> representing the asynchronous operation. 
    ''' <para></para>
    ''' If the task completes successfully, it indicates that 
    ''' the key was successfully created or overwritten on the server.
    ''' </returns>
    ''' 
    ''' <exception cref="HttpRequestException">
    ''' </exception>
    <DebuggerStepThrough>
    Public Shared Async Function CreateKeyAsync(bucketId As String, key As String, content As StringContent,
                                       Optional policy As KvdbBucketPolicy = Nothing) As Task
 
#If NETCOREAPP Then
        ArgumentNullException.ThrowIfNullOrWhiteSpace(bucketId, paramName:=NameOf(bucketId))
        ArgumentNullException.ThrowIfNullOrWhiteSpace(key, paramName:=NameOf(key))
        ArgumentNullException.ThrowIfNull(content, paramName:=NameOf(content))
#Else
        If String.IsNullOrWhiteSpace(bucketId) Then : Throw New ArgumentNullException(paramName:=NameOf(bucketId)) : End If
        If String.IsNullOrWhiteSpace(key) Then : Throw New ArgumentNullException(paramName:=NameOf(key)) : End If
        If content Is Nothing Then : Throw New ArgumentNullException(paramName:=NameOf(content)) : End If
#End If
        UtilKvdb.ValidateTokenSize(key, NameOf(key))
 
        Dim relativeUrl As String = UtilKvdb.BuildRelativeKeyUrl(bucketId, key, isWriteOperation:=True, policy)
 
        Using client As HttpClient = UtilKvdb.BuildHttpClient(policy),
              response As HttpResponseMessage = Await client.PostAsync(relativeUrl, content).
                                                             ConfigureAwait(continueOnCapturedContext:=False)
            If response.IsSuccessStatusCode Then
                Return
            Else
                Throw New HttpRequestException(
                    $"Failed to create or overwrite key on the server. Status Code: {CInt(response.StatusCode)} ({response.StatusCode})")
            End If
        End Using
    End Function
 
    ''' <summary>
    ''' Asynchronously creates or overwrites a key-value slot inside the specified bucket storage 
    ''' from the remote <c>kvdb.io</c> service using the provided <see cref="String"/> value.
    ''' </summary>
    ''' 
    ''' <example> This is a code example.
    ''' <code language="VB">
    ''' Dim bucketId As String = "JjSDG9KgFrBMbKgjRwmnAd"
    ''' Dim key As String = "Name of the key to create"
    ''' Dim value As String = "Value of the key"
    ''' 
    ''' Await CreateKeyAsync(bucketId, key, value)
    ''' </code>
    ''' </example>
    ''' 
    ''' <param name="bucketId">
    ''' The unique identifier pointing to the bucket storage. The bucket storage must exist on the server.
    ''' <para></para>
    ''' <i>Typically, the bucket identifier is an alphanumeric string with 22 character length, 
    ''' such as: <c>"JjSDG9KgFrBMbKgjRwmnAd"</c></i>
    ''' </param>
    ''' 
    ''' <param name="key">
    ''' The name of the key to create or overwrite.
    ''' </param>
    ''' 
    ''' <param name="value">
    ''' The value to be stored in the key. 
    ''' <para></para>
    ''' This value will be sent to the server as UTF-8 encoded plain text with media type <c>"text/plain"</c>.
    ''' </param>
    ''' 
    ''' <param name="policy">
    ''' Optional. The <see cref="KvdbBucketPolicy"/> object containing the access keys 
    ''' to authorize the creation or overwriting request for the specified key, 
    ''' and the expiration time to be applied to the key.
    ''' <para></para>
    ''' If no policy is provided or does not contain access keys, 
    ''' the creation request will be sent without authentication.
    ''' </param>
    ''' 
    ''' <returns>
    ''' A <see cref="Task"/> representing the asynchronous operation. 
    ''' <para></para>
    ''' If the task completes successfully, it indicates that 
    ''' the key was successfully created or overwritten on the server.
    ''' </returns>
    ''' 
    ''' <exception cref="HttpRequestException">
    ''' </exception>
    <DebuggerStepThrough>
    Public Shared Async Function CreateKeyAsync(bucketId As String, key As String, value As String,
                                       Optional policy As KvdbBucketPolicy = Nothing) As Task
 
#If NETCOREAPP Then
        ArgumentNullException.ThrowIfNullOrEmpty(value, paramName:=NameOf(value))
#Else
        If String.IsNullOrEmpty(value) Then : Throw New ArgumentNullException(paramName:=NameOf(value)) : End If
#End If
 
        Using content As New StringContent(value, Encoding.UTF8, "text/plain")
 
            Await UtilKvdb.CreateKeyAsync(bucketId, key, content, policy).
                           ConfigureAwait(continueOnCapturedContext:=False)
        End Using
    End Function
 
    ''' <summary>
    ''' Asynchronously retrieves the value stored in a existing key-value slot from the specified bucket storage 
    ''' on the remote <c>kvdb.io</c> service as a raw plain text.
    ''' </summary>
    ''' 
    ''' <example> This is a code example.
    ''' <code language="VB">
    ''' Dim bucketId As String = "JjSDG9KgFrBMbKgjRwmnAd"
    ''' Dim key As String = "Name of the key to create"
    ''' 
    ''' Dim value As String = Await GetKeyValueAsync(bucketId, key)
    ''' 
    ''' Console.WriteLine($"Raw value retrieved from key: {value}")
    ''' </code>
    ''' </example>
    ''' 
    ''' <param name="bucketId">
    ''' The unique identifier pointing to the bucket storage. The bucket storage must exist on the server.
    ''' <para></para>
    ''' <i>Typically, the bucket identifier is an alphanumeric string with 22 character length, 
    ''' such as: <c>"JjSDG9KgFrBMbKgjRwmnAd"</c></i>
    ''' </param>
    ''' 
    ''' <param name="key">
    ''' The name of the key from which to retrieve its value.
    ''' </param>
    ''' 
    ''' <param name="policy">
    ''' Optional. The <see cref="KvdbBucketPolicy"/> object containing the access keys 
    ''' to authorize read-access for the specified key.
    ''' <para></para>
    ''' If no policy is provided or does not contain access keys, 
    ''' the read-access request will be sent without authentication.
    ''' </param>
    ''' 
    ''' <returns>
    ''' A <see cref="Task(Of String)"/> containing the value stored in the specified key as a raw plain text string.
    ''' </returns>
    ''' 
    ''' <exception cref="HttpRequestException">
    ''' </exception>
    <DebuggerStepThrough>
    Public Shared Async Function GetKeyValueAsync(bucketId As String, key As String,
                                         Optional policy As KvdbBucketPolicy = Nothing) As Task(Of String)
 
#If NETCOREAPP Then
        ArgumentNullException.ThrowIfNullOrWhiteSpace(bucketId, paramName:=NameOf(bucketId))
        ArgumentNullException.ThrowIfNullOrWhiteSpace(key, paramName:=NameOf(key))
#Else
        If String.IsNullOrWhiteSpace(bucketId) Then : Throw New ArgumentNullException(paramName:=NameOf(bucketId)) : End If
        If String.IsNullOrWhiteSpace(key) Then : Throw New ArgumentNullException(paramName:=NameOf(key)) : End If
#End If
 
        Dim relativeUrl As String = UtilKvdb.BuildRelativeKeyUrl(bucketId, key, isWriteOperation:=False, policy)
 
        Using client As HttpClient = UtilKvdb.BuildHttpClient(policy),
              response As HttpResponseMessage = Await client.GetAsync(relativeUrl).
                                                             ConfigureAwait(continueOnCapturedContext:=False)
            If response.StatusCode = HttpStatusCode.OK Then
                Dim extractedContent As String = Await response.Content.ReadAsStringAsync().
                                                                        ConfigureAwait(continueOnCapturedContext:=False)
                Return extractedContent
            Else
                Throw New HttpRequestException(
                    $"Failed to read key from the server. Status Code: {CInt(response.StatusCode)} ({response.StatusCode})")
            End If
        End Using
    End Function
 
    ''' <summary>
    ''' Asynchronously retrieves the value stored in a existing key-value slot from the specified bucket storage 
    ''' on the remote <c>kvdb.io</c> service as a <see cref="JsonDocument"/>.
    ''' </summary>
    ''' 
    ''' <example> This is a code example.
    ''' <code language="VB">
    ''' Dim bucketId As String = "JjSDG9KgFrBMbKgjRwmnAd"
    ''' Dim key As String = "Name of the key to create"
    ''' 
    ''' Dim value As JsonDocument = Await GetKeyValueJsonAsync(bucketId, key)
    ''' 
    ''' Console.WriteLine($"JSON value retrieved from key: {value.RootElement}")
    ''' </code>
    ''' </example>
    ''' 
    ''' <param name="bucketId">
    ''' The unique identifier pointing to the bucket storage. The bucket storage must exist on the server.
    ''' <para></para>
    ''' <i>Typically, the bucket identifier is an alphanumeric string with 22 character length, 
    ''' such as: <c>"JjSDG9KgFrBMbKgjRwmnAd"</c></i>
    ''' </param>
    ''' 
    ''' <param name="key">
    ''' The name of the key from which to retrieve its value.
    ''' </param>
    ''' 
    ''' <param name="policy">
    ''' Optional. The <see cref="KvdbBucketPolicy"/> object containing the access keys 
    ''' to authorize read-access for the specified key.
    ''' <para></para>
    ''' If no policy is provided or does not contain access keys, 
    ''' the read-access request will be sent without authentication.
    ''' </param>
    ''' 
    ''' <returns>
    ''' A <see cref="Task(Of JsonDocument)"/> containing the value stored in the specified key as a <see cref="JsonDocument"/>.
    ''' </returns>
    ''' 
    ''' <exception cref="HttpRequestException">
    ''' </exception>
    ''' 
    ''' <exception cref="JsonException">
    ''' </exception>
    <DebuggerStepThrough>
    Public Shared Async Function GetKeyValueJsonAsync(bucketId As String, key As String,
                                             Optional policy As KvdbBucketPolicy = Nothing) As Task(Of JsonDocument)
 
        Dim jsonString As String = Await UtilKvdb.GetKeyValueAsync(bucketId, key, policy).
                                                  ConfigureAwait(continueOnCapturedContext:=False)
 
        ' Throws a JsonException if the remote payload content is invalid JSON.
        Dim parsedDocument As JsonDocument = JsonDocument.Parse(jsonString)
 
        Return parsedDocument
    End Function
 
    ''' <summary>
    ''' Asynchronously deletes a existing key-value slot in the specified bucket storage 
    ''' from the remote <c>kvdb.io</c> service.
    ''' </summary>
    ''' 
    ''' <example> This is a code example.
    ''' <code language="VB">
    ''' Dim bucketId As String = "JjSDG9KgFrBMbKgjRwmnAd"
    ''' Dim key As String = "Name of the key to delete"
    ''' 
    ''' Await DeleteKeyAsync(bucketId, key)
    ''' </code>
    ''' </example>
    ''' 
    ''' <param name="bucketId">
    ''' The unique identifier pointing to the bucket storage. The bucket storage must exist on the server.
    ''' <para></para>
    ''' <i>Typically, the bucket identifier is an alphanumeric string with 22 character length, 
    ''' such as: <c>"JjSDG9KgFrBMbKgjRwmnAd"</c></i>
    ''' </param>
    ''' 
    ''' <param name="key">
    ''' The name of the key to delete.
    ''' </param>
    ''' 
    ''' <param name="policy">
    ''' Optional. The <see cref="KvdbBucketPolicy"/> object containing the access keys 
    ''' to authorize the deletion for the specified key.
    ''' <para></para>
    ''' If no policy is provided or does not contain access keys, 
    ''' the deletion request will be sent without authentication.
    ''' </param>
    ''' 
    ''' <returns>
    ''' A <see cref="Task"/> representing the asynchronous operation.
    ''' <para></para>
    ''' If the task completes successfully, it indicates that the server accepted the deletion request 
    ''' (<see cref="HttpStatusCode.Accepted"/>) to remove the key, regardless of whether the key exists or not.
    ''' </returns>
    ''' 
    ''' <exception cref="HttpRequestException">
    ''' </exception>
    <DebuggerStepThrough>
    Public Shared Async Function DeleteKeyAsync(bucketId As String, key As String,
                                       Optional policy As KvdbBucketPolicy = Nothing) As Task
 
#If NETCOREAPP Then
        ArgumentNullException.ThrowIfNullOrWhiteSpace(bucketId, paramName:=NameOf(bucketId))
        ArgumentNullException.ThrowIfNullOrWhiteSpace(key, paramName:=NameOf(key))
#Else
        If String.IsNullOrWhiteSpace(bucketId) Then : Throw New ArgumentNullException(paramName:=NameOf(bucketId)) : End If
        If String.IsNullOrWhiteSpace(key) Then : Throw New ArgumentNullException(paramName:=NameOf(key)) : End If
#End If
 
        Dim relativeUrl As String = UtilKvdb.BuildRelativeKeyUrl(bucketId, key, isWriteOperation:=True, policy)
 
        Using client As HttpClient = UtilKvdb.BuildHttpClient(policy),
              response As HttpResponseMessage = Await client.DeleteAsync(relativeUrl).
                                                             ConfigureAwait(continueOnCapturedContext:=False)
            If response.IsSuccessStatusCode Then
                Return
            Else
                Throw New HttpRequestException(
                    $"Failed to delete key from the server. Status Code: {CInt(response.StatusCode)} ({response.StatusCode})")
            End If
        End Using
    End Function
 
#End Region
 
#Region " Private Methods "
 
    ''' <summary>
    ''' Gets a new instance of <see cref="HttpClient"/> configured for use with the <c>kvdb.io</c> service, 
    ''' applying the appropriate authentication header if a <see cref="KvdbBucketPolicy.SecretKey"/> is provided.
    ''' </summary>
    ''' 
    ''' <param name="policy">
    ''' Optional. The <see cref="KvdbBucketPolicy"/> object containing the <c>SecretKey</c> to be applied for 
    ''' authentication in the HTTP requests sent by the returned <see cref="HttpClient"/> instance.
    ''' <para></para>
    ''' If no policy is provided or does not contain a <c>SecretKey</c>, 
    ''' the returned <see cref="HttpClient"/> will not have any authentication header applied.
    ''' </param>
    ''' 
    ''' <returns>
    ''' Returns the resulting <see cref="HttpClient"/> instance configured for use with the <c>kvdb.io</c> service, 
    ''' and with the appropriate authentication header if applicable.
    ''' </returns>
    <DebuggerStepThrough>
    Private Shared Function BuildHttpClient(Optional policy As KvdbBucketPolicy = Nothing) As HttpClient
 
        ' clientHandler is automatically disposed by HttpClient object on disposal.
        Dim clientHandler As New HttpClientHandler() With {
            .AllowAutoRedirect = False,
            .UseCookies = False,
            .UseProxy = False,
            .DefaultProxyCredentials = Nothing,
            .UseDefaultCredentials = False,
            .Credentials = Nothing,
            .PreAuthenticate = False,
            .CheckCertificateRevocationList = True,
            .ClientCertificateOptions = ClientCertificateOption.Automatic,
            .SslProtocols = SslProtocols.Tls12 Or SslProtocols.Tls13,
            .AutomaticDecompression = DecompressionMethods.GZip Or DecompressionMethods.Deflate
        }
 
        ' The BaseAddress for the <c>kvdb.io</c> service API,
        ' so that we can use relative URLs for the requests.
        Const kvdbBaseAddress As String = "https://kvdb.io"
 
        Dim client As New HttpClient(clientHandler, disposeHandler:=True) With {
            .BaseAddress = New Uri(kvdbBaseAddress),
            .Timeout = TimeSpan.FromSeconds(60)
        }
 
        If (policy IsNot Nothing) AndAlso Not String.IsNullOrEmpty(policy.SecretKey) Then
            client.DefaultRequestHeaders.Authorization = New AuthenticationHeaderValue("Bearer", policy.SecretKey)
        End If
 
        Return client
    End Function
 
    ''' <summary>
    ''' Builds the relative URL for accessing a specific key in a bucket storage on the remote <c>kvdb.io</c> service, 
    ''' including the appropriate query string parameters for authentication and key expiration based on 
    ''' the provided <see cref="KvdbBucketPolicy"/> and operation context (create / read / write / delete).
    ''' </summary>
    ''' 
    ''' <param name="bucketId">
    ''' The unique identifier pointing to the bucket storage. The bucket storage must exist on the server.
    ''' <para></para>
    ''' <i>Typically, the bucket identifier is an alphanumeric string with 22 character length, 
    ''' such as: <c>"JjSDG9KgFrBMbKgjRwmnAd"</c></i>
    ''' </param>
    ''' 
    ''' <param name="key">
    ''' The name of the key for which to build the access URL.
    ''' </param>
    ''' 
    ''' <param name="isWriteOperation">
    ''' A value indicating whether the URL is being built for a write or a read operation. 
    ''' <para></para>
    ''' This parameter is used to determine which access key to attach in the query string, 
    ''' and whether to include the TTL parameter for key expiration.
    ''' </param>
    ''' 
    ''' <param name="policy">
    ''' Optional. The <see cref="KvdbBucketPolicy"/> object containing 
    ''' the access keys to authorize the request for the specified key, 
    ''' and the expiration time to be applied to the key if applicable.
    ''' <para></para>
    ''' If no policy is provided or does not contain access keys, 
    ''' the URL will be built without authentication parameters.
    ''' </param>
    ''' 
    ''' <returns>
    ''' Returns the resulting complete URL for accessing the specified key in the bucket storage.
    ''' </returns>
    <DebuggerStepThrough>
    Private Shared Function BuildRelativeKeyUrl(bucketId As String, key As String,
                                                isWriteOperation As Boolean,
                                       Optional policy As KvdbBucketPolicy = Nothing) As String
 
#If NETCOREAPP Then
        ArgumentNullException.ThrowIfNullOrWhiteSpace(bucketId, paramName:=NameOf(bucketId))
        ArgumentNullException.ThrowIfNullOrWhiteSpace(key, paramName:=NameOf(key))
#Else
        If String.IsNullOrWhiteSpace(bucketId) Then : Throw New ArgumentNullException(paramName:=NameOf(bucketId)) : End If
        If String.IsNullOrWhiteSpace(key) Then : Throw New ArgumentNullException(paramName:=NameOf(key)) : End If
#End If
 
        Dim escapedKey As String = Uri.EscapeDataString(key)
        Dim relativePath As String = $"{bucketId}/{escapedKey}"
        Dim queryParameters As New List(Of String)(capacity:=2)
 
        If policy IsNot Nothing Then
            ' Determine whether to attach the WriteKey or ReadKey based on the execution context.
 
            If isWriteOperation Then
                If Not String.IsNullOrEmpty(policy.WriteKey) Then
                    Dim escapedWriteKey As String = Uri.EscapeDataString(policy.WriteKey)
                    queryParameters.Add($"write_key={escapedWriteKey}")
                End If
 
                ' The TTL parameter is only applicable during write operations.
                If policy.KeyExpiration <> TimeSpan.Zero Then
                    Dim ttlValue As String = CInt(policy.KeyExpiration.TotalSeconds).ToString()
                    queryParameters.Add($"ttl={ttlValue}")
                End If
            Else
                If Not String.IsNullOrEmpty(policy.ReadKey) Then
                    Dim escapedReadKey As String = Uri.EscapeDataString(policy.ReadKey)
                    queryParameters.Add($"read_key={escapedReadKey}")
                End If
            End If
 
            ' If there are parameters, we append them manually to the relative path using a '?' character.
            If queryParameters.Any() Then
                Dim queryString As String = String.Join("&", queryParameters)
                relativePath = $"{relativePath}?{queryString}"
            End If
        End If
 
        Return relativePath
    End Function
 
    ''' <summary>
    ''' Validates that the provided token value does not exceed the maximum allowed byte size limit when encoded in <c>UTF-8</c>, 
    ''' which is 128 bytes (at least for key names) according to the <c>kvdb.io</c> service specifications.
    ''' <para></para>
    ''' Throws an <see cref="ArgumentException"/> if the byte size of the token exceeds the maximum allowed limit.
    ''' </summary>
    ''' 
    ''' <param name="token">
    ''' The token value to validate. This value can be null.
    ''' </param>
    ''' 
    ''' <param name="paramName">
    ''' The name of the parameter being validated for error tracing.
    ''' </param>
    ''' 
    ''' <exception cref="ArgumentException">
    ''' </exception>
    <DebuggerStepThrough>
    Friend Shared Sub ValidateTokenSize(token As String, paramName As String)
 
        Const MaxKvdbTokenByteSize As Integer = 128 ' In bytes, as per kvdb.io specifications.
 
#If NETCOREAPP Then
        ArgumentNullException.ThrowIfNullOrWhiteSpace(paramName, paramName:=NameOf(paramName))
#Else
        If String.IsNullOrWhiteSpace(paramName) Then : Throw New ArgumentNullException(paramName:=NameOf(paramName)) : End If
#End If
 
        If token IsNot Nothing Then
            Dim byteCount As Integer = Encoding.UTF8.GetByteCount(token)
 
            If byteCount > MaxKvdbTokenByteSize Then
                Throw New ArgumentException(
                    $"The token size ({byteCount} bytes) for parameter '{paramName}' exceeds the" &
                    " maximum allowed limit of {MaxKvdbTokenByteSize} bytes when encoded in UTF-8.",
                    paramName:=paramName)
            End If
        End If
    End Sub
 
#End Region
 
End Class

Name._x = Math.random()*320;
// Para zigzaguear:
Name.MinX = Name._x-Math.random()*EnemigosRate;
Name.MaxX = Name._x+Math.random()*EnemigosRate;
Name.SpeedX = Math.random()*MinEnemigoSpeed*(random(2)*2-1);

if (Name._x < Name.MinX or Name._x > Name.MaxX) {
	Name.SpeedX = Name.SpeedX*-1;
}