Class DataQueryClient

java.lang.Object
ai.badmonkey.agentspaces.connect.DataQueryClient
public final class DataQueryClient extends Object
The agent side of aspace:cap/data-query (ENTERPRISE §3): fetch data by asset name and parameters, local-first. A live result under the same canonical hash answers immediately and costs the source system nothing; otherwise the client writes a query entry and awaits the connector's result. The counters make the economics observable: cacheHits is money the abstraction returned.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    DataQueryClient.Fetched
    One fetch's answer.

  • Constructor Summary

    Constructors
    Constructor
    Description
    DataQueryClient(Space dataSpace, String requester)
    Creates a client that accepts a result from any admitted peer.
    DataQueryClient(Space dataSpace, String requester, Authorizer authorizer)
    Creates a client whose trust in a result is the fleet's Authorizer (TODO-EFG §4, TODO item 6): a DataResult counts — for the cache check and for the awaited answer — only when its space-authenticated issuer's peer is permitted CONNECTOR_SERVE for result.asset().
    DataQueryClient(Space dataSpace, String requester, Set<PeerId> trustedConnectors)
    Creates a client that consumes only results written by the named connector peers (ASF-009): a result forged by any other admitted peer is ignored, for both the cache check and the awaited answer.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    cacheHits()
    Fetches answered by a live space result, with no source execution.
    Optional<DataQueryClient.Fetched>
    fetch(String asset, Map<String,String> parameters, Duration timeout)
    Fetches one asset query, pull-once.
    int
    queriesSent()
    Fetches that wrote a query entry for a connector to execute.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • DataQueryClient

      public DataQueryClient(Space dataSpace, String requester)
      Creates a client that accepts a result from any admitted peer. Suitable for a fleet where every member is trusted to answer honestly; a fleet that is not should name its connectors via DataQueryClient(Space, String, Set).
      Parameters:
      dataSpace - the space queries and results flow through
      requester - the asking agent's name, stamped into queries

    • DataQueryClient

      public DataQueryClient(Space dataSpace, String requester, Set<PeerId> trustedConnectors)
      Creates a client that consumes only results written by the named connector peers (ASF-009): a result forged by any other admitted peer is ignored, for both the cache check and the awaited answer. The trusted peers come from the connectors' signed AssetCards (card.issuer()), discovered through the group's discovery service.
      Parameters:
      dataSpace - the space queries and results flow through
      requester - the asking agent's name, stamped into queries
      trustedConnectors - connector peers whose results to accept; empty accepts any peer's result

    • DataQueryClient

      public DataQueryClient(Space dataSpace, String requester, Authorizer authorizer)
      Creates a client whose trust in a result is the fleet's Authorizer (TODO-EFG §4, TODO item 6): a DataResult counts — for the cache check and for the awaited answer — only when its space-authenticated issuer's peer is permitted CONNECTOR_SERVE for result.asset(). Under the OIDC profiles that is the identity provider's aspace:connector-serve:<asset> scope; under the membership profiles it is admission plus any connector-serve grant. The trusted-set constructor remains for fleets that name their connectors directly.
      Parameters:
      dataSpace - the space queries and results flow through
      requester - the asking agent's name, stamped into queries
      authorizer - decides CONNECTOR_SERVE per result issuer and asset

  • Method Details

    • fetch

      public Optional<DataQueryClient.Fetched> fetch(String asset, Map<String,String> parameters, Duration timeout)
      Fetches one asset query, pull-once.
      Parameters:
      asset - the asset name from its card
      parameters - the query parameters
      timeout - how long to wait for a connector when the cache misses
      Returns:
      the answer, or empty when no connector answered in time

    • cacheHits

      public int cacheHits()
      Fetches answered by a live space result, with no source execution.

    • queriesSent

      public int queriesSent()
      Fetches that wrote a query entry for a connector to execute.