User defined types, bm-25, various fixes (#26)

Co-authored-by: Stephen Hewitt <stephenh@sembit.com>
Co-authored-by: jeffrey-elliott <jeffrey.elliott@gmail.com>
Co-authored-by: Steve Hewitt <45011981+stephenatsembit@users.noreply.github.com>

Author: 3 people

src/DataStax.AstraDB.DataApi/Admin/AstraDatabasesAdmin.cs

@@ -106,17 +106,39 @@ public async Task<List<string>> ListDatabaseNamesAsync(CommandOptions options)
     }
 
     /// <summary>
-    /// Returns a list of database info objects.
+    /// Synchronous version of <see cref="ListDatabasesAsync()"/>
     /// </summary>
-    /// <returns>A list of DatabaseInfo objects.</returns>
-    /// <example>
-    /// <code>
-    /// var databases = admin.ListDatabases();
-    /// </code>
-    /// </example>
+    /// <inheritdoc cref="ListDatabasesAsync()"/>
     public List<DatabaseInfo> ListDatabases()
     {
-        return ListDatabasesAsync(null, true).ResultSync();
+        return ListDatabases(null, null);
+    }
+
+    /// <summary>
+    /// Synchronous version of <see cref="ListDatabasesAsync(CommandOptions)"/>
+    /// </summary>
+    /// <inheritdoc cref="ListDatabasesAsync(CommandOptions)"/>
+    public List<DatabaseInfo> ListDatabases(CommandOptions options)
+    {
+        return ListDatabases(null, options);
+    }
+
+    /// <summary>
+    /// Synchronous version of <see cref="ListDatabasesAsync(ListDatabaseOptions)"/>
+    /// </summary>
+    /// <inheritdoc cref="ListDatabasesAsync(ListDatabaseOptions)"/>
+    public List<DatabaseInfo> ListDatabases(ListDatabaseOptions listOptions)
+    {
+        return ListDatabases(listOptions, null);
+    }
+
+    /// <summary>
+    /// Synchronous version of <see cref="ListDatabasesAsync(ListDatabaseOptions, CommandOptions)"/>
+    /// </summary>
+    /// <inheritdoc cref="ListDatabasesAsync(ListDatabaseOptions, CommandOptions)"/>
+    public List<DatabaseInfo> ListDatabases(ListDatabaseOptions listOptions, CommandOptions options)
+    {
+        return ListDatabasesAsync(null, options, true).ResultSync();
     }
 
     /// <summary>
@@ -130,44 +152,56 @@ public List<DatabaseInfo> ListDatabases()
     /// </example>
     public Task<List<DatabaseInfo>> ListDatabasesAsync()
     {
-        return ListDatabasesAsync(null, false);
+        return ListDatabasesAsync(null, null);
     }
 
     /// <summary>
-    /// Returns a list of database info objects using specified command options.
+    /// Asynchronously returns a list of database info objects using specified command options.
     /// </summary>
     /// <param name="options">The command options to use.</param>
-    /// <returns>A list of DatabaseInfo objects.</returns>
+    /// <returns>A task that resolves to a list of DatabaseInfo objects.</returns>
     /// <example>
     /// <code>
-    /// var databases = admin.ListDatabases(options);
+    /// var databases = await admin.ListDatabasesAsync(options);
     /// </code>
     /// </example>
-    public List<DatabaseInfo> ListDatabases(CommandOptions options)
+    public Task<List<DatabaseInfo>> ListDatabasesAsync(CommandOptions options)
     {
-        return ListDatabasesAsync(options, true).ResultSync();
+        return ListDatabasesAsync(null, options, false);
     }
 
     /// <summary>
-    /// Asynchronously returns a list of database info objects using specified command options.
+    ///  Asynchronously returns a list of database info objects using specified filtering options
     /// </summary>
-    /// <param name="options">The command options to use.</param>
-    /// <returns>A task that resolves to a list of DatabaseInfo objects.</returns>
-    /// <example>
-    /// <code>
-    /// var databases = await admin.ListDatabasesAsync(options);
-    /// </code>
-    /// </example>
-    public Task<List<DatabaseInfo>> ListDatabasesAsync(CommandOptions options)
+    /// <param name="listOptions"></param>
+    /// <returns></returns>
+    public Task<List<DatabaseInfo>> ListDatabasesAsync(ListDatabaseOptions listOptions)
     {
-        return ListDatabasesAsync(options, false);
+        return ListDatabasesAsync(listOptions, null, false);
     }
 
-    internal async Task<List<DatabaseInfo>> ListDatabasesAsync(CommandOptions options, bool runSynchronously)
+    /// <summary>
+    ///  Asynchronously returns a list of database info objects using specified command options and filtering options
+    /// </summary>
+    /// <param name="options"></param>
+    /// <param name="listOptions"></param>
+    /// <returns></returns>
+    public Task<List<DatabaseInfo>> ListDatabasesAsync(ListDatabaseOptions listOptions, CommandOptions options)
     {
+        return ListDatabasesAsync(listOptions, options, false);
+    }
+
+    internal async Task<List<DatabaseInfo>> ListDatabasesAsync(ListDatabaseOptions listOptions, CommandOptions options, bool runSynchronously)
+    {
+        if (listOptions == null)
+        {
+            listOptions = new ListDatabaseOptions();
+        }
+
         var command = CreateCommand()
             .AddUrlPath("databases")
             .WithTimeoutManager(new DatabaseAdminTimeoutManager())
+            .WithPayload(listOptions)
             .AddCommandOptions(options);
 
         var rawResults = await command.RunAsyncRaw<List<RawDatabaseInfo>>(HttpMethod.Get, runSynchronously).ConfigureAwait(false);
@@ -349,7 +383,7 @@ internal async Task<IDatabaseAdmin> CreateDatabaseAsync(DatabaseCreationOptions
         var databaseName = creationOptions.Name;
         Guard.NotNullOrEmpty(databaseName, nameof(databaseName));
 
-        List<DatabaseInfo> dbList = await ListDatabasesAsync(commandOptions, runSynchronously).ConfigureAwait(false);
+        List<DatabaseInfo> dbList = await ListDatabasesAsync(null, commandOptions, runSynchronously).ConfigureAwait(false);
 
         DatabaseInfo existingDb = dbList.FirstOrDefault(item => databaseName.Equals(item.Name));
 
@@ -568,7 +602,7 @@ public Task<bool> DropDatabaseAsync(Guid dbGuid, CommandOptions options)
     internal async Task<bool> DropDatabaseAsync(string databaseName, CommandOptions options, bool runSynchronously)
     {
         Guard.NotNullOrEmpty(databaseName, nameof(databaseName));
-        var dbList = await ListDatabasesAsync(options, runSynchronously).ConfigureAwait(false);
+        var dbList = await ListDatabasesAsync(null, options, runSynchronously).ConfigureAwait(false);
 
         var dbInfo = dbList.FirstOrDefault(item => item.Name.Equals(databaseName));
         if (dbInfo == null)
@@ -604,6 +638,19 @@ internal async Task<bool> DropDatabaseAsync(Guid dbGuid, CommandOptions options,
         return false;
     }
 
+
+    /// <summary>
+    /// Returns an IDatabaseAdmin instance for the database at the specified URL.
+    /// </summary>
+    /// <param name="dbUrl"></param>
+    /// <returns></returns>
+    public IDatabaseAdmin GetDatabaseAdmin(string dbUrl)
+    {
+        var database = _client.GetDatabase(dbUrl);
+        return new DatabaseAdminAstra(database, _client, null);
+    }
+
+
     /// <summary>
     /// Retrieves database information for the specified GUID.
     /// </summary>

src/DataStax.AstraDB.DataApi/Admin/DatabaseAdminAstra.cs

@@ -393,6 +393,7 @@ public Task DropKeyspaceAsync(string keyspace)
         }
 
         /// <inheritdoc cref="DropKeyspaceAsync(string)"/>
+        /// <param name="keyspace"></param>
         /// <param name="waitForCompletion">Whether or not to wait for the keyspace to be dropped before returning.</param>
         /// <example>
         /// <code>
@@ -405,8 +406,8 @@ public Task DropKeyspaceAsync(string keyspace, bool waitForCompletion)
         }
 
         /// <inheritdoc cref="DropKeyspaceAsync(string)"/>
+        /// <param name="keyspace"></param>
         /// <param name="options">Optional settings that influence request execution.</param>
-
         /// <example>
         /// <code>
         /// await admin.DropKeyspaceAsync("myKeyspace", options);
@@ -422,7 +423,9 @@ public Task DropKeyspaceAsync(string keyspace, CommandOptions options)
         }
 
         /// <inheritdoc cref="DropKeyspaceAsync(string, CommandOptions)"/>
+        /// <param name="keyspace"></param>
         /// <param name="waitForCompletion">Whether or not to wait for the keyspace to be dropped before returning.</param>
+        /// <param name="options"></param>
         /// <example>
         /// <code>
         /// await admin.DropKeyspaceAsync("myKeyspace", true, options);

src/DataStax.AstraDB.DataApi/Admin/DatabaseCreationOptions.cs

@@ -34,11 +34,11 @@ public class DatabaseCreationOptions
     public string Keyspace { get; set; } = Database.DefaultKeyspace;
 
     [JsonPropertyName("capacityUnits")]
-    public int CapacityUnits { get; set; } = 1;
+    internal int CapacityUnits { get; set; } = 1;
 
     [JsonPropertyName("tier")]
-    public string Tier { get; set; } = "serverless";
+    internal string Tier { get; set; } = "serverless";
 
     [JsonPropertyName("dbType")]
-    public string DatabaseType { get; set; } = "vector";
+    internal string DatabaseType { get; set; } = "vector";
 }

src/DataStax.AstraDB.DataApi/Admin/ListDatabaseOptions.cs

@@ -0,0 +1,79 @@
+/*
+ * Copyright DataStax, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+using DataStax.AstraDB.DataApi.Core;
+using System.Text.Json.Serialization;
+
+namespace DataStax.AstraDB.DataApi.Admin;
+
+/// <summary>
+/// Options used for ListDatabasesAsync.
+/// </summary>
+public class ListDatabaseOptions
+{
+    /// <summary>
+    /// Filter databases based on specific states.
+    /// </summary>
+    [JsonPropertyName("include")]
+    public QueryDatabaseStates StatesToInclude { get; set; } = QueryDatabaseStates.nonterminated;
+
+    /// <summary>
+    /// Filter databases based on cloud provider.
+    /// </summary>
+    [JsonPropertyName("cloudProvider")]
+    public QueryCloudProvider Provider { get; set; } = QueryCloudProvider.ALL;
+
+    /// <summary>
+    /// See <see cref="PageSizeLimit"/>. If getting an additional page of data, pass in the id of the last database in the previous page. 
+    /// </summary>
+    [JsonPropertyName("starting_after")]
+    internal string StartingAfter { get; set; }
+
+    /// <summary>
+    /// Number of items to return "per page".
+    /// </summary>
+    [JsonPropertyName("limit")]
+    public int PageSizeLimit = 100;
+}
+
+public enum QueryDatabaseStates
+{
+    nonterminated,
+    all,
+    active,
+    pending,
+    preparing,
+    prepared,
+    initializing,
+    parked,
+    parking,
+    unparking,
+    terminating,
+    terminated,
+    resizing,
+    error,
+    maintenance,
+    suspended,
+    suspending
+}
+
+public enum QueryCloudProvider
+{
+    ALL,
+    AWS,
+    GCP,
+    AZURE
+}