package com.cameleer.server.core.storage;

import com.cameleer.server.core.storage.model.ServerInstanceInfo;
import com.cameleer.server.core.storage.model.ServerMetricCatalogEntry;
import com.cameleer.server.core.storage.model.ServerMetricQueryRequest;
import com.cameleer.server.core.storage.model.ServerMetricQueryResponse;

import java.time.Instant;
import java.util.List;

/**
 * Read-side access to the ClickHouse {@code server_metrics} table. Exposed
 * to dashboards through {@code /api/v1/admin/server-metrics/**} so SaaS
 * control planes don't need direct ClickHouse access.
 */
public interface ServerMetricsQueryStore {

    /**
     * Catalog of metric names observed in {@code [from, to)} along with their
     * type, the set of statistics emitted, and the union of tag keys seen.
     */
    List<ServerMetricCatalogEntry> catalog(Instant from, Instant to);

    /**
     * Distinct {@code server_instance_id} values that wrote at least one
     * sample in {@code [from, to)}, with first/last seen timestamps.
     */
    List<ServerInstanceInfo> listInstances(Instant from, Instant to);

    /**
     * Generic time-series query. See {@link ServerMetricQueryRequest} for
     * request semantics. Implementations must enforce input validation and
     * reject unsafe inputs with {@link IllegalArgumentException}.
     */
    ServerMetricQueryResponse query(ServerMetricQueryRequest request);
}
