treasure-intercept-cache

A class for creating servers of objects, whose structure are determined by application requirements. This server allows for objects searching via formalized queries. The server object instances of this class will reside in applications that create it by calling its constructor with a configuration object.

The server contained object created by constructing this class will also be a client to other processes. In fact it is an endpoint client that subscribes to channels that provide new assets meta descriptors vetted by an endpoint. This module provides the pathway for meta descriptors to arrive after publication and move into search tables established by copious-little-searcher descendants.

An example of an endpoint server can be found here: persistence-endpoints

install

npm install -s treasure-intercept-cache

purpose

This module, treasure-intercept-cache, ties together the classes provided by copious-little-searcher into one functional class; so that, applications using implementations of this module's classes can manage containers of asset descriptors. The asset descriptors may play the role of intert meta descriptor objects, intert data objects, or active (executable) meta objects providing interfaces to external services.

This module sets up communication with endpoints, makes the application aware of new assets descriptors arriving on disk or via publication (pub/sub), and provides a query interface allowing the application to either get an element by its _tracking field value or by performing fuzzy searches for a number of assets.

One aspect of this module goes beyond just getting records describing data. It may also acquire assets that supply executable interfaces run by other processes, local and remote. These are the active assets. And, this module provides methods for loading and invoking the actions provided by active assets.

executable assets - brief overview

For an example of an executable asset, one might think of processes that interface to blockchain oracles. The asset would have to have its executable part loaded lazilly. First its descriptor will arrive via publication. Then, its executable part will have to be loaded via a node.js 'require'.

Some of the methods included in the top level class require active assets to have interfaces for calling upon them. A fairly absract and pliable API interface will be specified for these classes; it will be described below. A model class (paternal template or, in other words, interface) will be provided so that applications can begin making these types of assets.

Uses

This module may be used by link servers such as those in mini-link-servers. Or, it may be used to provide link and connection descriptors for oracles that interface blockchain services as does copious-counters. Applications that instantiate the classes of this module may call the search and mapping methods themselves, acting as local clients rather than remote.

Classes Provided

One class is provided at the top level. Applications may use this without any changes. The first type of costomization results from parameters mentioned in the configuration object passed to the constructor.

The class exported at the top level is the following:

• TreasureInterceptCache

TreasureInterceptCache has supporting classes from which it derives behavior. Supporting classes are implemented and supplied. Some derive from copious-little-searcher classes. Furthermore, many of these classes may be overridden by classes mentioned in the configuration object passed to the TreasureInterceptCache constructor.

Supporting classes:

• RecordSearchApp
• EntryWatcher
• classes from copious-little-searcher - these include:
  1. ObjFileDirLoader
  2. SearchesByUser
  3. FileLists
• AppSearching extends Searching from copious-little-searcher
• ExecutableAssetManagerInterface

TreasureInterceptCache is the main class exported by the module. In fact, it is provided in the module index. In order to make used of it, require it as follows:

const TreasureInterceptCache = require('treasure-intercept-cache')

// to make an instance of this class use the constructor
// with a configuration object

let tic = new TreasureInterceptCache(conf)

TreasureInterceptCache is a descendant of RecordSearchApp. It must be configured to get desired functionality.

One class that is best configured by applicaitons using this class is the AppSearching class. A default is available, but it makes assumptions about the fields in the stored objects.

The AppSearching class is introduced through the config parameter used in the constructor of TreasureInterceptCache.

RecordSearchApp has a fairly complicated constuctor, while TreasureInterceptCache takes care of invoking it with the right parameters. The configuration for TreasureInterceptCache will be explained below. The configuration will direct the initialization of the classes which are parameters to the RecordSearchApp constructor.

mapping to objects

One point of this module is to provide keyed access to objects that may be used in processing data belonging to creators and being consumed by streamers or compositors. Most of the time, the objects will be meta objects that indicate where BLOB data is located for consumption. The objects will contain hash keys indicating such things as the following:

1. how to find an object in a repository
2. who is the creator of the data available for streaming or compositing
3. possible contract indicators having to do with group ownership and payout
4. etc.

Sometimes the keys that map the tables to the objects, _tracking keys, will be keys made by hashing serveral keys together for use during active session operations performed by servers. Keys indicating servers, consumers, and data providers (such as streamers) may be brought together to provide runtime access to objects that communicate with such services as blockchain oracles.

A distinction is being envisioned here between asset meta descriptors (inert objects) and active assets, those that have executable aspects, (executable assets). TreasureInterceptCache provides methods to deal with both. RecordSearchApp by itself provides the methods that work with intert objects.

mapping to intert assets

Inert objects are JavaScript objects (serialized in JSON format) that provide no operations executable by any method calls provided by this module. Most of the time, they will be used by client applications to find other data. Of course, the objects can be any shape or size and, consequently, they may be the data themselves. In any case, they are not exected to have executable aspects and will not be available to the methods that require functionality.

For either type of asset, this module handles the basic process of reading in new asset meta description provided by publishers such as persistence endpoints. Once the objects are stored in the tables managed by these classes, this module has methods that will allow for basic database style searches on small indexes. All the results of these searches are lists of the meta descriptors of data represented as JavaScript objects. If the objects are being sent to clients in response to queries the objects will be serialized in JSON formats.

This module provides a means for searching for objects based on methods from copious-little-seachers. When applications override AppSearching, the match method should be implemented to fit the shape of the objects that the application requires. That is, the client application will send a query and have expectations for results that are based upon the implementation of match and tables of filtering functions, where the implementations are provided by instances of the class provided by this moduule.

This module works with the _tracking field to identify individual objects. This module only sets the _tracking field if it is not provided by publishers. Most applications will provide the publishers and set up the data fields of the objects in such a way that all the _tracking fields are unique. This module makes the assumption of uniqueness of this field.

With unique _tracking fields, this module provides methods to map directly from the _tracking field to the object. One type of a tracking field can be a ucwid or an intergalactic idenity

Some uses

Most applications need to store and retrieve data. So, objects, handled here, may store the link and query information for use with basic database interfaces. Also, this module allows for expressing access to repositories, stores idealized by peer to peer storage.

Consumers of the objects, handled by this module and queried by application clients, may use these objects either to run a database query or access BLOBs via a repository bridge. This module does not provide transport of the BLOB data referred to by the objects it handles.

One example of a respostory bridge is a bridge that can access objects stored on IPFS nodes. While this modules, treasure-intercept-cache, does not access the data, it uses generalized identity, e.g. intergalactic idenity, to find the meta descriptors and to provide enough information for clients to map to repository identities. (That is, an application can set up an IGID to CID mapping for IPFS use.)

mapping to executable assets

Many applications will want to store executable objects. So, this module makes the configuration of execution handling possible.

This module uses the mechanisms for storing and retrieving inert assets to store and retrieve active assets. However, it adds functionality for active assets. Hence, this module has methods for loading and utilizing active assets. And, these methods are available to the applications that instantiate the TreasureInterceptCache class.

The executable part of an active asset is a node.js module that is restricted to providing class instances with methods conforming to the APIs described in this document (see the section Executable Assets (API)). An active asset, obtained from publishers, has its executable aspects loaded into the application through a process of lazy loading, require. It is possible that the active asset's executable module will be stored in repositories, accessible via a repository bridge, or repository API calls, such as an npm interface and a applicattion provided manager class may go to the extent of retrieving the class code. But, once the module is within the reach of the node.js require mechanism, the module will be accessed and required by intialization methods provided by TreasureInterceptCache instance objects.

The link to the loaded module provided in active asset objects will be referenced by a particular field. A field is set asside for this, _x_exec. The TreasureInterceptCache instance objects access this field, testing that it is present before calling the API specified methods belonging to the loaded module.

The field _x_exec is not expected to be present in the active asset when it arrives from publishers. However, a field, _x_exec_uri is expected to be present. This should be the name of the module that has to be loaded. That is it should be a paramter for require as follows:

this_asset._x_exec = require(this_asset. _x_exec_uri)

stamping activity

If an assets is active and if the methods available in the object referred to by _x_exec has the following methods, the asset may be used in the stamping activity:

• active_operations used in check_initialization of TreasureInterceptCache
• stamp_action used in stamp_it of TreasureInterceptCache
• end_session_activity used in final of TreasureInterceptCache

The stamping activity is a process that marks data as it is being accrued. The data may be being stamped to mark ownership or sequence or some other function. It is assumed that some asset descriptors describe processes that provide this stamping function and that these descriptors allow for an interface to connect the accrued data with contract services.

especially time stamps

One reason to stamp data may be to put a time stamp on it. This stamping provides implicit sequencing. For data being passed through to contracts, the stamping activity may provide a time that a contract becomes valid for a piece of data.

counting stamps

Another reason to stamp data is to count its use in a contract. Or rather, some data representing a consumption of BLOB data, streaming or compositing, may be stamped and counted each time the BLOB data is accessed or consumed.

TreasureInterceptCache class

TreasureInterceptCache extends a class RecordSearchApp. Copies of RecordSearchApp have been used in mini-link-servers. This application abstracts any concrete code that was included in those copies. RecordSearchApp may be imported from this module by those who want to implement their own subclasses. This module provides TreasureInterceptCache as the main class.

Here is how to require either class:

const TreasureInterceptCache = require('treasure-intercept-cache')

// then create instances of TreasureInterceptCache

// to get into implementation details on your own,
// you may begin with RecordSearchApp as such

const {RecordSearchApp} = require('treasure-intercept-cache')

Here are methods provided by this class:

Methods for basic operation:

• constructor(conf)
• initialize(conf)
• prune_searches()
• save_publication(pub)
• remove_publication(tracking)

Methods for loading and intializing the executable asset

• has_asset(asset_key)
• deactivate_asset(asset_key)
• check_initialization(asset_key,ucwid,server_id,session_key)
• report_status
• lock_transition
• unlock_transition
• final(ucwid,sess_data)

Methods for working with the executable asset

• check_target_exsits
• check_target_has_resources
• check_target_can_receive
• resource_transfer
• chained_resource_transfer
• state_transition
• reset_state_transition
• stamp_it(time_stamp,chunk,ucwid,server_id,session_key)

By way of RecordSearchApp

• add_persistence_service
• injest_counting_service
• remove_counting_service

More having to rate limiting downstream uses (nearer client):

• rate_limit_redirect
• rate_limited
• rated_custom_search_ops
• rated_custom_search_processing
• rated_search_processing

Parameer based search interface:

• process_search

Searches relating to a particular user:

• get_custom_search
• process_custom_search(owner,params)
• run_custom_operation(owner,op)
• particular_interface_info

Interaction with the object-loader/directory-watcher:

• start_watching_files
• after_loading

TreasureInterceptCache -- method details

constructor(conf)

The constructor takes one parameter, conf, a configuration object. This sets up any class overrides that can be passed to the parent co=nstructor belonging to RecordSearchApp. The configuration may include any or all of the follwoing fields:

{
	"file_list_class" : for searching,
	"application_searcher" : the search engine class,
	"use_active_asset_manager" : a class that provides loading class object via require
	"entry_wqtcher" : an override of the DirEntryWatcher from little-searcher
	"object_file_loader" : a class that loads files an injects them into the search tables
}

parameters: (obj,ordering)

• conf -- the configuration object

initialize(conf)

Applications may override this and use their application dependent parts of the conf object (passed in by the constructor). This runs initialization after construction as a task set on the event queue (node.js). This starts watching the configured directory for new assets descriptors, loads objects received during the previous run, restores backed-up searches (not pruned in the last session) and initiates the pruning interval.

parameters: (obj,ordering)

• conf -- the configuration object

prune_searches()

Removes old search queries and their collected results from memory if they are older than the configured conf.prune_interval. If conf.prune_interval is not set, a default prune interval will be set to eight hours.

parameters: (obj,ordering)

• conf -- the configuration object

save_publication(pub)

Calls the parent class save_publication(pub) which returns the JSON parsed objects. If this class instance is processing active assets, this method loads the executive parts of the active asset. The parent method adds the object to the search tables.

parameters: ()

• pub -- a new publication arriving through subscription handling

remove_publication(tracking)

Uses tracking to find the object to which it maps. This shuts down the executive part of the active asset if this class instance is processing active assets (as opposed to inert). Calls, the parent method remove_publication(tracking) to remove the object from searches.

parameters: (obj,ordering)

• tracking -- This is the unique id of the object stored in its _tracking field.

has_asset(tracking)

Uses tracking to locate an active asset in the search tables. Places a reference to the object in the active assets table belonging to this class instance. The table keeps track of the objects that the application has required of this class instance.

parameters: (tracking)

• tracking -- This is the unique id of the object stored in its _tracking field

deactivate_asset(tracking)

Deletes the asset from the active assets table. Does not operate on the object or call its methods.

parameters: (tracking)

• tracking -- This is the unique id of the object stored in its _tracking field

check_initialization(asset_key,ucwid,server_id,session_key)

Ultimately calls active_operations(ucwid,server_id,session_key) of the active asset identified by the asset key. Checks initialization - in other words, allows the active asset to initialize if has not yet done so.

Most implementation will want to intialize their asset once with respect to the call parameters. Then, ensuing calls will simply report initialization status.

On successful initlialization this method places the active asset into the table of active asset uses. The active asset will be keyed by the ucwid parameter.

parameters: (ucwid,server_id,session_key)

• asset_key -- the same as tracking
• ucwid -- refers to a caller - in most cases a user/consumer
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

final(ucwid,sess_data)

Shuts down the operations of the active asset relative to the caller identified by ucwid. Ultimately calls end_session_activity(ucwid,sess_data), a method of the active asset. Note that this does not use a tracking kind of parameter, but looks into the table of active asset uses by reference to the caller identitity, ucwid.

parameters: (ucwid,sess_data)

• ucwid -- refers to a caller - in most cases a user/consumer
• sess_data -- provides an object parameter that can mention the session id and other call parameters

report_status

Give the executable asset a chance to report on its status. Returns JSON that may be formatted for human readable reports. This status report is determined by the implementation of the active asset.

Ultimately calls report_status(server_id,session_key) a method implemented by the active asset.

parameters: (asset_key,server_id, session_key)

• asset_key -- the same as tracking
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

lock_transition

Ultimately calls lock_transition(resource_id,server_id,session_key). Both the application and the acive asset share some knowledge about the resource id. This method allows the active asset to provide semaphore types of behavior for resources it manages.

More about resource IDs is discussed below. Examples can be 'bank accounts', 'addressable machines', etc. Sometimes the resource will be specific to a caller, e.g. something or someone identified by a ucwid. This call uses the session key and server id to determine the target of locking.

parameters: (asset_key,resource_id,server_id,session_key)

• asset_key -- the same as tracking
• resource_id -- this is a resource known to the active asset
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

unlock_transition

Ultimately calls unlock_transition(resource_id,server_id,session_key). Both the application and the acive asset share some knowledge about the resource id.

This method allows the active asset to provide semaphore types of behavior for resources it manages. Should reverse the affects of lock. This method should be called implicity by final.

parameters: (asset_key,resource_id,server_id,session_key)

• asset_key -- the same as tracking
• resource_id -- this is a resource known to the active asset
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

check_target_exsits

Abstracts the notion of checking whether a bank account exsts. The resource ID might be a 'bank account' or it might be 'store of ink' or anything that needs proof as a precondition for operations (transitions) going forward.

This call will attempt to gain a proof of existence for all idenities that are keys in the mapping object. (A JavaScript object).

Utlimately calls check_targets(resource_id,ucwid_table,server_id,session_key), a method of the active asset.

parameters: (asset_key,resource_id,ucwid_table,server_id,session_key)

• asset_key -- the same as tracking
• resource_id -- this is a resource known to the active asset
• ucwid_table - a map of user ids to any set of parameters needed by the prover of this status.
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

check_target_has_resources

Given that there is a target, something that can hold value, such as quantity, this method has the purpose of checking on the quantities of a target.

resource_identifier ... can be 'balance-greater', 'balance_leq', 'min-max-rating', 'min-qty', 'max-qty', etc. It is up to the asset to implement the identificiation of the of the resource identifier. It is up to the asset to check if the fields in ucwid_to_limits_table have correct values for comparison.

Utlimately calls check_target_resources(resource_identifier,ucwid_to_limits_table,server_id,session_key), a method of the active asset.

parameters: (asset_key,resource_id,ucwid_to_limits_table,server_id,session_key)

• asset_key -- the same as tracking
• resource_id -- this is a resource known to the active asset
• ucwid_to_limits_table - a map of user ids to any set of parameters needed by the prover of this status.
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

check_target_can_receive

This method provides an interface for queries asking if a some set of callers/consumers/clients can receive some quantity that may be transfered from one entity to another. The ucwid table, as in other methods, provides a mapping from the identity of the user to obects that provide any parameters needed by the active asset to prove the query.

For example, the application may wish to determine if an account can receive tokens (coins) from another account.

Utlimately calls check_receptive(resource_identifier,ucwid_table,server_id,session_key), a method of the active asset.

parameters: (asset_key,resource_id,ucwid_table,server_id,session_key)

• asset_key -- the same as tracking
• resource_id -- this is a resource known to the active asset
• ucwid_table - a map of user ids to any set of parameters needed by the prover of this status.
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

resource_transfer

This mehod provides an interface to the active asset allowing for the transfer of some resource from one idenitifiable entity to another identitifiable entity.

For example, the resource may be some amount of coins that move from one wallet to another.

Utlimately calls resource_transfer(resource_identifier,from_ucwid_to_ucwid_table,server_id,session_key), a method of the active asset.

parameters: (asset_key,resource_id,from_ucwid_to_ucwid_table,server_id,session_key)

• asset_key -- the same as tracking
• resource_id -- this is a resource known to the active asset
• from_ucwid_to_ucwid_table - a map of user ids to any set of parameters needed by the prover of this status, where these parameters must contain the identity of a recipient.
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

chained_resource_transfer

This method iterates, calling resource_transfer over and over until the active asset method tells it to stop or it fails to report a status for the set of transfers listed in the transfer table.

The resource_transfer method is expected to return a couple of values, a flag indicating if it is done and a status report which will be the next version of the stable, from_ucwid_to_ucwid_table.

Utlimately calls resource_transfer(resource_identifier,from_ucwid_to_ucwid_table,server_id,session_key), a method of the active asset.

parameters: (asset_key,resource_id,from_ucwid_to_ucwid_table,server_id,session_key)

• asset_key -- the same as tracking
• resource_id -- this is a resource known to the active asset
• from_ucwid_to_ucwid_table - a map of user ids to any set of parameters needed by the prover of this status, where these parameters must contain the identity of a recipient.
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

state_transition

Provide a method interface for driving state transitsions.

This expects the active asset call to return an indication of state. The value is expected to be an Object.

For Petri nets, the returned value might be a marking. For ATMs, the returned value might indicate a state and output values. In the end, this determined by the application and the implementation of the active asset.

Utlimately calls state_transition(resource_identifier,transition_parameters,server_id,session_key), a method of the active asset.

parameters: (asset_key,resource_id,transition_parameters,server_id,session_key)

• asset_key -- the same as tracking
• resource_id -- this is a resource known to the active asset
• transition_parameters - an Object that provides the parameters needed to drive a state transition.
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

reset_state_transition

Provides an interface allowing for the a call into the active asset to set a particular state in a state machine in a reentry fashion.

Utlimately calls reset_state_transition(resource_identifier,marking,server_id,session_key), a method of the active asset.

parameters: (asset_key,resource_id,marking,server_id,session_key)

• asset_key -- the same as tracking
• resource_id -- this is a resource known to the active asset
• marking - an Object that will contain fields and values required to put the state machine into some predermined state or configuration.
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

stamp_it(time_stamp,chunk,ucwid,server_id,session_key)

Allows for the passthrough of data that is to be stamped and recorded in a contract. The aim is for real time data stamping and ownership clarification.

Utlimately calls stamp_action(time_stamp,chunk,ucwid,server_id,session_key), a method of the active asset.

parameters: (time_stamp,chunk,ucwid,server_id,session_key)

• time_stamp -- determined by a server/client agreement, marks the time of the stamp
• chunk -- Blob data to be stamped
• ucwid -- the owner of the Blob data
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

count_it(time_stamp,asset_id,proc_ucwid,server_id,session_key)

Allows for the counting of asset uses, allowing for the count to be stamped and recorded in a contract. This should work with processes that identify payout tables, wallets to be paid, etc.

Utlimately calls count_action(time_stamp,asset_id,proc_ucwid,server_id,session_key), a method of the active asset.

parameters: (time_stamp,chunk,ucwid,server_id,session_key)

• time_stamp -- determined by a server/client agreement, marks the time of the stamp
• asset_id -- the id of an inert asset that is being counted
• proc_ucwid -- special process identification, allowing for the ID of the streamers or compositor servers and ongoing activity taking place during the session.
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

Methos from RecordSearchApp

add_persistence_service

A passthrough to the search watcher. Connect to an endpoint that manages a type of asset, inert or active. The special path will be used to add a new connect path different from others with different special paths.

Subscribes to publications of assets coming along the path from the endpoint server.

This method has previously been used to respond to sepcial utilities that will introduce the endpoint to the registry application. That is, this connection is established any time after the application is running and initalized. Tools adding connections to new endpoints are used behind firewalls, etc.

parameters: (persistence_link,special_path)

• persistence_link -- the configuration object
• special_path -- a distinct path

injest_counting_service

For applications, similar to mini link servers, that interact with counting services. This takes in a counting services descriptor as if it were an inert asset. The asset contains links the may be used by clients requiring connections to counting services. The client connections may be to HTTP methods that return links to streamers of client requested content.

parameters: (counter)

• counter -- the configuration object

remove_counting_service

Removes a counting service from the conversation provided by application using the classes of this module.

parameters: (counter)

• counter -- the asset object, provides _tracking for finding the counter to be removed.

The rate limited methods take parameters from HTTP requests determined by node.js packages such as polka, express, or fastly.

rate_limit_redirect

Can be implemented by a descendant. This is a stub. HTTP servers can set the response, res with a redirect status.

parameters: (req,res)

• req,res -- the request and response objects handed to HTTP path handlers

rate_limited

Takes the ucwid field of parameter from a request. A stub that returns false. Implement in the descendant.

parameters: (ucwid)

• ucwid -- identifies a caller

rated_custom_search_ops

Checks the rate limit before calling custom_search_ops.

parameters: (req,res)

• req,res -- the request and response objects handed to HTTP path handlers

rated_custom_search_processing

Checks the rate limit before calling custom_search\ _processing.

parameters: (req,res)

• req,res -- the request and response objects handed to HTTP path handlers

rated_search_processing

Checks the rate limit before calling search_processing.

parameters: (req,res)

• req,res -- the request and response objects handed to HTTP path handlers

process_search

This call makes it easy to call get_search of copious-little-searcher from an HTTP handler. But, it is not dependent upon HTTP req and res parameters. Its one parameter, the parameter object, must have three parameters as follows:

1. query -- a string that is a query formatter for use in get_search
2. bcount -- box count, which is the number of results requested
3. offset -- an offset into a list of search results

    let query = params.query;
    let box_count = parseInt(params.bcount);
    let offset = parseInt(params.offset);

parameters: (params)

• params -- a parameter object that provides the field-value pairs needed by get_search

get_custom_search

Returns the User Search Object. Will make a new User Search Object and store it in a table _particular_user_searches if it is not already there.

parameters: (owner)

• owner -- some identifier that can be an Object key that maps to a User Search.

process_custom_search(owner,params)

Calls the process_search method of a User Search Object.

parameters: (owner,params)

• owner -- some identifier that can be an Object key that maps to a User Search.
• params -- a parameter Object for calling process_search

run_custom_operation(owner,op)

After getting a User Search Object runs the specified OP specified by the parameter. Refer to copious-little-searcher for documentation on the OP.

Returns the results of the op.

parameters: (owner,op)

• owner -- some identifier that can be an Object key that maps to a User Search.
• op -- a string naming an OP, e.g. 'search', 'remove', 'item', 'info'

particular_interface_info

After getting a User Search Object runs the OP, 'info'. Refer to copious-little-searcher for documentation on the OP, 'info'.

Returns the results of the op, 'info'.

parameters: (owner)

• owner -- some identifier that can be an Object key that maps to a User Search.

start_watching_files

Calls the start method of the dir watcher. Called during initialization.

no parameters

after_loading

This method is used by the dir object loader. After it loads all backed up obejcts, it calls this method.

This in turn calls update_global_file_list_quotes_by() of the Searching implmentation.

no parameters

ServiceEntryWatcher (internal support class)

The ServiceEntryWatcher extends DirWatcherHandler from the module copious-little-searcher.

ServiceEntryWatcher adds functionality for responding to publications from endpoint servers.

Here are methods provided by this class:

The entry and exit of assets from publishers:

• constructor(directory,element_manager,conf)
• add_persistence_service(persistence_link,special_path)
• injest_publication(pub)
• remove_publication(pub)

Methods for interacting with the searching class:

• add_just_one_new_asset(fdata)
• remove_just_one_asset(fname)

Methods for applications interacting with counting services:

• injest_counting_service(counter)
• remove_counting_service(counter)

Extra methods for custom and exact seraching:

• addToCustomSearch(f_obj,is_new)
• track_list_id(name_id)

ServiceEntryWatcher -- method details

constructor(dir,conf,element_manager,app)

This class extends the class DirWatcherHandler from copious-little-searcher.

The constructor first calls the parent constuctor with the parameters: dir,element_manager,conf.

The configuration may also include asset_type, pub_topic, unpub_topic. These parameters set the topics for the subscriptions this class instance makes with endpoint servers.

parameters: (dir,conf,element_manager,app)

• dir -- the directoy this instance will watch
• conf -- the configuration object
• element_manager -- an object with an application wide iterable such as Searching
• app - a back reference to the application, e.g. RecordSearchApp

add_persistence_service(persistence_link,special_path)

This is the internal method that adds a link to an endpoint server and sets up subscriptions to the objects it publishes.

parameters: (persistence_link,special_path)

• persistence_link -- the configuration object
• special_path -- a distinct path

injest_publication(pub)

This takes in an endpoint publication. It makes sure the publication is in object form before asking the Searching implementation to add it into its tables. After it negotiates with searching, it calls upon the application to save the object.

parameters: (pub)

• pub -- an asset, active or inactive, published by an endpoint

remove_publication(pub)

Given a published asset, active or inert, with a _tracking field, this method locates the object and inverts the actions of injest_publication(pub), removing this object from searching and backup caches.

parameters: (pub)

• pub -- an asset, active or inactive, published by an endpoint

add_just_one_new_asset(fdata)

A method for calling upon the Searching object for adding objects. Will check if the object is an array and adds all the objects in the array if so. Otherwise, it adds one object to the Searhing table by calling upon Searching methods. Also, adds the objet or list of objects to custom searches provided there is an owner id field, ucwid, that can be used to find the custom searches.

parameters: (fdata)

• fdata -- a sysnonym for pub

remove_just_one_asset(fname)

Uses the fname to find the object in Searching tables and requests its removal. Also, uses the fname as a file name that is to be removed from the backup (file cache) directory.

parameters: (fname)

• fname -- a formalized file name with _tracking information that allows the object to be found

injest_counting_service(counter)

Defers to the application's implementation of this method. This has been made a method of this class to simplify the subscription callbacks.

parameters: (counter)

• counter -- an inert asset describing a counting service

remove_counting_service(counter)

Defers to the application's implementation of this method. This has been made a method of this class to simplify the subscription callbacks.

parameters: (counter)

• counter -- an inert asset describing a counting service

addToCustomSearch(f_obj,is_new)

Request the application to find the custom search belonging to the owner of the asset. If it is found, adds the object to the custom User Search.

parameters: (f_obj,is_new)

• f_obj -- an asset object (the parameter name is for suggesting it is already backed up into a file).
• is_new -- used by the Searching add_just_one

track_list_id(name_id)

A check on name_id to see if it is of the right for format for identifing an asset, inert or active.

parameters: (obj,ordering)

• name_id -- a string to be checked for naming conventions.

Executable Assets (API)

These types of assets provide an _x_exec field refering to a class instance established through a require call (lazy loading). Each asset will provided a field, _x_exec_uri indicating the location of the module that is to be required. In some cases, the module may have to be fetched out of a repository. This class will provide awareness to a few types of repositories, especially those accessible via a repository bridge. (on roadmap)

ExecutableAsset Methods

• active_operations(ucwid,server_id,session_key)
• end_session_activity(ucwid,sess_data)
• report_status(server_id,session_key)
• lock_transition(resource_id,server_id,session_key)
• check_targets(resource_id,ucwid_table,server_id,session_key)
• check_target_resources(resource_identifier,ucwid_to_limits_table,server_id,session_key)
• check_receptive(resource_identifier,ucwid_table,server_id,session_key)
• resource_transfer(resource_identifier,from_ucwid_to_ucwid_table,server_id,session_key)
• state_transition(resource_identifier,transition_parameters,server_id,session_key)
• reset_state_transition(resource_identifier,marking,server_id,session_key)
• stamp_action(time_stamp,chunk,ucwid,server_id,session_key)
• count_action(time_stamp,asset_id,proc_ucwid,server_id,session_key)

ServiceEntryWatcher -- method details

active_operations(ucwid,server_id,session_key)

Makes sure that the active asset has readied operations for the consumer acting within a session on a particular server.

parameters: (ucwid,server_id,session_key)

• ucwid -- refers to a caller - in most cases a user/consumer
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

end_session_activity(ucwid,sess_data)

Turn off the operations for a consumer associated with the session data.

parameters: (ucwid,sess_data)

• ucwid -- refers to a caller - in most cases a user/consumer
• sess_data -- provides an object parameter that can mention the session id and other call parameters

report_status(server_id,session_key)

This should return a status report that the application knows how to present. Ideally, the active asset will be written for an application or it will provide a clear description of its status report for application developers.

parameters: (server_id,session_key)

• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

lock_transition(resource_id,server_id,session_key)

Locks a resource for a state transition. Assigns this resource or limits access to other processes or its own process to the asset that are wholly owned by a session, identified by the session key.

parameters: (resource_id,server_id,session_key)

• resource_id -- this is a resource known to the active asset
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

check_targets(resource_id,ucwid_table,server_id,session_key)

This method provides an existence check or existence plus operational efficacy of some target identified by a resource ID.

An example of a target would be a bank account or crypto wallet.

parameters: (resource_id,ucwid_table,server_id,session_key)

• resource_id -- this is a resource known to the active asset
• ucwid_table - a map of user ids to any set of parameters needed by the prover of this status.
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

check_target_resources(resource_identifier,ucwid_to_limits_table,server_id,session_key)

Provides a checks for the existence of resources maintaind by a target identifed by the recourse identifier. This check is often a quantity check.

An example would be that a target, a bank account, would have sufficient funds, where the check is parameterized by limits.

Notice that the ucwid_to_limits_table is a plurality. For example, this method would be called on a number of banks accounts.

parameters: (obj,ordering)

• resource_id -- this is a resource known to the active asset
• ucwid_to_limits_table - a map of user ids to any set of parameters needed by the prover of this status.
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

check_receptive(resource_identifier,ucwid_table,server_id,session_key)

This method checks to see if a number of targets can accept new resources.

For example, while a bank account might be able to receive more funds, a pie shop might already have too many pies in storage.

parameters: (resource_identifier,ucwid_table,server_id,session_key)

• resource_id -- this is a resource known to the active asset
• ucwid_table - a map of user ids to any set of parameters needed by the prover of this status.
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

resource_transfer(resource_identifier,from_ucwid_to_ucwid_table,server_id,session_key)

This method is an interface to any oracle operations that result in the transfer of resources from one entity to another.

parameters: (resource_identifier,from_ucwid_to_ucwid_table,server_id,session_key)

• resource_id -- this is a resource known to the active asset
• from_ucwid_to_ucwid_table - a map of user ids to any set of parameters needed by the prover of this status, where these parameters must contain the identity of a recipient.
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

state_transition(resource_id,transition_parameters,server_id,session_key)

This is an interface that calls upon oracular operations to effect a state transition in some system.

parameters: (resource_id,transition_parameters,server_id,session_key)

• resource_id -- this is a resource known to the active asset
• transition_parameters - an Object that provides the parameters needed to drive a state transition.
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

reset_state_transition(resource_id,marking,server_id,session_key)

Force a state machine into a particular state, making the state the initial state of future operations. The marking could be a Petri-net marking that is simply written into a Petri-net description.

This is more for the synchronization of tracking computation with the real world. Or it may be used to jump into something like a game state.

parameters: (resource_id,marking,server_id,session_key)

• resource_id -- this is a resource known to the active asset
• marking -- this is a configuration of a state machine that can be written to force the current state
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

stamp_action(time_stamp,chunk,ucwid,server_id,session_key)

This method is the oracular interface to contract operations used to secure the time stamp and ownership marking of a chunk of data.

parameters: (time_stamp,chunk,ucwid,server_id,session_key)

• time_stamp -- determined by a server/client agreement, marks the time of the stamp
• chunk -- Blob data to be stamped
• ucwid -- the owner of the Blob data
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session

count_action(time_stamp,asset_id,proc_ucwid,server_id,session_key)

This is the oracluar interface to opeations that count the use of an asset and record it within a contract. This should work with processes that identify payout tables, wallets to be paid, etc.

Utlimately calls count_action(time_stamp,asset_id,proc_ucwid,server_id,session_key), a method of the active asset.

parameters: (time_stamp,chunk,ucwid,server_id,session_key)

• time_stamp -- determined by a server/client agreement, marks the time of the stamp
• asset_id -- the id of an inert asset that is being counted
• proc_ucwid -- special process identification, allowing for the ID of the streamers or compositor servers and ongoing activity taking place during the session.
• server_id -- passed on to the active asset method -- identify the server calling
• session_key -- passed on to the active asset method -- refers to a session such as a browser session