rom-ldap 0.2.2

data/TODO.md

@@ -0,0 +1,33 @@
+# TODO
+
+1. **Time out limit and retry in client.**
+    Test timeout expiration and retry in client methods.
+
+2. **SSL connections.**
+    Hand secure connections; also some vendors only permit certain functions through a secure connection.
+
+3. **Rouge lexer for LDAP filters.**
+    Custom terminal syntax for LDAP similar to rom-sql.
+
+4. **Paged results.**
+    Use a real paged request instead of chunking all results
+
+5. **Transactions.**
+    Rollback failed actions on compatible LDAP servers.
+    <https://www.port389.org/docs/389ds/design/exop-plugin-transactions.html>
+
+6. **Associated relations - preload_assoc and transproc.**
+    Build LDAP to LDAP relation associations automatically.
+    Simple rudimentary RDMS.
+    <https://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS>
+
+7. Directory instrumentation using dry-monitor to replace debug logging.
+
+8. `rom/devtools` integration.
+
+
+## ONGOING
+
+- Improve Rspec coverage, currently 90% complete @ v0.1.0
+- Improve Yard docs, currently 72% complete @ v0.1.0
+- Ensure Rubocop style compliance

data/config/responses.yml

@@ -0,0 +1,328 @@
+---
+# Detailed responses from LDAP server.
+# @see https://ldapwiki.com/wiki/LDAP%20Result%20Codes
+#
+:success:
+  - Success
+  - Indicates the requested client operation completed successfully.
+  - LDAP_SUCCESS:0x00
+:operations_error:
+  - Operations Error
+  - >
+    Indicates an internal error.
+    The server is unable to respond with a more specific error and is also unable to properly respond to a request.
+    It does not indicate that the client has sent an erroneous message.
+  - LDAP_OPERATIONS_ERROR:0x01
+:protocol_error:
+  - Protocol Error
+  - Indicates that the server has received an invalid or malformed request from the client.
+  - LDAP_PROTOCOL_ERROR:0x02
+:time_limit_exceeded:
+  - Time Limit Exceeded
+  - >
+    Indicates the operation's time limit specified by either the client or the server has been exceeded.
+    On search operations, incomplete results are returned.
+  - LDAP_TIMELIMIT_EXCEEDED:0x03
+:size_limit_exceeded:
+  - Size Limit Exceeded
+  - >
+    Indicates in a search operation, the size limit specified by the client or the server has been exceeded.
+    Incomplete results are returned.
+  - LDAP_SIZELIMIT_EXCEEDED:0x04
+:compare_false:
+  - False Comparison
+  - >
+    Does not indicate an error condition.
+    Indicates that the results of a compare operation are false.
+  - LDAP_COMPARE_FALSE:0x05
+:compare_true:
+  - True Comparison
+  - >
+    Does not indicate an error condition.
+    Indicates that the results of a compare operation are true.
+  - LDAP_COMPARE_TRUE:0x06
+:auth_method_not_supported:
+  - Authentication Method Not Supported
+  - Indicates during a bind operation the client requested an authentication method not supported by the LDAP server.
+  - LDAP_AUTH_METHOD_NOT_SUPPORTED:0x07
+:stronger_auth_required:
+  - Stronger Authentication Needed
+  - >
+    Indicates one of the following:
+    In bind requests, the LDAP server accepts only strong authentication.
+    In a client request, the client requested an operation such as delete that requires strong authentication.
+    In an unsolicited notice of disconnection, the LDAP server discovers the security protecting the communication between the client and server has unexpectedly failed or been compromised.
+  - LDAP_STRONG_AUTH_REQUIRED:0x08
+:reserved:
+  - Reserved
+  - Reserved.
+  - Reserved:0x09
+:referral:
+  - Referral
+  - >
+    Does not indicate an error condition.
+    In LDAPv3, indicates that the server does not hold the target entry of the request, but that the servers in the referral field may.
+  - LDAP_REFERRAL:0x0A
+:admin_limit_exceeded:
+  - Admin Limit Exceeded
+  - Indicates an LDAP server limit set by an administrative authority has been exceeded.
+  - LDAP_ADMINLIMIT_EXCEEDED:0x0B
+:unavailable_critical_extension:
+  - Unavailable Critical Extension
+  - >
+    Indicates the LDAP server was unable to satisfy a request because one or more critical extensions were not available.
+    Either the server does not support the control or the control is not appropriate for the operation type.
+  - LDAP_UNAVAILABLE_CRITICAL_EXTENSION:0x0C
+:confidentiality_required:
+  - Confidentiality Required
+  - Indicates the session is not protected by a protocol such as Transport Layer Security (TLS), which provides session confidentiality.
+  - LDAP_CONFIDENTIALITY_REQUIRED:0x0D
+:sasl_bind_in_progress:
+  - SASL Bind In Progress
+  - >
+    Does not indicate an error condition, but indicates the server is ready for the next step in the process.
+    The client must send the server the same SASL mechanism to continue the process.
+  - LDAP_SASL_BIND_IN_PROGRESS:0x0E
+:not_used:
+  - Not Used
+  - Not used.
+  - NotUsed:0x0F
+:no_such_attribute:
+  - No Such Attribute
+  - Indicates the attribute specified in the modify or compare operation does not exist in the entry.
+  - LDAP_NO_SUCH_ATTRIBUTE:0x10
+:undefined_attribute_type:
+  - Undefined Attribute Type
+  - Indicates the attribute specified in the modify or add operation does not exist in the LDAP server's schema.
+  - LDAP_UNDEFINED_TYPE:0x11
+:inappropriate_matching:
+  - Inappropriate Matching
+  - Indicates the matching rule specified in the search filter does not match a rule defined for the attribute's syntax.
+  - LDAP_INAPPROPRIATE_MATCHING:0x12
+:constraint_violation:
+  - Constraint Violation
+  - >
+    Indicates the attribute value specified in a modify, add, or modify DN operation violates constraints placed on the attribute.
+    The constraint can be one of size or content (string only, no binary).
+  - LDAP_CONSTRAINT_VIOLATION:0x13
+:attribute_or_value_exists:
+  - Attribute or Value Exists
+  - Indicates the attribute value specified in a modify or add operation already exists as a value for that attribute.
+  - LDAP_TYPE_OR_VALUE_EXISTS:0x14
+:invalid_attribute_syntax:
+  - Invalid Attribute Syntax
+  - Indicates the attribute value specified in an add, compare, or modify operation is an unrecognized or invalid syntax for the attribute.
+  - LDAP_INVALID_SYNTAX:0x15
+#
+# 22..31 - Not used.
+#
+:no_such_object:
+  - No Such Object
+  - >
+    Indicates the target object cannot be found.
+    This code is not returned on following operations:
+    Search operations that find the search base but cannot find any entries that match the search filter.
+    Bind operations.
+  - LDAP_NO_SUCH_OBJECT:0x20
+:alias_problem:
+  - Alias Problem
+  - Indicates an error occurred when an alias was dereferenced.
+  - LDAP_ALIAS_PROBLEM:0x21
+:invalid_dn_syntax:
+  - Invalid DN Syntax
+  - >
+    Indicates the syntax of the DN is incorrect.
+    If the DN syntax is correct, but the LDAP server's structure rules do not permit the operation, the server returns LDAP_UNWILLING_TO_PERFORM.
+  - LDAP_INVALID_DN_SYNTAX:0x22
+:ldap_is_leaf:
+  - Failed On Leaf
+  - >
+    Indicates the specified operation cannot be performed on a leaf entry.
+    This code is not currently in the LDAP specifications, but is reserved for this constant.
+  - LDAP_IS_LEAF:0x23
+:alias_dereferencing_problem:
+  - Alias Dereferencing Problem
+  - Indicates during a search operation, either the client does not have access rights to read the aliased object's name or dereferencing is not allowed.
+  - LDAP_ALIAS_DEREF_PROBLEM:0x24
+#
+# 37..47 - Not used.
+#
+:inappropriate_authentication:
+  - Inappropriate Authentication
+  - >
+    Indicates during a bind operation, the client is attempting to use an authentication method that the client cannot use correctly.
+    For example, either of the following cause this error:
+    The client returns simple credentials when strong credentials are required.
+    The client returns a DN and a password for a simple bind when the entry does not have a password defined.
+  - LDAP_INAPPROPRIATE_AUTH:0x30
+:invalid_credentials:
+  - Invalid Credentials
+  - >
+    Indicates during a bind operation one of the following occurred:
+    The client passed either an incorrect DN or password.
+    The password is incorrect because it has expired, intruder detection has locked the account, or some other similar reason.
+  - LDAP_INVALID_CREDENTIALS:0x31
+:insufficient_access_rights:
+  - Insufficient Access Rights
+  - Indicates the caller does not have sufficient rights to perform the requested operation.
+  - LDAP_INSUFFICIENT_ACCESS:0x32
+:busy:
+  - Busy
+  - Indicates the LDAP server is too busy to process the client request at this time but if the client waits and resubmits the request, the server may be able to process it then.
+  - LDAP_BUSY:0x33
+:unavailable:
+  - Unavailable
+  - Indicates the LDAP server cannot process the client's bind request, usually because it is shutting down.
+  - LDAP_UNAVAILABLE:0x34
+:unwilling_to_perform:
+  - Unwilling To Perform
+  - >
+    Indicates the LDAP server cannot process the request because of server-defined restrictions.
+    This error is returned for the following reasons:
+    The add entry request violates the server's structure rules.
+    The modify attribute request specifies attributes that users cannot modify.
+    Password restrictions prevent the action.
+    Connection restrictions prevent the action.
+  - LDAP_UNWILLING_TO_PERFORM:0x35
+:loop_detected:
+  - Referral Loop Detected
+  - Indicates the client discovered an alias or referral loop, and is thus unable to complete this request.
+  - LDAP_LOOP_DETECT:0x36
+#
+# 55..63 - Not used.
+#
+:naming_violation:
+  - Naming Violation
+  - >
+    Indicates the add or modify DN operation violates the schema's structure rules. For example,
+    The request places the entry subordinate to an alias.
+    The request places the entry subordinate to a container that is forbidden by the containment rules.
+    The RDN for the entry uses a forbidden attribute type.
+    LDAP_NAMING_VIOLATION:0x40
+:object_class_violation:
+  - Object Class Violation
+  - >
+    Indicates the add, modify, or modify DN operation violates the object class rules for the entry.
+    For example, the following types of request return this error:
+    The add or modify operation tries to add an entry without a value for a required attribute.
+    The add or modify operation tries to add an entry with a value for an attribute which the class definition does not contain.
+    The modify operation tries to remove a required attribute without removing the auxiliary class that defines the attribute as required.
+  - LDAP_OBJECT_CLASS_VIOLATION:0x41
+:not_allowed_on_non_leaf:
+  - Not Allowed On Non-Leaf
+  - >
+    Indicates the requested operation is permitted only on leaf entries.
+    For example, the following types of requests return this error:
+    The client requests a delete operation on a parent entry.
+    The client request a modify DN operation on a parent entry.
+  - LDAP_NOT_ALLOWED_ON_NONLEAF:0x42
+:not_allowed_on_rdn:
+  - Not Allowed On RDN
+  - Indicates the modify operation attempted to remove an attribute value that forms the entry's relative distinguished name.
+  - LDAP_NOT_ALLOWED_ON_RDN:0x43
+:entry_already_exists:
+  - Entry Already Exists
+  - Indicates the add operation attempted to add an entry that already exists, or that the modify operation attempted to rename an entry to the name of an entry that already exists.
+  - LDAP_ALREADY_EXISTS:0x44
+:object_class_mods_prohibited:
+  - ObjectClass Modifications Prohibited
+  - Indicates the modify operation attempted to modify the structure rules of an object class.
+  - LDAP_NO_OBJECT_CLASS_MODS:0x45
+:reserved_for_cldap:
+  - Reserved for CLDAP
+  -
+  - LDAP_RESULTS_TOO_LARGE:0x46
+:affects_multiple_dsas:
+  - Affects Multiple DSAs
+  - Indicates the modify DN operation moves the entry from one LDAP server to another and thus requires more than one LDAP server.
+  - LDAP_AFFECTS_MULTIPLE_DSAS:0x47
+#
+# 72..79 - Not used.
+#
+:other:
+  - Other
+  - >
+    Indicates an unknown error condition.
+    This is the default value for NDS error codes which do not map to other LDAP error codes.
+  - LDAP_OTHER:0x50
+:server_down:
+  - Server Down
+  - Indicates the LDAP client cannot establish a connection with, or lost the connection to, the LDAP server.
+  - LDAP_SERVER_DOWN:0x51
+:local_error:
+  - Local Client Error
+  - Indicates an error occurred in the LDAP client.
+  - LDAP_LOCAL_ERROR:0x52
+:encoding_error:
+  - Encoding Error
+  - Indicates the LDAP client encountered an error when encoding the LDAP request to be sent to the server.
+  - LDAP_ENCODING_ERROR:0x53
+:decoding_error:
+  - Decoding Error
+  - Indicates the LDAP client encountered an error when decoding the LDAP response received from the server.
+  - LDAP_DECODING_ERROR:0x54
+:timeout:
+  - Timeout
+  - >
+    Indicates the LDAP client timed out while waiting for a response from the server.
+    The specified timeout period has been exceeded and the server has not responded.
+  - LDAP_TIMEOUT:0x55
+:auth_method_unknown:
+  - Unknown Authentication Method
+  - Indicates an unknown authentication method was specified.
+  - LDAP_AUTH_UNKNOWN:0x56
+:filter_error:
+  - Filter Error
+  - Indicates an error occurred when specifying the search filter.
+  - LDAP_FILTER_ERROR:0x57
+:user_cancelled:
+  - User Cancelled
+  - Indicates the user cancelled the LDAP operation
+  - LDAP_USER_CANCELLED:0x58
+:param_error:
+  - Invalid Parameter
+  - Indicates that an invalid parameter was specified.
+  - LDAP_PARAM_ERROR:0x59
+:no_memory:
+  - No Memory
+  - >
+    Indicates that no memory is available.
+    For example, when creating an LDAP request or an LDAP control.
+  - LDAP_NO_MEMORY:0x5a
+:connect_error:
+  - Connection Error
+  - Indicates the LDAP client cannot establish a connection, or has lost the connection, with the LDAP server.
+  - LDAP_CONNECT_ERROR:0x5b
+:not_supported:
+  - Not Supported
+  - >
+    Indicates that the LDAP client is attempting to use functionality that is not supported.
+    For example, the client identifies itself as an LDAPv2 client, and attempt to use functionality only available in LDAPv3.
+  - LDAP_NOT_SUPPORTED:0x5c
+:control_not_found:
+  - Control Not Found
+  - >
+    Indicates a requested LDAP control was not found.
+    This result code is set when the client parsing a server response for controls and not finding the requested controls
+  - LDAP_CONTROL_NOT_FOUND:0x5d
+:no_results_returned:
+  - No Results returned
+  - Indicates no results were returned from the server.
+  - LDAP_NO_RESULTS_RETURNED:0x5e
+:more_results:
+  - More Results To Return
+  - >
+    Indicates there are more results in the chain of results.
+    This result code is returned when additional result codes are available from the LDAP server.
+  - LDAP_MORE_RESULTS_TO_RETURN:0x5f
+:client_loop:
+  - Client Loop
+  - Indicates the LDAP client detected a loop, for example, when following referrals.
+  - LDAP_CLIENT_LOOP:0x60
+:referral_limit:
+  - Referral Limit Exceeded
+  - >
+    Indicates that the referral hop limit was exceeded.
+    This result code is if the client is referred to other servers more times than allowed by the referral hop limit.
+  - LDAP_REFERRAL_LIMIT_EXCEEDED:0x61
+

data/lib/dry/monitor/ldap/colorizers/default.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Dry
+  module Monitor
+    module LDAP
+      module Colorizers
+        class Default
+          def initialize(_theme); end
+
+          def call(string)
+            string
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dry/monitor/ldap/colorizers/rouge.rb

@@ -0,0 +1,31 @@
+require 'rouge/util'
+require 'rouge/token'
+require 'rouge/theme'
+require 'rouge/themes/gruvbox'
+require 'rouge/formatter'
+require 'rouge/formatters/terminal256'
+require 'rouge/lexer'
+require 'rouge/regex_lexer'
+require 'rouge/lexers/ldap'
+
+module Dry
+  module Monitor
+    module LDAP
+      module Colorizers
+        class Rouge
+          attr_reader :formatter
+          attr_reader :lexer
+
+          def initialize(theme)
+            @formatter = ::Rouge::Formatters::Terminal256.new(theme || ::Rouge::Themes::Gruvbox.new)
+            @lexer = ::Rouge::Lexers::LDAP.new
+          end
+
+          def call(string)
+            formatter.format(lexer.lex(string))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dry/monitor/ldap/logger.rb

@@ -0,0 +1,58 @@
+require 'dry-configurable'
+require 'dry/core/extensions'
+require 'dry/monitor/notifications'
+
+Dry::Monitor::Notifications.register_event(:ldap)
+
+module Dry
+  module Monitor
+    module LDAP
+      class Logger
+        extend Dry::Core::Extensions
+        extend Dry::Configurable
+
+        register_extension(:default_colorizer) do
+          require_relative './colorizers/default'
+
+          def colorizer
+            @colorizer ||= Colorizers::Default.new(config.theme)
+          end
+        end
+
+        register_extension(:rouge_colorizer) do
+          require_relative './colorizers/rouge'
+
+          def colorizer
+            @colorizer ||= Colorizers::Rouge.new(config.theme)
+          end
+        end
+
+        setting :theme, nil
+        setting :message_template, %(  Loaded %s in %sms %s).freeze
+
+        attr_reader :config
+        attr_reader :logger
+        attr_reader :template
+
+        load_extensions(:default_colorizer)
+        load_extensions(:rouge_colorizer)
+
+        def initialize(logger, config = self.class.config)
+          @logger = logger
+          @config = config
+          @template = config.message_template
+        end
+
+        def subscribe(notifications)
+          notifications.subscribe(:ldap) do |time:, name:, query:|
+            log_query(time, name, query)
+          end
+        end
+
+        def log_query(time, name, query)
+          logger.info template % [name.inspect, time, colorizer.call(query)]
+        end
+      end
+    end
+  end
+end