/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License, Version 1.0 only
 * (the "License").  You may not use this file except in compliance
 * with the License.
 *
 * You can obtain a copy of the license at
 * docs/licenses/cddl.txt
 * or http://www.opensource.org/licenses/cddl1.php.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at
 * docs/licenses/cddl.txt.  If applicable,
 * add the following below this CDDL HEADER, with the fields enclosed
 * by brackets "[]" replaced with your own identifying information:
 *      Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 *
 *
 *      Portions Copyright 2010-2024 Ping Identity Corporation
 */
package com.unboundid.directory.sdk.broker.api;

import com.unboundid.directory.sdk.broker.internal.BrokerExtension;
import com.unboundid.directory.sdk.broker.config.PolicyDecisionLoggerConfig;
import com.unboundid.directory.sdk.common.internal.ExampleUsageProvider;
import com.unboundid.directory.sdk.common.internal.Reconfigurable;
import com.unboundid.directory.sdk.common.internal.UnboundIDExtension;
import com.unboundid.directory.sdk.broker.types.PolicyMessageType;
import com.unboundid.directory.sdk.common.types.ServerContext;
import com.unboundid.ldap.sdk.LDAPException;
import com.unboundid.ldap.sdk.ResultCode;
import com.unboundid.util.Extensible;
import com.unboundid.util.ThreadSafety;
import com.unboundid.util.ThreadSafetyLevel;
import com.unboundid.util.args.ArgumentException;
import com.unboundid.util.args.ArgumentParser;

import java.util.Collections;
import java.util.List;
import java.util.Map;

/**
 * This class defines an API that must be implemented by extensions which
 * record information about PingAuthorize policy enforcement point
 * (PEP) and policy decision point (PDP) activity
 * <BR><BR>
 * Each policy decision logger may be configured to indicate whether to
 * include the PDP response or exclude log messages based on their Policy
 * Message Type.  This is handled automatically by the server, so individual
 * policy decision logger implementations do not need to attempt to perform that
 * filtering on their own.  However, they may perform additional processing
 * if desired to further narrow the set of messages that should be logged.
 * <BR>
 * <H2>Configuring Policy Decision Loggers</H2>
 * To configure a policy decision created using this API, use a command
 * like:
 * <PRE>
 *      dsconfig create-log-publisher \
 *           --publisher-name "<I>{logger-name}</I>" \
 *           --type third-party-policy-decision \
 *           --set enabled:true \
 *           --set "extension-class:<I>{class-name}</I>" \
 *           --set "extension-argument:<I>{name=value}</I>"
 * </PRE>
 * where "<I>{logger-name}</I>" is the name
 * to use for the policy decision logger
 * instance, "<I>{class-name}</I>" is the fully-qualified name of the Java class
 * that extends {@code com.unboundid.directory.sdk.common.api
 * .PolicyDecisionLogger},
 * and "<I>{name=value}</I>" represents name-value pairs for any arguments to
 * provide to the logger.  If multiple arguments should be provided to the
 * logger, then the "<CODE>--set extension-argument:<I>{name=value}</I></CODE>"
 * option should be provided multiple times.
 *
 * <p>See ExamplePolicyDecisionLogger for a basic implementation.</p>
 *
 * <p><strong>Tips:</strong></p>
 * <ul>
 *   <li>Ensure the custom logger handles both DECISION and ADVICE policy
 *   message types.</li>
 *   <li>Review the method-level documentation before implementing the log
 *   method. This documentation contains important information about the data
 *   being passed to the log method, including the contexts where such data
 *   is present.</li>
 * </ul>
 */
@Extensible()
@BrokerExtension()
@ThreadSafety(level= ThreadSafetyLevel.INTERFACE_THREADSAFE)
public abstract class PolicyDecisionLogger implements UnboundIDExtension,
        Reconfigurable<PolicyDecisionLoggerConfig>, ExampleUsageProvider {

    /**
     * Creates a new instance of this policy decision logger.
     * All policy decision logger implementations must include a default
     * constructor, but any initialization should generally be done in
     * the {@code initializePolicyDecisionLogger} method.
     */
    public PolicyDecisionLogger()
    {
        // No implementation is required.
    }

    /**
     * {@inheritDoc}
     */
    public void defineConfigArguments(final ArgumentParser parser)
            throws ArgumentException
    {
        // No arguments will be allowed by default.
    }

    /**
     * Initializes this policy decision logger.
     *
     * @param  serverContext  A handle to the server context for the server in
     *                        which this extension is running.
     * @param  config         The general configuration for
     *                        this policy decision logger.
     * @param  parser         The argument parser which
     *                        has been initialized from the configuration
     *                        for this policy decision logger.
     *
     * @throws LDAPException  If a problem occurs while initializing
     * this policy decision logger.
     */
    public void initializePolicyDecisionLogger(
            final ServerContext serverContext,
                                      final PolicyDecisionLoggerConfig config,
                                      final ArgumentParser parser)
            throws LDAPException
    {
        // No initialization will be performed by default.
    }

    /**
     * Performs any cleanup which may be necessary when this
     * policy decision logger is to be taken out of service.
     */
    public void finalizePolicyDecisionLogger()
    {
        // No implementation is required.
    }

    /**
     * Logs a message.
     *
     * @param messageType The {@link PolicyMessageType} indicates the stage
     *                    being logged in the decision processing lifecycle.
     *                    The provided message type can be either
     *                    {@link PolicyMessageType#ADVICE} or
     *                    {@link PolicyMessageType#DECISION}.
     * <p>
     * @param logContext  A set of key/value pairs summarizing and providing
     *                    context for the policy decision or advice.
     *                    <p>
     *                    <strong>Shared Keys:</strong> These keys are included
     *                    in the logContext for both DECISION and ADVICE message
     *                    types:
     *                    </p>
     * <table>
     * <caption>Shared Keys</caption>
     * <tr><td>{@code requestID}</td>
     * <td>The unique identifier for the request.</td></tr>
     * <tr><td>{@code correlationID}</td>
     * <td>The correlation identifier for tracking requests.</td></tr>
     * <tr><td>{@code product}</td>
     * <td>The product name generating the log
     *                    (e.g. Ping Identity PingAuthorize Server).</td></tr>
     * <tr><td>{@code instanceName}</td>
     * <td>The name of the server instance.</td></tr>
     * <tr><td>{@code clusterName}</td>
     * <td>The cluster name the instance belongs to.</td></tr>
     * <tr><td>{@code startupID}</td>
     * <td>A compact identifier that was assigned to the
     *                    server instance at startup.</td></tr>
     * <tr><td>{@code threadID}</td>
     * <td>The identifier for the thread handling the request.</td></tr>
     * <tr><td>{@code from}</td>
     * <td>The source IP address and port of the request.</td></tr>
     * <tr><td>{@code method}</td>
     * <td>The HTTP method used in the request.</td></tr>
     * <tr><td>{@code url}</td>
     * <td>The request URL. Note that the logged value might differ slightly
     *                    from the client-requested URL in minor ways.</td></tr>
     * <tr><td>{@code clientId}</td>
     * <td>The client ID. The logged value depends on the
     *                    Access Token Validator handling the request.</td></tr>
     * <tr><td>{@code tokenOwner}</td>
     * <td>The value depends on the Token Resource Lookup Method performed by a
     *                    handling Access Token Validator, and might not be
     *                    present if token owner lookup is skipped.</td>
     * <tr><td>{@code action}</td>
     * <td>The policy request action (e.g., "inbound-GET").</td></tr>
     * <tr><td>{@code service}</td>
     * <td>The service name provided in the decision request. This value will
     vary depending on whether the client request is a SCIM2, Gateway/Sideband,
     or a direct request to the policy decision engine
     (like a JSON PDP API request).</td></tr>
     * <tr><td>{@code resourcePath}</td>
     * <td>The path to the resource involved in the request.
     This value will vary depending on whether the client request is a SCIM2,
     Gateway/Sideband, or a direct request to the policy decision engine
     (like a JSON PDP API request).</td></tr>
     * <tr><td>{@code deploymentPackageId}</td>
     * <td>The unique identifier for the deployment package used
     *                    during policy evaluation.</td></tr>
     * <tr><td>{@code decisionId}</td>
     * <td>The unique identifier for the decision.</td></tr>
     * <tr><td>{@code authorized}</td>
     * <td>Indicates if the request was authorized (true or false).</td></tr>
     * <tr><td>{@code decisionStatusCode}</td>
     * <td>The policy decision status code. Commonly "OKAY", but values such as
     *                    "MISSING_ATTRIBUTE" in case of an error.</td></tr>
     * <tr><td>{@code decision}</td>
     * <td>The result of the decision (e.g., PERMIT, DENY).</td></tr>
     * </table>
     * <p>
     * <strong>DECISION Only Keys:</strong> These keys are included in the
     *                    logContext only for DECISION message types:
     * <table>
     * <caption>DECISION Only Keys</caption>
     * <tr><td>{@code snapshotId}</td>
     * <td>The ID of the policy snapshot.</td></tr>
     * <tr><td>{@code decisionNodeId}</td>
     * <td>The ID of the deployment package's root decision node.</td></tr>
     * <tr><td>{@code adviceIds}</td>
     * <td>A comma-separated list of advice identifiers included
     *                    in the decision response.</td></tr>
     * <tr><td>{@code adviceNames}</td>
     * <td>A comma-separated list of advice names included in the decision
     *                    response. These are the names that policy writers
     *                    used when constructing the policies.</td></tr>
     * <tr><td>{@code domain}</td>
     * <td>The decision request domain, if provided.</td></tr>
     * <tr><td>{@code identityProvider}</td>
     * <td>The identity provider included on the decision request. For client
     *                    requests triggering Access Token Validation
     *                    (e.g. Gateway, Sideband, etc.), this will be the
     *                    name of the used Access Token Validator.</td></tr>
     * </table>
     * <p>
     * <strong>ADVICE Only Keys:</strong>
     *                    These keys are included in the logContext only for
     *                    ADVICE message types:
     * <table>
     * <caption>ADVICE Only Keys</caption>
     * <tr><td>{@code adviceImplId}</td>
     * <td>The advice implementation ID, corresponding to an advice ID in the
     * configuration (e.g., "denied-reason").</td></tr>
     * <tr><td>{@code adviceImplName}</td>
     * <td>The advice implementation name, corresponding to an advice name in
     *                   the configuration (e.g., "Denied Reason Advice").
     *                   </td></tr>
     * <tr><td>{@code obligatory}</td>
     * <td>Indicates if the advice is obligatory (true or false).</td></tr>
     * <tr><td>{@code resourceModified}</td>
     * <td>Indicates whether the advice processing resulted in a modification
     *                    to the HTTP request (for inbound advice processing)
     *                    or the HTTP response (for outbound advice processing).
     *                    </td></tr>
     * </table>
     * <p>
     * @param message     The full response returned by the PDP in
     *                    JSON format, which is logged if the DECISION policy
     *                    message type is passed.
     *                    If the include-pdp-response property is disabled or
     *                    the message type does not record a decision response,
     *                    the PDP response is null.
     *
     * <p>
     *                    The PDP message object is always null when the
     *                    ADVICE policy message type is provided.
     * </p>
     */
    public abstract void log(
            final PolicyMessageType messageType,
            final Map<String, String> logContext,
            final String message);

    /**
     * {@inheritDoc}
     */
    public boolean isConfigurationAcceptable(
            final PolicyDecisionLoggerConfig config,
            final ArgumentParser parser,
            final List<String> unacceptableReasons)
    {
        // No extended validation will be performed by default.
        return true;
    }

    /**
     * {@inheritDoc}
     */
    public ResultCode applyConfiguration(
            final PolicyDecisionLoggerConfig config,
            final ArgumentParser parser,
            final List<String> adminActionsRequired,
            final List<String> messages)
    {
        // By default, no configuration changes will be applied.
        // If there are any arguments,
        // then add an admin action message indicating that the extension
        // needs to be restarted for any changes to take effect.
        if (! parser.getNamedArguments().isEmpty())
        {
            adminActionsRequired.add(
                    "No configuration change has actually been applied." +
                            " The new configuration will not take effect" +
                            " until this Policy Decision Logger is disabled" +
                            " and re-enabled or until the server" +
                            " is restarted.");
        }
        return ResultCode.SUCCESS;
    }

    /**
     * {@inheritDoc}
     */
    public abstract String getExtensionName();

    /**
     * {@inheritDoc}
     */
    public abstract String[] getExtensionDescription();

    /**
     * {@inheritDoc}
     */
    public Map<List<String>,String> getExamplesArgumentSets()
    {
        return Collections.emptyMap();
    }
}