// SPDX-License-Identifier: MIT
pragma solidity >=0.8.10 <0.9.0;

import {TablelandPolicy} from "../TablelandPolicy.sol";

/**
 * @dev Interface of a TablelandTables compliant contract.
 */
interface ITablelandTables {
    /**
     * The caller is not authorized.
     */
    error Unauthorized();

    /**
     * RunSQL was called with a query length greater than maximum allowed.
     */
    error MaxQuerySizeExceeded(uint256 querySize, uint256 maxQuerySize);

    /**
     * @dev Emitted when `owner` creates a new table.
     *
     * owner - the to-be owner of the table
     * tableId - the table id of the new table
     * statement - the SQL statement used to create the table
     */
    event CreateTable(address owner, uint256 tableId, string statement);

    /**
     * @dev Emitted when a table is transferred from `from` to `to`.
     *
     * Not emmitted when a table is created.
     * Also emitted after a table has been burned.
     *
     * from - the address that transfered the table
     * to - the address that received the table
     * tableId - the table id that was transferred
     */
    event TransferTable(address from, address to, uint256 tableId);

    /**
     * @dev Emitted when `caller` runs a SQL statement.
     *
     * caller - the address that is running the SQL statement
     * isOwner - whether or not the caller is the table owner
     * tableId - the id of the target table
     * statement - the SQL statement to run
     * policy - an object describing how `caller` can interact with the table (see {TablelandPolicy})
     */
    event RunSQL(
        address caller,
        bool isOwner,
        uint256 tableId,
        string statement,
        TablelandPolicy policy
    );

    /**
     * @dev Emitted when a table's controller is set.
     *
     * tableId - the id of the target table
     * controller - the address of the controller (EOA or contract)
     */
    event SetController(uint256 tableId, address controller);

    /**
     * @dev Struct containing parameters needed to run a mutating sql statement
     *
     * tableId - the id of the target table
     * statement - the SQL statement to run
     *           - the statement type can be any of INSERT, UPDATE, DELETE, GRANT, REVOKE
     *
     */
    struct Statement {
        uint256 tableId;
        string statement;
    }

    /**
     * @dev Creates a new table owned by `owner` using `statement` and returns its `tableId`.
     *
     * owner - the to-be owner of the new table
     * statement - the SQL statement used to create the table
     *           - the statement type must be CREATE
     *
     * Requirements:
     *
     * - contract must be unpaused
     */
    function create(
        address owner,
        string memory statement
    ) external payable returns (uint256);

    /**
     * @dev Creates multiple new tables owned by `owner` using `statements` and returns array of `tableId`s.
     *
     * owner - the to-be owner of the new table
     * statements - the SQL statements used to create the tables
     *            - each statement type must be CREATE
     *
     * Requirements:
     *
     * - contract must be unpaused
     */
    function create(
        address owner,
        string[] calldata statements
    ) external payable returns (uint256[] memory);

    /**
     * @dev Runs a mutating SQL statement for `caller` using `statement`.
     *
     * caller - the address that is running the SQL statement
     * tableId - the id of the target table
     * statement - the SQL statement to run
     *           - the statement type can be any of INSERT, UPDATE, DELETE, GRANT, REVOKE
     *
     * Requirements:
     *
     * - contract must be unpaused
     * - `msg.sender` must be `caller`
     * - `tableId` must exist and be the table being mutated
     * - `caller` must be authorized by the table controller
     * - `statement` must be less than or equal to 35000 bytes
     */
    function mutate(
        address caller,
        uint256 tableId,
        string calldata statement
    ) external payable;

    /**
     * @dev Runs an array of mutating SQL statements for `caller`
     *
     * caller - the address that is running the SQL statement
     * statements - an array of structs containing the id of the target table and coresponding statement
     *            - the statement type can be any of INSERT, UPDATE, DELETE, GRANT, REVOKE
     *
     * Requirements:
     *
     * - contract must be unpaused
     * - `msg.sender` must be `caller`
     * - `tableId` must be the table being muated in each struct's statement
     * - `caller` must be authorized by the table controller if the statement is mutating
     * - each struct inside `statements` must have a `tableId` that corresponds to table being mutated
     * - each struct inside `statements` must have a `statement` that is less than or equal to 35000 bytes after normalization
     */
    function mutate(
        address caller,
        ITablelandTables.Statement[] calldata statements
    ) external payable;

    /**
     * @dev Sets the controller for a table. Controller can be an EOA or contract address.
     *
     * When a table is created, it's controller is set to the zero address, which means that the
     * contract will not enforce write access control. In this situation, validators will not accept
     * transactions from non-owners unless explicitly granted access with "GRANT" SQL statements.
     *
     * When a controller address is set for a table, validators assume write access control is
     * handled at the contract level, and will accept all transactions.
     *
     * You can unset a controller address for a table by setting it back to the zero address.
     * This will cause validators to revert back to honoring owner and GRANT/REVOKE based write access control.
     *
     * caller - the address that is setting the controller
     * tableId - the id of the target table
     * controller - the address of the controller (EOA or contract)
     *
     * Requirements:
     *
     * - contract must be unpaused
     * - `msg.sender` must be `caller` and owner of `tableId`
     * - `tableId` must exist
     * - `tableId` controller must not be locked
     */
    function setController(
        address caller,
        uint256 tableId,
        address controller
    ) external;

    /**
     * @dev Returns the controller for a table.
     *
     * tableId - the id of the target table
     */
    function getController(uint256 tableId) external returns (address);

    /**
     * @dev Locks the controller for a table _forever_. Controller can be an EOA or contract address.
     *
     * Although not very useful, it is possible to lock a table controller that is set to the zero address.
     *
     * caller - the address that is locking the controller
     * tableId - the id of the target table
     *
     * Requirements:
     *
     * - contract must be unpaused
     * - `msg.sender` must be `caller` and owner of `tableId`
     * - `tableId` must exist
     * - `tableId` controller must not be locked
     */
    function lockController(address caller, uint256 tableId) external;

    /**
     * @dev Sets the contract base URI.
     *
     * baseURI - the new base URI
     *
     * Requirements:
     *
     * - `msg.sender` must be contract owner
     */
    function setBaseURI(string memory baseURI) external;

    /**
     * @dev Pauses the contract.
     *
     * Requirements:
     *
     * - `msg.sender` must be contract owner
     * - contract must be unpaused
     */
    function pause() external;

    /**
     * @dev Unpauses the contract.
     *
     * Requirements:
     *
     * - `msg.sender` must be contract owner
     * - contract must be paused
     */
    function unpause() external;
}