::nsmcp::Object ::nsmcp::Object dict getdef ::nx::Object ::nx::Object ::nsmcp::Object->::nx::Object ::nsmcp::AccessRecordStoreSQLite ::nsmcp::AccessRecordStoreSQLite allScope available batchInsertionAvailable boundaryPending cRead capacity checkpointCounts close coveredBytes coveredEnd descriptors destroy diagnostic disconnect diskBytes dropState filters finish gapEnd ingest init initialize legacyViews observeBatch overview pageLimit prepare prune pruneAge retentionFloor rollBatch rollupBackfill rollupSource samples scope session stateGet statePut stats totals tuple ::nsmcp::AccessRecordStoreSQLite->::nsmcp::Object

Class ::nsmcp::AccessRecordStoreSQLite

::nsmcp::AccessRecordStoreSQLite[i] create ... \
           [ -attached (default "false") ] \
           [ -batchSchema (default "") ] \
           [ -db (default "") ] \
           [ -fullScope (default "false") ] \
           [ -handle (default "") ] \
           [ -lastCompleted (default "0") ] \
           [ -lastStamp (default "") ] \
           [ -mode (default "writer") ] \
           [ -observer (default "") ] \
           [ -path path ] \
           [ -peers (default "") ] \
           [ -prior (default "") ] \
           [ -querying (default "false") ] \
           [ -settings:required settings:required ]
Defined in /usr/local/ns/tcl/nsmcp/log-traffic-record-store.tcl

Class Relations

  • class: ::nx::Class[i]
  • superclass: ::nsmcp::Object[i]

Methods (to be applied on instances)

  • allScope (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> allScope

    Open a query scope covering every active stored generation. Create the source-scope table and retained-record view in a read transaction. This enables complete-generation rollup queries; call finish after querying.

    Returns:
    An empty result after the all-generation scope is ready.

    Testcases:
    No testcase defined.

  • available (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> available

    Report whether this adapter owns a database session. This checks the current object state; it does not obtain another pool handle or perform a database health query.

    Returns:
    True when a session is available, otherwise false.

    Testcases:
    No testcase defined.

  • batchInsertionAvailable (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> batchInsertionAvailable

    Report use of the prepared-row batch insertion API. Current deployments require this API. Tests may override this method to select the SQL reference implementation for comparison.

    Returns:
    True for the required production insertion path.

    Testcases:
    No testcase defined.

  • cRead (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> cRead fid file \
    offset stop budget limits redactor ingestOnly [ batched ]

    Read a bounded source slice through the C access-log scanner. Use a connection-local temporary table to materialize raw scanner fields, then cook and redact valid requests. Raw fields are never written to the canonical store. Leave an incomplete tail uncommitted.

    Parameters:
    fid (required)
    Stored source-file identifier.
    file (required)
    Discovered source descriptor.
    offset (required)
    Starting source byte offset.
    stop (required)
    Planned exclusive source boundary.
    budget (required)
    Maximum source bytes to scan in this invocation.
    limits (required)
    Scanner limits, including the maximum line size.
    redactor (required)
    Redaction object used when cooking requests.
    ingestOnly (required)
    True for ingestion; false allows time-dependent records to request the Tcl scanner fallback.
    batched (optional, defaults to "false")
    True to construct prepared rows; false to construct SQL reference tuples.
    Returns:
    A list of end offset, cooked tuples, pending flag, fallback flag and parsing-loss counts.

    Testcases:
    No testcase defined.

  • capacity (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> capacity

    Report the configured record-store budget and current allocation. Account for the main database and its journal files separately. Writer instances also publish a timestamped capacity snapshot for the status interface.

    Returns:
    A dictionary containing byte budgets, allocation, disk usage and the limit-exceeded flag.

    Testcases:
    No testcase defined.

  • close (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> close

    Destroy this adapter and release its database resources. Roll back any unfinished query or transaction, remove temporary state, detach the record store and restore the connection settings before returning its handle to the pool.

    Returns:
    No result; the adapter object is destroyed.

    Testcases:
    No testcase defined.

  • coveredBytes (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> coveredBytes fid lo \
    hi

    Count committed bytes overlapping a source interval. Intersect the interval with persisted coverage ranges. This is stored coverage, not a measurement of current source-file contents.

    Parameters:
    fid (required)
    Stored source-file identifier.
    lo (required)
    Inclusive lower byte boundary.
    hi (required)
    Exclusive upper byte boundary.
    Returns:
    The number of covered bytes in the interval.

    Testcases:
    No testcase defined.

  • coveredEnd (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> coveredEnd fid \
    offset end

    Find the end of the committed range containing an offset. Use persisted byte coverage rather than reading the source file. Clamp the result to the caller's planned scan boundary.

    Parameters:
    fid (required)
    Stored source-file identifier.
    offset (required)
    Starting byte offset to test.
    end (required)
    Upper byte boundary for this scan.
    Returns:
    The covered end offset, or offset itself when no range covers it.

    Testcases:
    No testcase defined.

  • descriptors (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> descriptors

    Describe the active generations present in the record store. Derive live and rotated-source descriptors from persisted state without discovering or opening source files.

    Returns:
    A list of active stored-source descriptors and their committed byte boundaries.

    Testcases:
    No testcase defined.

  • diagnostic (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> diagnostic message \
    opts

    Classify and log a record-store failure. Use the shared aggregation diagnostic path so callers receive a bounded classification and diagnostic identifier rather than exposing the underlying error details.

    Parameters:
    message (required)
    Original error message.
    opts (required)
    Tcl return-options dictionary for the failure.
    Returns:
    The shared diagnostic dictionary for the record-store error.

    Testcases:
    No testcase defined.

  • diskBytes (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> diskBytes

    Measure the disk space occupied by the record-store files. Include the database, rollback journal, WAL and shared-memory file when present. SQLite temporary files and unrelated files are excluded.

    Returns:
    The total size in bytes of the existing store files.

    Testcases:
    No testcase defined.

  • dropState (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> dropState fid \
    offset

    Check whether an offset follows a committed dropped section. Consult the source generation's persisted dropping flag and high watermark. This allows the scanner to carry its framing state across ingestion slices.

    Parameters:
    fid (required)
    Stored source-file identifier.
    offset (required)
    Byte offset at which scanning will resume.
    Returns:
    True when the generation is dropping at or before this offset, otherwise false.

    Testcases:
    No testcase defined.

  • finish (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> finish

    Finish the current scoped read transaction. Commit the transaction and clear the object's query-active flag. The adapter continues to own its session until it is closed.

    Returns:
    False after the query-active flag has been cleared.

    Testcases:
    No testcase defined.

  • gapEnd (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> gapEnd fid offset \
    end

    Find the next committed range after an uncovered offset. Bound scanning to the next stored range or the planned source end, whichever comes first.

    Parameters:
    fid (required)
    Stored source-file identifier.
    offset (required)
    Uncovered byte offset.
    end (required)
    Upper byte boundary for this scan.
    Returns:
    The end offset of the uncovered interval.

    Testcases:
    No testcase defined.

  • ingest (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> ingest fid \
    checkpoint tuples [ batched ]

    Persist the scanner's supplied requests and checkpoint atomically. Insert every supplied request; duplicate source positions are errors. Commit rollups, pending peer addresses, parsing-loss counters and byte coverage in the same transaction. This method does not read the source file.

    Parameters:
    fid (required)
    Stored source-file identifier.
    checkpoint (required)
    Scanner-prepared coverage, framing, timestamp and parsing-loss metadata.
    tuples (required)
    Prepared request rows, or serialized SQL tuples for the reference path.
    batched (optional, defaults to "false")
    True for the batch API; false for the SQL reference implementation.
    Returns:
    Committed request and diagnostic counts, together with the insertion-backend label.

    Testcases:
    No testcase defined.

  • legacyViews (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> legacyViews

    Create connection-local views for the access-analytics interface. Expose canonical requests, control metadata and evictions through the legacy view names. Enforce request and peer retention without duplicating stored records.

    Returns:
    An empty result after the temporary views have been created.

    Testcases:
    No testcase defined.

  • observeBatch (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> observeBatch \
    [ batchSource ]

    Update observation metadata from an inserted or migrated batch. Merge first and latest request times, completion time and parsing-loss counts into persistent state. The caller supplies the surrounding transaction.

    Parameters:
    batchSource (optional, defaults to "temp.nsmcp_ingest_batch")
    Trusted SQL relation containing the batch; defaults to the migration staging table.
    Returns:
    An empty result after the observation state has been saved.

    Testcases:
    No testcase defined.

  • overview (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> overview

    Report persisted ingestion progress and current store status. Combine the continuous cursor, observation times, parsing-loss totals, retention floor and capacity. Missing history metadata remains pending rather than implying complete coverage.

    Returns:
    An overview dictionary containing coverage, lag, storage, writer and retention status.

    Testcases:
    No testcase defined.

  • prepare (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> prepare file

    Resolve or initialize the stored generation for a discovered log file. Validate the source prefix and committed-range anchors before reusing a generation. Writers retire or replace changed generations; readers only accept an existing active generation.

    Parameters:
    file (required)
    Discovered source descriptor, including path, identity, size and modification time.
    Returns:
    The stored file identifier, or -1 when a reader cannot use the generation.

    Testcases:
    No testcase defined.

  • prune (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> prune [ batchRows ]

    Apply the configured retention policy to a writable store. Unified stores remove bounded batches of expired records and related metadata. Other stores expire whole source generations so retained coverage cannot certify deleted requests.

    Parameters:
    batchRows (optional, defaults to "10000")
    Maximum rows per unified-retention deletion, from 1 through 10000.
    Returns:
    Deletion counts for unified retention, or an empty result for generation retention.

    Testcases:
    No testcase defined.

  • rollupBackfill (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> rollupBackfill \
    [ batches ]

    Build missing minute rollups for previously stored requests. Process bounded batches in source order. Commit rollups, observations, rolled flags and the migration cursor atomically for each batch.

    Parameters:
    batches (optional, defaults to "1")
    Maximum number of migration batches to process in this invocation.
    Returns:
    True when no unrolled rows remain; false when the batch budget was exhausted.

    Testcases:
    No testcase defined.

  • samples (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> samples selected \
    files redactor

    Build deterministic samples from selected and successful requests. Restrict output to known source descriptors and apply the supplied redactor. Preserve truncation metadata when a stored user-agent label was clipped.

    Parameters:
    selected (required)
    Trusted SQL predicate produced by the query-filter builder.
    files (required)
    Source descriptors used to attach sample locations.
    redactor (required)
    Redaction object used for sample output.
    Returns:
    A list of selected-request sample entries and successful-request sample entries.

    Testcases:
    No testcase defined.

  • scope (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> scope files

    Open a stored-record query scope for selected source intervals. Create connection-local range metadata and a bounded request view inside a read transaction. Reject a generation that disappeared after discovery. Call finish to end the scope.

    Parameters:
    files (required)
    Source descriptors containing archive file identifiers and byte bounds.
    Returns:
    An empty result after the scoped transaction and view are ready.

    Testcases:
    No testcase defined.

  • session (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> session

    Return the database session owned by this adapter. Use the session for operations within the adapter's lifetime. The adapter retains responsibility for closing it and releasing the pool handle.

    Returns:
    The DatabaseSession object, or an empty value when no session is available.

    Testcases:
    No testcase defined.

  • stateGet (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> stateGet key \
    [ default ]

    Read a named control-state value. Return the stored Tcl representation without interpreting its contents. Use the supplied default when the key is absent.

    Parameters:
    key (required)
    Control-state key.
    default (optional)
    Value to return when the key does not exist.
    Returns:
    The stored state value or the supplied default.

    Testcases:
    No testcase defined.

  • statePut (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> statePut key value

    Save a named control-state value. Replace the existing value using scalar binding. The caller controls transaction boundaries when this state accompanies record or coverage changes.

    Parameters:
    key (required)
    Control-state key.
    value (required)
    Tcl value to serialize into the state table.
    Returns:
    An empty result after the value has been saved.

    Testcases:
    No testcase defined.

  • stats (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> stats options \
    redactor limits

    Aggregate request statistics for the current stored-record scope. Combine detailed request rows with eligible minute rollups. Bound ranked dimensions, redact returned labels and report omitted or unavailable observations explicitly.

    Parameters:
    options (required)
    Normalized time window, filters, bucket size and result limits.
    redactor (required)
    Redaction object for returned dimension labels.
    limits (required)
    Aggregation limits, including the maximum number of retained keys.
    Returns:
    A list containing request statistics, aggregation metadata and the selected SQL predicate.

    Testcases:
    No testcase defined.

  • totals (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> totals options

    Return stored request totals for the current query scope. Use minute rollups when the scope and filters permit, retaining detailed boundary rows. Otherwise aggregate the scoped records and checkpoint diagnostic counters directly.

    Parameters:
    options (required)
    Normalized time window and request filters.
    Returns:
    A list containing the counts dictionary, selected status counts and coverage diagnostics.

    Testcases:
    No testcase defined.

  • tuple (scripted, public)

     <instance of nsmcp::AccessRecordStoreSQLite[i]> tuple fid off stop \
    kind row redactor file [ batched ]

    Construct one policy-processed record from a valid parsed request. Redact display fields and encode the canonical row representation. Cache completion-time parsing and retain eligible peer-address observations for the enclosing ingestion transaction; do not insert a row here.

    Parameters:
    fid (required)
    Stored source-file identifier.
    off (required)
    Starting source byte offset.
    stop (required)
    Exclusive byte offset after the record.
    kind (required)
    Record kind; only valid requests (zero) are accepted.
    row (required)
    Parsed request dictionary.
    redactor (required)
    Redaction object for display fields.
    file (required)
    Source descriptor used to derive the stable sample identifier.
    batched (optional, defaults to "false")
    True to return a prepared row; false to return a quoted SQL tuple.
    Returns:
    The cooked request as a Tcl row list or serialized SQL tuple.

    Testcases:
    No testcase defined.