diff --git a/src/Gel.Net.Driver/GelConnection.cs b/src/Gel.Net.Driver/GelConnection.cs index cccf042a..e5e8a967 100644 --- a/src/Gel.Net.Driver/GelConnection.cs +++ b/src/Gel.Net.Driver/GelConnection.cs @@ -184,7 +184,7 @@ public TLSSecurityMode TLSSecurity /// Gets the TLS server name to be used. /// /// - /// Overrides the value provided by Hostname. + /// Overrides the value provided by Hostname for TLS. /// public string? TLSServerName { get; private set; } @@ -211,30 +211,277 @@ public int WaitUntilAvailable #region Create Function /// - /// Optional args which can be passed into . + /// Parses the `gel.toml`, parameters, and environment variables to build a . + /// + /// This function will first search for the first valid primary args (which can set host/port) + /// in the following order: + /// - Primary parameters + /// - Environment variables + /// - `gel.toml` file + /// + /// It will then apply any secondary args from the environment variables and options. + /// + /// If any primary parameters are present, then all environment variables are ignored. + /// + /// See the documentation + /// for more information. + /// + /// + /// The name of a local instance, remote linked instance, or a Gel Cloud instance. + /// + /// This is a primary parameter. + /// + /// /> + /// A connection URL of the form gel://user:pass@host:port/branch. + /// For a guide to DSNs, see the + /// DSN Specification. + /// + /// This is a primary parameter. + /// + /// /> + /// The json representation of the connection. See . + /// Checking in the value of this parameter could present a security risk and is not recommended. + /// + /// This is a primary parameter. + /// + /// /> + /// The path to a json file representing a connection. See . + /// Checking in the credentials file could present a security risk and is not recommended. + /// + /// This is a primary parameter. + /// + /// /> + /// The hostname of the gel instance to connect to. + /// + /// This is a primary parameter. + /// + /// /> + /// The port of the gel instance to connect to. + /// + /// This is a primary parameter. + /// + /// /> + /// The database name to use when connecting. Mutually exclusive with . + /// + /// This is a secondary parameter. + /// + /// /> + /// The branch name to use when connecting. Mutually exclusive with . + /// + /// This is a secondary parameter. + /// + /// /> + /// The username used to connect to the database. + /// + /// This is a secondary parameter. + /// + /// /> + /// The password to connect to the database. + /// + /// This is a secondary parameter. + /// + /// /> + /// The secret key used to authenticate with cloud instances. + /// + /// This is a secondary parameter. + /// + /// /> + /// The TLS Certificate Authority. + /// + /// This is a secondary parameter. + /// + /// /> + /// The path to A file which contains the TLS Certificate Authority. + /// + /// This is a secondary parameter. + /// + /// /> + /// The TLS security level. + /// + /// This is a secondary parameter. + /// + /// /> + /// The TLS server name. Overrides the hostname for TLS. + /// + /// This is a secondary parameter. + /// + /// /> + /// The number of miliseconds a client will wait for a connection to be + /// established with the server. + /// + /// This is a secondary parameter. + /// + /// /> + /// Additional settings for the server connection. Currently has no effect + /// + /// This is a secondary parameter. + /// + /// + /// A class that can be used to connect to a Gel instance. + /// + /// + /// An error occured while parsing or configuring the . + /// + public static GelConnection Create( + string? instance = null, + string? dsn = null, + string? credentials = null, + string? credentialsFile = null, + string? host = null, + int? port = null, + string? database = null, + string? branch = null, + string? user = null, + string? password = null, + string? secretKey = null, + string? tlsCertificateAuthority = null, + string? tlsCertificateAuthorityFile = null, + TLSSecurityMode? tlsSecurity = null, + string? tlsServerName = null, + string? waitUntilAvailable = null, + Dictionary? serverSettings = null + ) + { + Options options = new(); + return _Create( + new() + { + Instance = instance, + Dsn = dsn, + Credentials = credentials, + CredentialsFile = credentialsFile, + Host = host, + Port = port, + Database = database, + Branch = branch, + User = user, + Password = password, + SecretKey = secretKey, + TLSCertificateAuthority = tlsCertificateAuthority, + TLSCertificateAuthorityFile = tlsCertificateAuthorityFile, + TLSSecurity = tlsSecurity, + TLSServerName = tlsServerName, + WaitUntilAvailable = waitUntilAvailable, + ServerSettings = serverSettings, + + }, + ConfigUtils.DefaultPlatformProvider + ); + } + + /// + /// Optional args which can be passed into . + /// + /// Primary args can set host/port of the connection. /// public sealed class Options { - // Primary args - // These can set host/port of the connection. + /// + /// The name of a local instance, remote linked instance, or a Gel Cloud instance. + /// + /// This is a primary parameter. + /// public string? Instance { get; set; } + /// + /// A connection URL of the form gel://user:pass@host:port/branch. + /// For a guide to DSNs, see the + /// DSN Specification. + /// + /// This is a primary parameter. + /// public string? Dsn { get; set; } + /// + /// The json representation of the connection. See . + /// Checking in the value of this parameter could present a security risk and is not recommended. + /// + /// This is a primary parameter. + /// public string? Credentials { get; set; } + /// + /// The path to a json file representing a connection. See . + /// Checking in the credentials file could present a security risk and is not recommended. + /// + /// This is a primary parameter. + /// public string? CredentialsFile { get; set; } + /// + /// The hostname of the gel instance to connect to. + /// + /// This is a primary parameter. + /// public string? Host { get; set; } + /// + /// The port of the gel instance to connect to. + /// + /// This is a primary parameter. + /// public int? Port { get; set; } - - // Secondary args + /// + /// The database name to use when connecting. Mutually exclusive with . + /// + /// This is a secondary parameter. + /// public string? Database { get; set; } + /// + /// The branch name to use when connecting. Mutually exclusive with . + /// + /// This is a secondary parameter. + /// public string? Branch { get; set; } + /// + /// The username used to connect to the database. + /// + /// This is a secondary parameter. + /// public string? User { get; set; } + /// + /// The password to connect to the database. + /// + /// This is a secondary parameter. + /// public string? Password { get; set; } + /// + /// The secret key used to authenticate with cloud instances. + /// + /// This is a secondary parameter. + /// public string? SecretKey { get; set; } + /// + /// The TLS Certificate Authority. + /// + /// This is a secondary parameter. + /// public string? TLSCertificateAuthority { get; set; } + /// + /// The path to A file which contains the TLS Certificate Authority. + /// + /// This is a secondary parameter. + /// public string? TLSCertificateAuthorityFile { get; set; } + /// + /// The TLS security level. + /// + /// This is a secondary parameter. + /// public TLSSecurityMode? TLSSecurity { get; set; } + /// + /// The TLS server name. Overrides the hostname for TLS. + /// + /// This is a secondary parameter. + /// public string? TLSServerName { get; set; } + /// + /// The number of miliseconds a client will wait for a connection to be + /// established with the server. + /// + /// This is a secondary parameter. + /// public string? WaitUntilAvailable { get; set; } + /// + /// Additional settings for the server connection. Currently has no effect. + /// + /// This is a secondary parameter. + /// public Dictionary? ServerSettings { get; set; } public bool IsEmpty => @@ -258,7 +505,7 @@ Instance is null } /// - /// Parses the `gel.toml`, optional , and environment variables to build an + /// Parses the `gel.toml`, optional , and environment variables to build a /// . /// /// This function will first search for the first valid primary args (which can set host/port) @@ -271,7 +518,7 @@ Instance is null /// /// If any primary are present, then all environment variables are ignored. /// - /// See the documentation + /// See the documentation /// for more information. /// /// Options used to build the . @@ -281,9 +528,9 @@ Instance is null /// /// An error occured while parsing or configuring the . /// - public static GelConnection Create(Options? options = null) + public static GelConnection Create(Options options) { - return _Create(options ?? new(), ConfigUtils.DefaultPlatformProvider); + return _Create(options, ConfigUtils.DefaultPlatformProvider); } internal static GelConnection _Create(Options options, ISystemProvider platform)