/*
 * 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.juneau.rest.client.classic.remote;

import java.util.*;
import java.util.concurrent.*;
import java.util.logging.*;

import org.apache.juneau.commons.svl.*;
import org.apache.juneau.http.remote.*;

/**
 * Shared helpers for the classic REST-proxy engine.
 *
 * <p>
 * The parse/apply logic here is ported from the next-generation engine
 * (<c>org.apache.juneau.rest.client.remote.RemoteClient</c> and <c>RrpcInterfaceMeta</c>) so that the classic
 * engine can honor the same {@link Remote @Remote}/{@link RemoteOp @RemoteOp}
 * members without introducing a cross-module dependency on freshly-installed common code.
 *
 * <h5 class='section'>See Also:</h5><ul>
 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestProxies">REST Proxies</a>
 * </ul>
 */
public class RemoteProxyUtils {

   private RemoteProxyUtils() {}

   private static final Logger LOG = Logger.getLogger("org.apache.juneau.rest.client.classic.remote");

   /** Interfaces already warned about an engine-specific member, to keep the build-time warning one-time. */
   private static final Set<String> WARNED = ConcurrentHashMap.newKeySet();

   /**
    * Parses an array of constant {@code "name<delim>value"} strings into resolved name/value entries.
    *
    * <p>
    * Ported from the next-generation engine's {@code RrpcInterfaceMeta.parseConstantParts(...)}.  Each entry is
    * resolved through {@link VarResolver#DEFAULT} (so values such as {@code "$S{sysprop}"} expand), then split on the
    * first occurrence of {@code delim} ({@code ':'} for the {@code "Name: value"} header form, {@code '='} for the
    * {@code "name=value"} query/form-data form).  Entries with no delimiter are skipped.  Both the name and the value
    * are trimmed.
    *
    * @param entries The raw annotation strings (may be empty).
    * @param delim The name/value delimiter character.
    * @return An unmodifiable list of resolved name/value entries. Never <jk>null</jk>, but may be empty.
    */
   public static List<Map.Entry<String,String>> parseConstantParts(String[] entries, char delim) {
      if (entries == null || entries.length == 0)
         return List.of();
      var l = new ArrayList<Map.Entry<String,String>>();
      for (var e : entries) {
         var s = VarResolver.DEFAULT.resolve(e);
         var i = s.indexOf(delim);
         if (i != -1)
            l.add(Map.entry(s.substring(0, i).trim(), s.substring(i + 1).trim()));
      }
      return Collections.unmodifiableList(l);
   }

   /**
    * Merges interface-level and method-level constant parts into a single name-keyed map, with method-level entries
    * overriding interface-level entries of the same name (declaration order preserved).
    *
    * <p>
    * Ported from the next-generation engine's {@code RemoteInvocationHandler.applyConstants(...)}.
    *
    * @param interfaceLevel Interface-level constants (applied first; lower precedence).
    * @param methodLevel Method-level constants (override interface-level entries of the same name).
    * @return An ordered, name-keyed map of merged constants. Never <jk>null</jk>, but may be empty.
    */
   public static Map<String,String> mergeConstants(List<Map.Entry<String,String>> interfaceLevel, List<Map.Entry<String,String>> methodLevel) {
      var merged = new LinkedHashMap<String,String>();
      for (var e : interfaceLevel)
         merged.put(e.getKey(), e.getValue());
      for (var e : methodLevel)
         merged.put(e.getKey(), e.getValue());
      return merged;
   }

   /**
    * Combines a base URL with a method path, avoiding double slashes.
    *
    * <p>
    * Ported verbatim from the next-generation engine's {@code RemoteInvocationHandler.combinePaths(...)}.
    *
    * @param base The base URL/path.
    * @param method The method path.
    * @return The combined path.
    */
   public static String combinePaths(String base, String method) {
      if (base.isEmpty())
         return method.isEmpty() ? "" : method;
      if (method.isEmpty())
         return base;
      if (base.endsWith("/") && method.startsWith("/"))
         return base + method.substring(1);
      if (! base.endsWith("/") && ! method.startsWith("/"))
         return base + "/" + method;
      return base + method;
   }

   /**
    * Enforces the SSRF guardrail with the default (deny-private) policy: delegates to
    * {@link #requireHttpScheme(String, boolean) requireHttpScheme(url, false)}.
    *
    * @param url The URL to validate.
    * @return The unchanged URL.
    * @throws IllegalArgumentException If {@code url} is absolute and violates the policy.
    */
   public static String requireHttpScheme(String url) {
      return requireHttpScheme(url, false);
   }

   /**
    * Enforces the SSRF guardrail: when {@code url} carries a URI scheme it must be {@code http} or {@code https}
    * with a nonempty host, and &mdash; unless {@code allowPrivateUrls} is set &mdash; must not target a
    * loopback/private/link-local/metadata host (see {@link RemoteUrlPolicy}).  Scheme-less (relative) values pass
    * through unchanged.
    *
    * <p>
    * Delegates to the shared {@link RemoteUrlPolicy#requireAllowedUrl(String, boolean)} used by both the classic and
    * next-generation engines, so the deny-list is defined exactly once.
    *
    * @param url The URL to validate.
    * @param allowPrivateUrls When <jk>true</jk>, the deny-private check is skipped (the http/https scheme
    *    requirement still applies).
    * @return The unchanged URL.
    * @throws IllegalArgumentException If {@code url} is absolute and violates the policy.
    */
   public static String requireHttpScheme(String url, boolean allowPrivateUrls) {
      return RemoteUrlPolicy.requireAllowedUrl(url, allowPrivateUrls);
   }

   /**
    * Same as {@link #requireHttpScheme(String, boolean)}, additionally honoring a client's per-client allowed address ranges.
    *
    * @param url The URL to validate.
    * @param allowPrivateUrls When <jk>true</jk>, the deny-private check is skipped.
    * @param allowedRanges The client's {@link org.apache.juneau.http.remote.RemoteUrlPolicy.AllowedRanges RemoteUrlPolicy.AllowedRanges}, unioned with the {@code RestClient.allowAddressRanges} property.
    * @return The unchanged URL.
    * @throws IllegalArgumentException If {@code url} is absolute and violates the policy.
    */
   public static String requireHttpScheme(String url, boolean allowPrivateUrls, RemoteUrlPolicy.AllowedRanges allowedRanges) {
      return RemoteUrlPolicy.requireAllowedUrl(url, allowPrivateUrls, allowedRanges);
   }

   /**
    * Emits a one-time build-time warning that an {@link Remote @Remote}/{@link RemoteOp @RemoteOp}
    * member is set on the classic engine that the classic engine cannot honor.
    *
    * <p>
    * De-duplicated per interface-class + member name so it fires at most once for a given proxy interface.
    *
    * @param interfaceClass The proxy interface the member was declared on.
    * @param member The unsupported member name (e.g. <js>"interceptors"</js>).
    * @param detail A short explanation of why the member is not honored.
    */
   public static void warnUnsupportedMember(Class<?> interfaceClass, String member, String detail) {
      var key = interfaceClass.getName() + "#" + member;
      if (WARNED.add(key))
         LOG.warning(() -> "@Remote/@RemoteOp member '" + member + "' set on " + interfaceClass.getName()
            + " is not honored by the classic REST-proxy engine: " + detail
            + "  Use the next-generation engine (RestClient.remote(...)) for this feature.");
   }
}