Allow specifying a PSR-3 logger for the server process.

Fix some race conditions on server shutdown and signal handling in child processes.

Author: ChadSikorra

composer.json

@@ -18,13 +18,14 @@
     "php": ">=7.1",
     "freedsx/asn1": "^0.4.0",
     "freedsx/socket": "^0.5.2",
-    "freedsx/sasl": "^0.1.0"
+    "freedsx/sasl": "^0.1.0",
+    "psr/log": "^1|^2|^3"
   },
   "require-dev": {
-    "phpspec/phpspec": "^5.1|^6.1|^7.1",
+    "phpspec/phpspec": "^7.2|^7.1|^6.1|^5.1",
     "phpunit/phpunit": "^9.3|^8.0|^7.0",
     "symplify/easy-coding-standard": "^6.1|^7.3|^9.0",
-    "friends-of-phpspec/phpspec-code-coverage": "^4.3|^6.1",
+    "friends-of-phpspec/phpspec-code-coverage": "^4.3|^6.1|dev-master",
     "phpstan/phpstan": "^0.12.70",
     "symfony/process": "^3.0|^4.0|^5.0",
     "squizlabs/php_codesniffer": "3.*",

docs/Server/Configuration.md

@@ -6,6 +6,7 @@ LDAP Server Configuration
     * [port](#port)
     * [unix_socket](#unix_socket)
     * [transport](#transport)
+    * [logger](#logger)
     * [idle_timeout](#idle_timeout)
     * [require_authentication](#require_authentication)
     * [allow_anonymous](#allow_anonymous)
@@ -75,6 +76,25 @@ If using `unix` for the transport you can change set the `unix_socket` to a file
 
 **Default**: `tcp`
 
+------------------
+#### logger
+
+Specify a PSR-3 compatible logging instance to use. This will log various server events and errors.
+
+You can also set the logger after instantiating the server and before running it:
+
+```php
+use FreeDSx\Ldap\LdapServer;
+
+$server = new LdapServer();
+
+// instantiate some logger class...
+
+$server->useLogger($logger);
+```
+
+**Default**: `null`
+
 ------------------
 #### idle_timeout
 

src/FreeDSx/Ldap/LdapServer.php

@@ -21,6 +21,7 @@
 use FreeDSx\Ldap\Server\ServerRunner\ServerRunnerInterface;
 use FreeDSx\Socket\Exception\ConnectionException;
 use FreeDSx\Socket\SocketServer;
+use Psr\Log\LoggerInterface;
 
 /**
  * The LDAP server.
@@ -29,6 +30,8 @@
  */
 class LdapServer
 {
+    use LoggerTrait;
+
     /**
      * @var array
      */
@@ -43,6 +46,7 @@ class LdapServer
         'request_handler' => null,
         'rootdse_handler' => null,
         'paging_handler' => null,
+        'logger' => null,
         'use_ssl' => false,
         'ssl_cert' => null,
         'ssl_cert_passphrase' => null,
@@ -147,6 +151,16 @@ public function usePagingHandler(PagingHandlerInterface $pagingHandler): self
         return $this;
     }
 
+    /**
+     * Specify a logger to be used by the server process.
+     */
+    public function useLogger(LoggerInterface $logger): self
+    {
+        $this->options['logger'] = $logger;
+
+        return $this;
+    }
+
     /**
      * Convenience method for generating an LDAP server instance that will proxy client request's to an LDAP server.
      *
@@ -191,14 +205,14 @@ private function removeExistingSocketIfNeeded(string $socket): void
         }
 
         if (!is_writeable($socket)) {
-            throw new RuntimeException(sprintf(
+            $this->logAndThrow(sprintf(
                 'The socket "%s" already exists and is not writeable. To run the LDAP server, you must remove the existing socket.',
                 $socket
             ));
         }
 
         if (!unlink($socket)) {
-            throw new RuntimeException(sprintf(
+            $this->logAndThrow(sprintf(
                 'The existing socket "%s" could not be removed. To run the LDAP server, you must remove the existing socket.',
                 $socket
             ));

src/FreeDSx/Ldap/LoggerTrait.php

@@ -0,0 +1,85 @@
+<?php
+
+/**
+ * This file is part of the FreeDSx LDAP package.
+ *
+ * (c) Chad Sikorra <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace FreeDSx\Ldap;
+
+use FreeDSx\Ldap\Exception\RuntimeException;
+use Psr\Log\LoggerInterface;
+use Psr\Log\LogLevel;
+
+/**
+ * Some simple logging methods. Only logs if we have a logger in the options.
+ *
+ * @author Chad Sikorra <[email protected]>
+ */
+trait LoggerTrait
+{
+    /**
+     * Logs a message and then throws a runtime exception.
+     *
+     * @throws RuntimeException
+     */
+    private function logAndThrow(
+        string $message,
+        array $context = []
+    ): void {
+        $this->log(
+            LogLevel::ERROR,
+            $message,
+            $context
+        );
+
+        throw new RuntimeException($message);
+    }
+
+    protected function logError(
+        string $message,
+        array $context = []
+    ): void {
+        $this->log(
+            LogLevel::ERROR,
+            $message,
+            $context
+        );
+    }
+
+    protected function logInfo(
+        string $message,
+        array $context = []
+    ): void {
+        $this->log(
+            LogLevel::INFO,
+            $message,
+            $context
+        );
+    }
+
+    /**
+     * Log a message with a level and context (if we have a logger).
+     *
+     * @param string $level
+     * @param string $message
+     * @param array $context
+     */
+    private function log(
+        string $level,
+        string $message,
+        array $context = []
+    ): void {
+        if (isset($this->options['logger']) && $this->options['logger'] instanceof LoggerInterface) {
+            $this->options['logger']->log(
+                $level,
+                $message,
+                $context
+            );
+        }
+    }
+}

src/FreeDSx/Ldap/Protocol/ServerProtocolHandler.php

@@ -24,6 +24,7 @@
 use FreeDSx\Ldap\Protocol\Queue\ServerQueue;
 use FreeDSx\Ldap\Server\HandlerFactoryInterface;
 use FreeDSx\Ldap\Server\RequestHistory;
+use FreeDSx\Ldap\LoggerTrait;
 use FreeDSx\Ldap\Server\Token\TokenInterface;
 use FreeDSx\Socket\Exception\ConnectionException;
 use Throwable;
@@ -37,6 +38,8 @@
  */
 class ServerProtocolHandler
 {
+    use LoggerTrait;
+
     /**
      * @var array
      */
@@ -85,6 +88,11 @@ class ServerProtocolHandler
      */
     protected $bindHandlerFactory;
 
+    /**
+     * @var array<string, mixed>
+     */
+    protected $defaultContext = [];
+
     public function __construct(
         ServerQueue $queue,
         HandlerFactoryInterface $handlerFactory,
@@ -111,9 +119,10 @@ public function __construct(
      *
      * @throws EncoderException
      */
-    public function handle(): void
+    public function handle(array $defaultContext = []): void
     {
         $message = null;
+        $this->defaultContext = $defaultContext;
 
         try {
             while ($message = $this->queue->getMessage()) {
@@ -135,7 +144,18 @@ public function handle(): void
             # Per RFC 4511, 4.1.1 if the PDU cannot be parsed or is otherwise malformed a disconnect should be sent with a
             # result code of protocol error.
             $this->sendNoticeOfDisconnect('The message encoding is malformed.');
+            $this->logError(
+                'The client sent a malformed request. Terminating their connection.',
+                $this->defaultContext
+            );
         } catch (Exception | Throwable $e) {
+            $this->logError(
+                'An unexpected exception was caught while handling the client. Terminating their connection.',
+                array_merge(
+                    $this->defaultContext,
+                    ['exception' => $e]
+                )
+            );
             if ($this->queue->isConnected()) {
                 $this->sendNoticeOfDisconnect();
             }
@@ -151,13 +171,17 @@ public function handle(): void
      *
      * @throws EncoderException
      */
-    public function shutdown(): void
+    public function shutdown(array $context = []): void
     {
         $this->sendNoticeOfDisconnect(
             'The server is shutting down.',
             ResultCode::UNAVAILABLE
         );
         $this->queue->close();
+        $this->logInfo(
+            'Sent notice of disconnect to client and closed the connection.',
+            $context
+        );
     }
 
     /**