path: root/include/CursorManager.h

#pragma once

#include "Api.h"
#include "HandlerManager.h"
#include "IStorageBackend.h"
#include "LifecycleManager.h"
#include "ObjectManager.h"
#include "Types.h"

#include <cstddef>
#include <string>
#include <vector>

/**
 * @file CursorManager.h
 * @brief Declares paging and cursor orchestration for query execution.
 */

namespace nt
{
    /**
     * @class CursorManager
     * @brief Orchestrates paginated data retrieval from a storage backend.
     *
     * CursorManager depends only on IStorageBackend. The concrete backend
     * (SqliteBackend, InMemoryBackend, …) is injected at construction time.
     *
     * Tuples are never loaded all at once. Open() fetches the first page;
     * each subsequent Next() call transparently fetches the next page from
     * the backend once the current page is exhausted.
     *
     * Pagination is driven by the Merkle B-tree: each cursor carries the hex
     * hash of the relation's Merkle root at open time, and LoadPage calls
     * Merkle::Page(backend, merkle_root, fetch_offset, PAGE_SIZE) to retrieve
     * the next page of tuple hashes without loading sibling subtrees.
     */
    class CursorManager
    {
    public:
        static constexpr std::size_t PAGE_SIZE = 1;

        /**
         * @brief Constructs a CursorManager.
         *
         * The @p lifecycles and @p objects references are optional: when
         * left null the cursor performs no snapshot pinning (this matches the
         * test fixtures, which register relations at synthetic paths with no
         * /system/snapshots ancestor). When both are provided, Open finds the
         * resolved snapshot for the handle's relation and Pins it for the
         * cursor's lifetime, releasing the pin in Close.
         */
        explicit CursorManager(IStorageBackend& backend,
                               LifecycleManager* lifecycles = nullptr,
                               ObjectManager* objects = nullptr);

        /**
         * @brief Active scan state for a single relation.
         *
         * Holds one page of deserialized tuples at a time. When page_position
         * reaches the end of the page, Next() discards the page and fetches
         * the next one from the backend.
         *
         * The pointer returned by Next() is valid only until the next Next()
         * or Close() call — a page replacement invalidates all prior pointers.
         *
         * merkle_root is seeded from ObjectManager::Relation::merkle_root at
         * open time and does not change during iteration; the cursor reads the
         * snapshot captured when it was opened.
         *
         * Notably the cursor does NOT keep a pointer to the HandlerManager
         * handle it was opened from. Everything Next() needs — the relation
         * type, the merkle_root, and the ephemeral generator function — is
         * captured at Open time, so closing the handle before the cursor is
         * exhausted is safe (the API contract still says to close the cursor
         * first, but a violation no longer dereferences a freed handle).
         */
        struct cursor {
            /**
             * Hex hash of the relation's Merkle B-tree root node.
             * Empty string means the relation contains no tuples.
             */
            std::string merkle_root;
            /**
             * Bound argument values for EPHEMERAL_RELATION cursors.
             * Written by the JOIN operator before each probe; ignored for
             * stored RELATION cursors.
             */
            std::vector<std::string> args;
            std::vector<Tuple> page;
            std::size_t page_position = 0;
            std::size_t fetch_offset  = 0;   // next Merkle::Page() call starts here
            bool exhausted = false;
            /**
             * True for EPHEMERAL_RELATION cursors; selects the generator-driven
             * page fetch path instead of Merkle B-tree paging.
             */
            bool is_ephemeral = false;
            /**
             * Generator function for ephemeral cursors. Copied from the
             * ephemeral_object_type at Open time, so the cursor remains valid
             * even if the source registry entry is later torn down (the
             * snapshot pin held in pinned_snapshot prevents that today, but
             * the copy makes the cursor independent regardless).
             */
            ObjectManager::ephemeral_object_type::Generator generator;
            /**
             * Borrowed pointer to the snapshot the cursor is pinning.
             * Non-null only when a /system/snapshots/<H>/<n>
             * ancestor was found at Open time and LifecycleManager was
             * available. Close unpins it.
             */
            ObjectManager::registry* pinned_snapshot = nullptr;
        };

        /**
         * @brief Opens a cursor on the relation referenced by the handle.
         *
         * Fetches the first page immediately for non-empty relations. Returns
         * a valid exhausted cursor when @p merkle_root is empty (empty relation).
         * Returns nullptr when the handle does not refer to a RELATION or
         * EPHEMERAL_RELATION.
         *
         * @param handle       Open RELATION or EPHEMERAL_RELATION handle.
         * @param merkle_root  Hex hash of the relation's Merkle root at open
         *                     time. Ignored for EPHEMERAL_RELATION handles.
         */
        cursor* Open(HandlerManager::handle* handle,
                     const std::string& merkle_root = "");

        /**
         * @brief Pulls the next tuple from the cursor.
         *
         * Fetches the next page from the backend transparently when the
         * current page is exhausted. Returns nullptr when all pages are done.
         */
        Tuple* Next(cursor* cursor);

        /**
         * @brief Closes the cursor and releases its resources.
         * @param cursor Cursor to close.
         */
        void Close(cursor* cursor);

    private:
        IStorageBackend&  backend_;
        LifecycleManager* lifecycles_ = nullptr;
        ObjectManager*    objects_    = nullptr;

        /**
         * Fetches a page of hashes via Merkle::Page, resolves each from the
         * KV store, and deserializes them into cursor->page. Clears the
         * existing page.  Advances fetch_offset by the number of hashes
         * returned; sets exhausted when fewer than PAGE_SIZE hashes come back.
         */
        void LoadPage(cursor* c);
    };
}