/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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.
 */

package org.apache.paimon.rest.auth;

import javax.annotation.Nullable;

import java.time.Instant;
import java.util.Map;

/**
 * Interface for DLF request signers. Different signers implement different signature algorithms
 * (e.g., DLF4-HMAC-SHA256, ROA v2 HMAC-SHA1).
 */
public interface DLFRequestSigner {

    /**
     * Generate signature headers for the request.
     *
     * @param body request body (can be null for GET requests)
     * @param now current timestamp
     * @param securityToken security token (can be null)
     * @param host request host
     * @return map of signature-related headers
     */
    Map<String, String> signHeaders(
            @Nullable String body, Instant now, @Nullable String securityToken, String host);

    /**
     * Generate the Authorization header value.
     *
     * @param restAuthParameter request parameters (method, path, query, body)
     * @param token DLF token (access key id, secret, security token)
     * @param host request host
     * @param signHeaders headers generated by {@link #signHeaders}
     * @return Authorization header value
     */
    String authorization(
            RESTAuthParameter restAuthParameter,
            DLFToken token,
            String host,
            Map<String, String> signHeaders)
            throws Exception;

    /**
     * Get the identifier for this signer (e.g., "default", "openapi").
     *
     * @return signer identifier
     */
    String identifier();
}
