package io.prometheus.metrics.model.snapshots;

import io.prometheus.metrics.annotations.StableApi;
import io.prometheus.metrics.config.EscapingScheme;
import javax.annotation.Nullable;

/** Immutable container for metric metadata: name, help, unit. */
public final class MetricMetadata {

  /**
   * Name without suffix.
   *
   * <p>For example, the name for a counter "http_requests_total" is "http_requests". The name of an
   * info called "jvm_info" is "jvm".
   *
   * <p>We allow dots in label names. Dots are automatically replaced with underscores in Prometheus
   * exposition formats. However, if metrics from this library are exposed in OpenTelemetry format
   * dots are retained.
   *
   * <p>See {@link #MetricMetadata(String, String, Unit)} for more info on naming conventions.
   */
  private final String name;

  /**
   * Same as name that all invalid char (without Unicode support) are replaced by _
   *
   * <p>Multiple metrics with the same prometheusName are not allowed, because they would end up in
   * the same time series in Prometheus if {@link EscapingScheme#UNDERSCORE_ESCAPING} or {@link
   * EscapingScheme#DOTS_ESCAPING} is used.
   */
  private final String prometheusName;

  /**
   * The base name for exposition, with unit suffix ensured and type suffix preserved. For example,
   * for {@code Counter.builder().name("events_total").unit(BYTES)}, this is "events_total_bytes".
   * Used by format writers for smart-append logic (e.g. deciding whether to append _total).
   */
  private final String expositionBaseName;

  private final String expositionBasePrometheusName;

  /**
   * The original name as provided by the user, before any modification (no suffix stripping, no
   * unit appending). For example, for {@code Counter.builder().name("req").unit(BYTES)}, this is
   * "req". Used by the OTel exporter with {@code preserve_names=true}.
   */
  private final String originalName;

  @Nullable private final String help;
  @Nullable private final Unit unit;

  /** See {@link #MetricMetadata(String, String, Unit)} */
  @StableApi
  public MetricMetadata(String name) {
    this(name, null, null);
  }

  /** See {@link #MetricMetadata(String, String, Unit)} */
  @StableApi
  public MetricMetadata(String name, String help) {
    this(name, help, null);
  }

  /**
   * Constructor.
   *
   * @param name must not be {@code null}. {@link PrometheusNaming#isValidMetricName(String)
   *     isValidMetricName(name)} must be {@code true}. Use {@link
   *     PrometheusNaming#sanitizeMetricName(String)} to convert arbitrary strings into valid names.
   * @param help optional. May be {@code null}.
   * @param unit optional. May be {@code null}.
   */
  @StableApi
  public MetricMetadata(String name, @Nullable String help, @Nullable Unit unit) {
    this(name, name, help, unit);
  }

  /**
   * Creates a builder for {@link MetricMetadata}.
   *
   * <p>Use the builder instead of the multi-arg constructors for cleaner, more readable code:
   *
   * <pre>{@code
   * MetricMetadata.builder()
   *     .name("http_requests")
   *     .help("Total HTTP requests")
   *     .unit(Unit.BYTES)
   *     .counterSuffix(true)
   *     .build();
   * }</pre>
   */
  @StableApi
  public static Builder builder() {
    return new Builder();
  }

  /** Builder for {@link MetricMetadata}. */
  public static final class Builder {
    @Nullable private String name;
    @Nullable private String expositionBaseName;
    @Nullable private String originalName;
    @Nullable private String help;
    @Nullable private Unit unit;
    private boolean counterSuffix;

    private Builder() {}

    /** Required. The base metric name (without type suffix like {@code _total}). */
    @StableApi
    public Builder name(String name) {
      this.name = name;
      if (originalName == null) {
        this.originalName = name;
      }
      return this;
    }

    /**
     * Internal use only. Not part of the stable API.
     *
     * <p>Allows internal callers to preserve a separate exposition base name.
     */
    public Builder expositionBaseName(String expositionBaseName) {
      this.expositionBaseName = expositionBaseName;
      return this;
    }

    /**
     * Internal use only. Not part of the stable API.
     *
     * <p>Allows internal callers to preserve the raw name before normalization.
     */
    public Builder originalName(String originalName) {
      this.originalName = originalName;
      return this;
    }

    /** Optional. Human-readable description of the metric. */
    @StableApi
    public Builder help(@Nullable String help) {
      this.help = help;
      return this;
    }

    /** Optional. The unit of measurement. Appended to the name if not already present. */
    @StableApi
    public Builder unit(@Nullable Unit unit) {
      this.unit = unit;
      return this;
    }

    /**
     * Optional. When {@code true}, the writer appends {@code _total} to the exposition name. Use
     * this for counter metrics, especially UTF-8 names where the writer cannot infer it from the
     * snapshot type alone.
     */
    @StableApi
    public Builder counterSuffix(boolean counterSuffix) {
      this.counterSuffix = counterSuffix;
      return this;
    }

    /** Builds the {@link MetricMetadata}. Throws if {@code name} was not set. */
    @StableApi
    public MetricMetadata build() {
      if (name == null) {
        throw new IllegalArgumentException("name is required");
      }
      String baseName = appendUnitIfMissing(name, unit);
      String originalName = this.originalName == null ? name : this.originalName;
      String expositionBaseName =
          appendUnitIfMissing(
              this.expositionBaseName == null ? baseName : this.expositionBaseName, unit);
      if (counterSuffix
          && !expositionBaseName.endsWith("_total")
          && !expositionBaseName.endsWith(".total")) {
        expositionBaseName = expositionBaseName + "_total";
      }
      return new MetricMetadata(baseName, expositionBaseName, originalName, help, unit);
    }
  }

  /**
   * Constructor with exposition base name.
   *
   * @param name the base name (with type suffixes stripped, e.g. "events" for a counter named
   *     "events_total")
   * @param expositionBaseName the name with unit suffix ensured and type suffix preserved, used by
   *     format writers for smart-append logic
   * @param help optional. May be {@code null}.
   * @param unit optional. May be {@code null}.
   * @deprecated Use {@link #builder()} instead.
   */
  @StableApi
  @Deprecated
  public MetricMetadata(
      String name, String expositionBaseName, @Nullable String help, @Nullable Unit unit) {
    this(name, expositionBaseName, expositionBaseName, help, unit);
  }

  /**
   * Constructor with exposition base name and original name.
   *
   * @param name the base name (with type suffixes stripped, e.g. "events" for a counter named
   *     "events_total")
   * @param expositionBaseName the name with unit suffix ensured and type suffix preserved
   * @param originalName the raw name as provided by the user, before any modification
   * @param help optional. May be {@code null}.
   * @param unit optional. May be {@code null}.
   * @deprecated Use {@link #builder()} instead.
   */
  @StableApi
  @Deprecated
  public MetricMetadata(
      String name,
      String expositionBaseName,
      String originalName,
      @Nullable String help,
      @Nullable Unit unit) {
    this.name = name;
    this.expositionBaseName = expositionBaseName;
    this.originalName = originalName;
    this.help = help;
    this.unit = unit;
    validate();
    this.prometheusName = PrometheusNaming.prometheusName(name);
    this.expositionBasePrometheusName = PrometheusNaming.prometheusName(expositionBaseName);
  }

  /**
   * The name does not include the {@code _total} suffix for counter metrics or the {@code _info}
   * suffix for Info metrics.
   *
   * <p>The name may contain any Unicode chars. Use {@link #getPrometheusName()} to get the name in
   * legacy Prometheus format, i.e. with all dots and all invalid chars replaced by underscores.
   */
  @StableApi
  public String getName() {
    return name;
  }

  /**
   * Same as {@link #getName()} but with all invalid characters and dots replaced by underscores.
   *
   * <p>This is used by Prometheus exposition formats.
   */
  @StableApi
  public String getPrometheusName() {
    return prometheusName;
  }

  /**
   * The original name as provided by the user, before any modification. For example, if the user
   * called {@code Counter.builder().name("req").unit(BYTES)}, this returns "req" while {@link
   * #getName()} returns "req_bytes" and {@link #getExpositionBaseName()} returns "req_bytes".
   */
  @StableApi
  public String getOriginalName() {
    return originalName;
  }

  /**
   * The base name for exposition, with unit suffix ensured and type suffix preserved. For example,
   * if the user called {@code Counter.builder().name("events_total")}, this returns "events_total"
   * while {@link #getName()} returns "events".
   */
  @StableApi
  public String getExpositionBaseName() {
    return expositionBaseName;
  }

  /**
   * Same as {@link #getExpositionBaseName()} but with all invalid characters and dots replaced by
   * underscores.
   */
  @StableApi
  public String getExpositionBasePrometheusName() {
    return expositionBasePrometheusName;
  }

  @StableApi
  @Nullable
  public String getHelp() {
    return help;
  }

  @StableApi
  public boolean hasUnit() {
    return unit != null;
  }

  @StableApi
  @Nullable
  public Unit getUnit() {
    return unit;
  }

  private static String appendUnitIfMissing(String name, @Nullable Unit unit) {
    if (unit != null && !name.endsWith("_" + unit) && !name.endsWith("." + unit)) {
      return name + "_" + unit;
    }
    return name;
  }

  private void validate() {
    if (name == null) {
      throw new IllegalArgumentException("Missing required field: name is null");
    }
    String error = PrometheusNaming.validateMetricName(name);
    if (error != null) {
      throw new IllegalArgumentException(
          "'"
              + name
              + "': Illegal metric name. "
              + error
              + " Call "
              + PrometheusNaming.class.getSimpleName()
              + ".sanitizeMetricName(name) to avoid this error.");
    }
    if (hasUnit()) {
      if (!name.endsWith("_" + unit) && !name.endsWith("." + unit)) {
        throw new IllegalArgumentException(
            "'"
                + name
                + "': Illegal metric name. If the unit is non-null, "
                + "the name must end with the unit: _"
                + unit
                + "."
                + " Call "
                + PrometheusNaming.class.getSimpleName()
                + ".sanitizeMetricName(name, unit) to avoid this error.");
      }
    }
  }

  MetricMetadata escape(EscapingScheme escapingScheme) {
    return MetricMetadata.builder()
        .name(PrometheusNaming.escapeName(name, escapingScheme))
        .expositionBaseName(PrometheusNaming.escapeName(expositionBaseName, escapingScheme))
        .originalName(PrometheusNaming.escapeName(originalName, escapingScheme))
        .help(help)
        .unit(unit)
        .build();
  }
}