package com.easyagents.agent.runtime.tool.operate;

import java.nio.file.Path;

/**
 * 业务侧可选的工作区配额校验 Hook。
 *
 * <p>Runtime 会先执行内置容量校验，再调用该 Hook。参数中的路径仅供受信任的服务端实现使用，
 * 不会进入 Tool Schema、metadata 或模型结果。
 */
public interface WorkspaceQuotaHook {

    /**
     * 在读取普通文件前执行附加校验。
     *
     * @param workspaceRoot 工作区根目录
     * @param target 目标普通文件
     * @param requestedBytes 预计读取字节数
     */
    void beforeRead(Path workspaceRoot, Path target, long requestedBytes);

    /**
     * 在提交文件变更前执行附加校验。
     *
     * @param workspaceRoot 工作区根目录
     * @param target 目标文件
     * @param previousBytes 原文件字节数，不存在时为零
     * @param resultingBytes 新文件字节数，删除时为零
     */
    void beforeWrite(Path workspaceRoot, Path target, long previousBytes, long resultingBytes);

    /**
     * 获取无操作 Hook。
     *
     * @return 无操作 Hook
     */
    static WorkspaceQuotaHook noop() {
        return NoopWorkspaceQuotaHook.INSTANCE;
    }

    /**
     * 无操作 Hook 实现。
     */
    final class NoopWorkspaceQuotaHook implements WorkspaceQuotaHook {

        private static final NoopWorkspaceQuotaHook INSTANCE = new NoopWorkspaceQuotaHook();

        private NoopWorkspaceQuotaHook() {
        }

        /**
         * 不执行附加读取校验。
         *
         * @param workspaceRoot 工作区根目录
         * @param target 目标普通文件
         * @param requestedBytes 预计读取字节数
         */
        @Override
        public void beforeRead(Path workspaceRoot, Path target, long requestedBytes) {
        }

        /**
         * 不执行附加写入校验。
         *
         * @param workspaceRoot 工作区根目录
         * @param target 目标文件
         * @param previousBytes 原文件字节数
         * @param resultingBytes 新文件字节数
         */
        @Override
        public void beforeWrite(Path workspaceRoot, Path target, long previousBytes, long resultingBytes) {
        }
    }
}
