Skip to content

Commit 6b4c90c

Browse files
dnwparkdnwpark
committed
Add version of Create which takes params instead of Options.
1 parent ecdc707 commit 6b4c90c

File tree

1 file changed

+257
-10
lines changed

1 file changed

+257
-10
lines changed

‎src/Gel.Net.Driver/GelConnection.cs‎

Lines changed: 257 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -184,7 +184,7 @@ public TLSSecurityMode TLSSecurity
184184
/// Gets the TLS server name to be used.
185185
/// </summary>
186186
/// <remarks>
187-
/// Overrides the value provided by Hostname.
187+
/// Overrides the value provided by Hostname for TLS.
188188
/// </remarks>
189189
public string? TLSServerName { get; private set; }
190190

@@ -211,30 +211,277 @@ public int WaitUntilAvailable
211211
#region Create Function
212212

213213
/// <summary>
214-
/// Optional args which can be passed into <see cref="Create"/>.
214+
/// Parses the `gel.toml`, parameters, and environment variables to build a <see cref="GelConnection" />.
215+
///
216+
/// This function will first search for the first valid primary args (which can set host/port)
217+
/// in the following order:
218+
/// - Primary parameters
219+
/// - Environment variables
220+
/// - `gel.toml` file
221+
///
222+
/// It will then apply any secondary args from the environment variables and options.
223+
///
224+
/// If any primary parameters are present, then all environment variables are ignored.
225+
///
226+
/// See the <see href="https://docs.geldata.com/reference/clients/connection">documentation</see>
227+
/// for more information.
228+
/// </summary>
229+
/// <param name="instance">
230+
/// The name of a local instance, remote linked instance, or a Gel Cloud instance.
231+
///
232+
/// This is a primary parameter.
233+
/// </param>
234+
/// <param name="dsn">/>
235+
/// A connection URL of the form gel://user:pass@host:port/branch.
236+
/// For a guide to DSNs, see the
237+
/// <see href="https://docs.geldata.com/reference/reference/dsn#ref-dsn">DSN Specification</see>.
238+
///
239+
/// This is a primary parameter.
240+
/// </param>
241+
/// <param name="credentials">/>
242+
/// The json representation of the connection. See <see cref="ConnectionCredentials"/>.
243+
/// Checking in the value of this parameter could present a security risk and is not recommended.
244+
///
245+
/// This is a primary parameter.
246+
/// </param>
247+
/// <param name="credentialsFile">/>
248+
/// The path to a json file representing a connection. See <see cref="ConnectionCredentials"/>.
249+
/// Checking in the credentials file could present a security risk and is not recommended.
250+
///
251+
/// This is a primary parameter.
252+
/// </param>
253+
/// <param name="host">/>
254+
/// The hostname of the gel instance to connect to.
255+
///
256+
/// This is a primary parameter.
257+
/// </param>
258+
/// <param name="port">/>
259+
/// The port of the gel instance to connect to.
260+
///
261+
/// This is a primary parameter.
262+
/// </param>
263+
/// <param name="database">/>
264+
/// The database name to use when connecting. Mutually exclusive with <paramref name="branch"/>.
265+
///
266+
/// This is a secondary parameter.
267+
/// </param>
268+
/// <param name="branch">/>
269+
/// The branch name to use when connecting. Mutually exclusive with <paramref name="database"/>.
270+
///
271+
/// This is a secondary parameter.
272+
/// </param>
273+
/// <param name="user">/>
274+
/// The username used to connect to the database.
275+
///
276+
/// This is a secondary parameter.
277+
/// </param>
278+
/// <param name="password">/>
279+
/// The password to connect to the database.
280+
///
281+
/// This is a secondary parameter.
282+
/// </param>
283+
/// <param name="secretKey">/>
284+
/// The secret key used to authenticate with cloud instances.
285+
///
286+
/// This is a secondary parameter.
287+
/// </param>
288+
/// <param name="tlsCertificateAuthority">/>
289+
/// The TLS Certificate Authority.
290+
///
291+
/// This is a secondary parameter.
292+
/// </param>
293+
/// <param name="tlsCertificateAuthorityFile">/>
294+
/// The path to A file which contains the TLS Certificate Authority.
295+
///
296+
/// This is a secondary parameter.
297+
/// </param>
298+
/// <param name="tlsSecurity">/>
299+
/// The TLS security level.
300+
///
301+
/// This is a secondary parameter.
302+
/// </param>
303+
/// <param name="tlsServerName">/>
304+
/// The TLS server name. Overrides the hostname for TLS.
305+
///
306+
/// This is a secondary parameter.
307+
/// </param>
308+
/// <param name="waitUntilAvailable">/>
309+
/// The number of miliseconds a client will wait for a connection to be
310+
/// established with the server.
311+
///
312+
/// This is a secondary parameter.
313+
/// </param>
314+
/// <param name="serverSettings">/>
315+
/// Additional settings for the server connection. Currently has no effect
316+
///
317+
/// This is a secondary parameter.
318+
/// </param>
319+
/// <returns>
320+
/// A <see cref="GelConnection" /> class that can be used to connect to a Gel instance.
321+
/// </returns>
322+
/// <exception cref="ConfigurationException">
323+
/// An error occured while parsing or configuring the <see cref="GelConnection" />.
324+
/// </exception>
325+
public static GelConnection Create(
326+
string? instance = null,
327+
string? dsn = null,
328+
string? credentials = null,
329+
string? credentialsFile = null,
330+
string? host = null,
331+
int? port = null,
332+
string? database = null,
333+
string? branch = null,
334+
string? user = null,
335+
string? password = null,
336+
string? secretKey = null,
337+
string? tlsCertificateAuthority = null,
338+
string? tlsCertificateAuthorityFile = null,
339+
TLSSecurityMode? tlsSecurity = null,
340+
string? tlsServerName = null,
341+
string? waitUntilAvailable = null,
342+
Dictionary<string, string>? serverSettings = null
343+
)
344+
{
345+
Options options = new();
346+
return _Create(
347+
new()
348+
{
349+
Instance = instance,
350+
Dsn = dsn,
351+
Credentials = credentials,
352+
CredentialsFile = credentialsFile,
353+
Host = host,
354+
Port = port,
355+
Database = database,
356+
Branch = branch,
357+
User = user,
358+
Password = password,
359+
SecretKey = secretKey,
360+
TLSCertificateAuthority = tlsCertificateAuthority,
361+
TLSCertificateAuthorityFile = tlsCertificateAuthorityFile,
362+
TLSSecurity = tlsSecurity,
363+
TLSServerName = tlsServerName,
364+
WaitUntilAvailable = waitUntilAvailable,
365+
ServerSettings = serverSettings,
366+
367+
},
368+
ConfigUtils.DefaultPlatformProvider
369+
);
370+
}
371+
372+
/// <summary>
373+
/// Optional args which can be passed into <see cref="Create(Options?)"/>.
374+
///
375+
/// Primary args can set host/port of the connection.
215376
/// </summary>
216377
public sealed class Options
217378
{
218-
// Primary args
219-
// These can set host/port of the connection.
379+
/// <summary>
380+
/// The name of a local instance, remote linked instance, or a Gel Cloud instance.
381+
///
382+
/// This is a primary parameter.
383+
/// </summary>
220384
public string? Instance { get; set; }
385+
/// <summary>
386+
/// A connection URL of the form gel://user:pass@host:port/branch.
387+
/// For a guide to DSNs, see the
388+
/// <see href="https://docs.geldata.com/reference/reference/dsn#ref-dsn">DSN Specification</see>.
389+
///
390+
/// This is a primary parameter.
391+
/// </summary>
221392
public string? Dsn { get; set; }
393+
/// <summary>
394+
/// The json representation of the connection. See <see cref="ConnectionCredentials"/>.
395+
/// Checking in the value of this parameter could present a security risk and is not recommended.
396+
///
397+
/// This is a primary parameter.
398+
/// </summary>
222399
public string? Credentials { get; set; }
400+
/// <summary>
401+
/// The path to a json file representing a connection. See <see cref="ConnectionCredentials"/>.
402+
/// Checking in the credentials file could present a security risk and is not recommended.
403+
///
404+
/// This is a primary parameter.
405+
/// </summary>
223406
public string? CredentialsFile { get; set; }
407+
/// <summary>
408+
/// The hostname of the gel instance to connect to.
409+
///
410+
/// This is a primary parameter.
411+
/// </summary>
224412
public string? Host { get; set; }
413+
/// <summary>
414+
/// The port of the gel instance to connect to.
415+
///
416+
/// This is a primary parameter.
417+
/// </summary>
225418
public int? Port { get; set; }
226-
227-
// Secondary args
419+
/// <summary>
420+
/// The database name to use when connecting. Mutually exclusive with <see cref="Branch"/>.
421+
///
422+
/// This is a secondary parameter.
423+
/// </summary>
228424
public string? Database { get; set; }
425+
/// <summary>
426+
/// The branch name to use when connecting. Mutually exclusive with <see cref="Database"/>.
427+
///
428+
/// This is a secondary parameter.
429+
/// </summary>
229430
public string? Branch { get; set; }
431+
/// <summary>
432+
/// The username used to connect to the database.
433+
///
434+
/// This is a secondary parameter.
435+
/// </summary>
230436
public string? User { get; set; }
437+
/// <summary>
438+
/// The password to connect to the database.
439+
///
440+
/// This is a secondary parameter.
441+
/// </summary>
231442
public string? Password { get; set; }
443+
/// <summary>
444+
/// The secret key used to authenticate with cloud instances.
445+
///
446+
/// This is a secondary parameter.
447+
/// </summary>
232448
public string? SecretKey { get; set; }
449+
/// <summary>
450+
/// The TLS Certificate Authority.
451+
///
452+
/// This is a secondary parameter.
453+
/// </summary>
233454
public string? TLSCertificateAuthority { get; set; }
455+
/// <summary>
456+
/// The path to A file which contains the TLS Certificate Authority.
457+
///
458+
/// This is a secondary parameter.
459+
/// </summary>
234460
public string? TLSCertificateAuthorityFile { get; set; }
461+
/// <summary>
462+
/// The TLS security level.
463+
///
464+
/// This is a secondary parameter.
465+
/// </summary>
235466
public TLSSecurityMode? TLSSecurity { get; set; }
467+
/// <summary>
468+
/// The TLS server name. Overrides the hostname for TLS.
469+
///
470+
/// This is a secondary parameter.
471+
/// </summary>
236472
public string? TLSServerName { get; set; }
473+
/// <summary>
474+
/// The number of miliseconds a client will wait for a connection to be
475+
/// established with the server.
476+
///
477+
/// This is a secondary parameter.
478+
/// </summary>
237479
public string? WaitUntilAvailable { get; set; }
480+
/// <summary>
481+
/// Additional settings for the server connection. Currently has no effect.
482+
///
483+
/// This is a secondary parameter.
484+
/// </summary>
238485
public Dictionary<string, string>? ServerSettings { get; set; }
239486

240487
public bool IsEmpty =>
@@ -258,7 +505,7 @@ Instance is null
258505
}
259506

260507
/// <summary>
261-
/// Parses the `gel.toml`, optional <see cref="Options"/>, and environment variables to build an
508+
/// Parses the `gel.toml`, optional <see cref="Options"/>, and environment variables to build a
262509
/// <see cref="GelConnection" />.
263510
///
264511
/// This function will first search for the first valid primary args (which can set host/port)
@@ -271,7 +518,7 @@ Instance is null
271518
///
272519
/// If any primary <see cref="Options"/> are present, then all environment variables are ignored.
273520
///
274-
/// See the <see href="https://www.geldata.com/docs/reference/connection">documentation</see>
521+
/// See the <see href="https://docs.geldata.com/reference/clients/connection">documentation</see>
275522
/// for more information.
276523
/// </summary>
277524
/// <param name="options">Options used to build the <see cref="GelConnection" />.</param>
@@ -281,9 +528,9 @@ Instance is null
281528
/// <exception cref="ConfigurationException">
282529
/// An error occured while parsing or configuring the <see cref="GelConnection" />.
283530
/// </exception>
284-
public static GelConnection Create(Options? options = null)
531+
public static GelConnection Create(Options options)
285532
{
286-
return _Create(options ?? new(), ConfigUtils.DefaultPlatformProvider);
533+
return _Create(options, ConfigUtils.DefaultPlatformProvider);
287534
}
288535

289536
internal static GelConnection _Create(Options options, ISystemProvider platform)

0 commit comments

Comments
 (0)