package com.easyagents.federation.sql.api;

import com.easyagents.federation.sql.compile.FederationSqlPlan;
import com.easyagents.federation.sql.compile.SqlCompileRequest;
import com.easyagents.federation.sql.compile.SqlExplainRequest;
import com.easyagents.federation.sql.compile.SqlExplainResult;
import com.easyagents.federation.sql.execute.FederationResultCursor;
import com.easyagents.federation.sql.execute.QueryId;
import com.easyagents.federation.sql.source.FederationSourceManager;

/**
 * SQL 编译、补全、查询、Explain、取消和数据源管理的统一公共入口。
 */
public interface FederationSqlEngine extends AutoCloseable {

    /**
     * 返回数据源管理入口。
     *
     * @return 数据源管理器
     */
    FederationSourceManager sources();

    /**
     * 编译节点本地计划。
     *
     * @param request 编译请求
     * @return 节点本地计划
     */
    FederationSqlPlan compile(SqlCompileRequest request);

    /**
     * 执行节点本地计划。
     *
     * @param plan 编译计划
     * @param context 执行上下文
     * @return 流式游标
     */
    FederationResultCursor execute(FederationSqlPlan plan, SqlExecutionContext context);

    /**
     * 在当前节点完成编译或缓存命中并立即执行。
     *
     * @param command 可跨节点查询命令
     * @return 流式游标
     */
    FederationResultCursor query(SqlQueryCommand command);

    /**
     * 返回不含运行对象的 Explain 结果。
     *
     * @param request Explain 请求
     * @return Explain 结果
     */
    SqlExplainResult explain(SqlExplainRequest request);

    /**
     * 根据当前查询范围返回 Calcite SQL 上下文补全候选。
     *
     * @param request 补全请求
     * @return 替换区间与候选列表
     */
    SqlCompletionResult complete(SqlCompletionRequest request);

    /**
     * 尝试取消当前节点正在执行的查询。
     *
     * @param queryId 查询标识
     * @return 是否找到并发起取消
     */
    boolean cancel(QueryId queryId);

    /**
     * 返回节点本地 JDBC 终止与游标清理通道的累计指标。
     *
     * <p>自定义 Engine 未提供资源治理指标时返回空快照。</p>
     *
     * @return 清理通道指标
     */
    default FederationCleanupMetrics cleanupMetrics() {
        return FederationCleanupMetrics.empty();
    }

    /**
     * 关闭 Engine、订阅、Runtime 和独占句柄。
     */
    @Override
    void close();
}
