ConnectionPoolConfiguration.cs

/*
 * Copyright 2017 Stanislav Muhametsin. All rights Reserved.
 *
 * 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 CBAM.SQL.Implementation;
using System;
using System.Collections.Generic;
using System.IO;
using System.Net;
using System.Text;
using System.Threading.Tasks;
using CBAM.SQL.PostgreSQL.Implementation;
using UtilPack;
using CBAM.Abstractions.Implementation;
using CBAM.SQL.PostgreSQL;
using IOUtils.Network.Configuration;
using FluentCryptography.SASL;
using FluentCryptography.SASL.SCRAM;

#if !NETSTANDARD1_0
using IOUtils.Network.ResourcePooling;
#endif

namespace CBAM.SQL.PostgreSQL
{

   /// <summary>
   /// This class represents the passive data related to creation of new <see cref="PgSQLConnection"/>.
   /// Typically, this class holds the values written in some configuration file on a disk.
   /// Use <c>Microsoft.Extensions.Configuration.Binder</c> NuGet package to automatize the creation of this class and population of its properties.
   /// </summary>
   /// <remarks>
   /// See <see href="https://github.com/CometaSolutions/CBAM/tree/develop/Source/CBAM.SQL.PostgreSQL.Implementation"/> for small example on typical usecase of this class.
   /// </remarks>
   /// <seealso cref="PgSQLConnectionCreationInfo"/>
   public class PgSQLConnectionCreationInfoData : NetworkConnectionCreationInfoData<PgSQLConnectionConfiguration, PgSQLInitializationConfiguration, PgSQLProtocolConfiguration, PgSQLPoolingConfiguration, PgSQLAuthenticationConfiguration>
   {


   }

   /// <summary>
   /// This class contains all passive configuration data related to opening a socket connection when initializing new <see cref="PgSQLConnection"/>.
   /// </summary>
   public class PgSQLConnectionConfiguration : NetworkConnectionConfiguration
   {
   }

   /// <summary>
   /// This class contains all passive configuration data related to initialization routine of new <see cref="PgSQLConnection"/> once the <see cref="Stream"/> used to communicate with backend has been initialized.
   /// </summary>
   public class PgSQLInitializationConfiguration : NetworkInitializationConfiguration<PgSQLProtocolConfiguration, PgSQLPoolingConfiguration, PgSQLAuthenticationConfiguration>
   {
      /// <summary>
      /// Gets or sets the type containing passive configuration data about the database to connect to.
      /// </summary>
      /// <value>The type containing passive configuration data about the database to connect to.</value>
      /// <seealso cref="PgSQLDatabaseConfiguration"/>
      public PgSQLDatabaseConfiguration Database { get; set; }

   }

   /// <summary>
   /// This class contains all passive configuration data related to behaviour of PgSQL connections when they are used within the connection pool.
   /// </summary>
   public class PgSQLPoolingConfiguration : NetworkPoolingConfiguration
   {
   }

   /// <summary>
   /// This class contains all passive configuration data related to authentication of new <see cref="PgSQLConnection"/>.
   /// </summary>
   public class PgSQLAuthenticationConfiguration
   {

      internal static readonly Encoding PasswordByteEncoding = new UTF8Encoding( false, true );

      /// <summary>
      /// Gets or sets the username to use when connecting to the database.
      /// </summary>
      /// <value>The username to use when connecting to the database.</value>
      public String Username { get; set; }

      /// <summary>
      /// Gets the textual password as byte array, to use along with <see cref="Username"/> when connecting to the database.
      /// </summary>
      /// <value>The textual password as byte array, to use along with <see cref="Username"/> when connecting to the database.</value>
      /// <seealso cref="PasswordDigest"/>
      public Byte[] PasswordBytes { get; private set; }

      /// <summary>
      /// Gets or sets the digest of the cleartext password.
      /// </summary>
      /// <value>The digest of the cleartext password.</value>
      /// <remarks>
      /// This property will *only* be used in SCRAM authentication, if server chooses to perform it.
      /// The SCRAM authentication allows to use the digest of the password instead of cleartext password.
      /// </remarks>
      public Byte[] PasswordDigest { get; set; }

      /// <summary>
      /// Gets the password, as <see cref="String"/>, to use along with <see cref="Username"/> when connecting to the database.
      /// </summary>
      /// <value>The password, as <see cref="String"/>, to use along with <see cref="Username"/> when connecting to the database.</value>
      public String Password
      {
         get
         {
            var arr = this.PasswordBytes;
            return arr == null ? null : PasswordByteEncoding.GetString( arr, 0, arr.Length );
         }
         set
         {
            this.PasswordBytes = value == null ? null : PasswordByteEncoding.GetBytes( value );
         }
      }
   }

   /// <summary>
   /// This class contains all passive configuration data related to selecting which database the <see cref="PgSQLConnection"/> will be connected to, as well as authentication to that database.
   /// </summary>
   public class PgSQLDatabaseConfiguration
   {

      /// <summary>
      /// Gets or sets the name of the database that the <see cref="PgSQLConnection"/> should be connected to.
      /// </summary>
      /// <value>The name of the database that the <see cref="PgSQLConnection"/> should be connected to.</value>
      public String Name { get; set; }

      /// <summary>
      /// Gets the search path (<see href="https://www.postgresql.org/docs/current/static/runtime-config-client.html"/>) to use for the database.
      /// </summary>
      /// <value>The search path (<see href="https://www.postgresql.org/docs/current/static/runtime-config-client.html"/>) to use for the database.</value>
      public String SearchPath { get; set; }
   }

   /// <summary>
   /// This class contains all passive data configuration related to protocol used to communicate with backend process.
   /// </summary>
   public class PgSQLProtocolConfiguration
   {
      /// <summary>
      /// Gets or sets the value indicating whether SQL type IDs should be re-read from database, even though they have been previously cached for the version of PostgreSQL backend connected to.
      /// </summary>
      /// <value>The value indicating whether SQL type IDs should be re-read from database</value>
      public Boolean ForceTypeIDLoad { get; set; }

      /// <summary>
      /// Gets or sets the value indicating whether <see cref="DataFormat.Binary"/> should be disabled when sending data to the backend.
      /// </summary>
      /// <value>The value indicating whether <see cref="DataFormat.Binary"/> should be disabled when sending data to the backend.</value>
      public Boolean DisableBinaryProtocolSend { get; set; }

      /// <summary>
      /// Gets or sets the value indicating whether <see cref="DataFormat.Binary"/> should be disabled when receiving data from the backend.
      /// </summary>
      /// <value>The value indicating whether <see cref="DataFormat.Binary"/> should be disabled when receiving data from the backend.</value>
      public Boolean DisableBinaryProtocolReceive { get; set; }
   }

   /// <summary>
   /// This class binds together the passive configuration data of the <see cref="PgSQLConnectionCreationInfoData"/> and behaviour (callbacks) needed when creating and initializing <see cref="PgSQLConnection"/>s.
   /// </summary>
   public sealed class PgSQLConnectionCreationInfo : NetworkConnectionCreationInfo<PgSQLConnectionCreationInfoData, PgSQLConnectionConfiguration, PgSQLInitializationConfiguration, PgSQLProtocolConfiguration, PgSQLPoolingConfiguration, PgSQLAuthenticationConfiguration>
   {
      private const String SCRAM_SHA_256 = "SCRAM-SHA-256";
      private const String SCRAM_SHA_512 = "SCRAM-SHA-512";

      /// <summary>
      /// Creates a new instance of <see cref="PgSQLConnectionCreationInfo"/> with given <see cref="PgSQLConnectionCreationInfoData"/>.
      /// </summary>
      /// <param name="data">The <see cref="PgSQLConnectionCreationInfoData"/> to use.</param>
      /// <exception cref="ArgumentNullException">If <paramref name="data"/> is <c>null</c>.</exception>
      /// <remarks>
      /// In .NET Core App 1.1+ and .NET Desktop 4.0+ environments this will also set up default values for <see cref="P:CBAM.SQL.PostgreSQL.PgSQLConnectionCreationInfo.ProvideSSLStream"/>.
      /// </remarks>
      public PgSQLConnectionCreationInfo(
         PgSQLConnectionCreationInfoData data
         ) : base( data )
      {
         this.CreateSASLMechanism = ( names ) =>
         {
            FluentCryptography.Digest.BlockDigestAlgorithm algorithm;
            String mechanismName;

            if ( String.IsNullOrEmpty( names ) )
            {
               algorithm = null;
               mechanismName = null;
            }
            else
            {
               if ( names.IndexOf( SCRAM_SHA_512 ) >= 0 )
               {
                  algorithm = new FluentCryptography.Digest.SHA512();
                  mechanismName = SCRAM_SHA_512;
               }
               else if ( names.IndexOf( SCRAM_SHA_256 ) >= 0 )
               {
                  algorithm = new FluentCryptography.Digest.SHA256();
                  mechanismName = SCRAM_SHA_256;
               }
               else
               {
                  algorithm = null;
                  mechanismName = null;
               }
            }

            return (algorithm?.CreateSASLClientSCRAM(), mechanismName);
         };
      }
      /// <summary>
      /// This callback will be used during SCRAM authentication to select the <see cref="SASLMechanism"/> based on the advertised mechanisms sent by server as a string.
      /// The constructor will set this to default value which supports SCRAM-SHA-256 and SCRAM-SHA-512, but this may be overridden for custom <see cref="SASLMechanism"/>s.
      /// </summary>
      /// <value>The callback to select <see cref="SASLMechanism"/> from a list of SASL mechanisms advertised by backend.</value>
      /// <remarks>
      /// This callback should return a tuple of <see cref="SASLMechanism"/> and the name of it.
      /// </remarks>
      public Func<String, (SASLMechanism, String)> CreateSASLMechanism { get; set; }

      /// <summary>
      /// This callback will be used during SCRAM authentication, when the user is successfully authenticated.
      /// It will receive a digest of the cleartext password, so that it can be e.g. saved for later purpose.
      /// </summary>
      /// <value>The callback to call on successful SASL SCRAM authentication, receiving password digest as argument.</value>
      public Action<Byte[]> OnSASLSCRAMSuccess { get; set; }

   }
}

/// <summary>
/// This class contains extension methods for types defined in this assembly.
/// </summary>
public static partial class E_CBAM
{
   /// <summary>
   /// This is helper method to create a new deep copy of this <see cref="PgSQLConnectionCreationInfoData"/> instance.
   /// </summary>
   /// <param name="data">This <see cref="PgSQLConnectionCreationInfoData"/>.</param>
   /// <returns>A new instance of <see cref="PgSQLConnectionCreationInfoData"/>, with all values deeply copied from this <see cref="PgSQLConnectionCreationInfoData"/>.</returns>
   /// <exception cref="NullReferenceException">If this <see cref="PgSQLConnectionCreationInfoData"/> is <c>null</c>.</exception>
   public static PgSQLConnectionCreationInfoData CreateCopy( this PgSQLConnectionCreationInfoData data )
   {

#if !NETSTANDARD1_0
      var conn = data.Connection;
#endif

      var init = data.Initialization;
      var db = init?.Database;
      var protocol = init?.Protocol;
      var pool = init?.ConnectionPool;
      var auth = init?.Authentication;

      return new PgSQLConnectionCreationInfoData()
      {
#if !NETSTANDARD1_0
         Connection = new PgSQLConnectionConfiguration()
         {
            Host = conn?.Host,
            Port = conn?.Port ?? 0,
            ConnectionSSLMode = conn?.ConnectionSSLMode ?? ConnectionSSLMode.NotRequired,
            SSLProtocols = conn?.SSLProtocols ?? PgSQLConnectionConfiguration.DEFAULT_SSL_PROTOCOL
         },
#endif
         Initialization = new PgSQLInitializationConfiguration()
         {
            Database = new PgSQLDatabaseConfiguration()
            {
               Name = db?.Name,
               SearchPath = db?.SearchPath
            },
            Authentication = new PgSQLAuthenticationConfiguration()
            {
               Username = auth?.Username,
               Password = auth?.Password,
               PasswordDigest = auth?.PasswordDigest
            },
            Protocol = new PgSQLProtocolConfiguration()
            {
               ForceTypeIDLoad = protocol?.ForceTypeIDLoad ?? false,
               DisableBinaryProtocolSend = protocol?.DisableBinaryProtocolSend ?? false,
               DisableBinaryProtocolReceive = protocol?.DisableBinaryProtocolReceive ?? false
            },
            ConnectionPool = new PgSQLPoolingConfiguration()
            {
               ConnectionsOwnStringPool = pool?.ConnectionsOwnStringPool ?? false
            }
         }
      };
   }
}