NAME

       Prophet::Replica

DESCRIPTION

       A base class for all Prophet replicas.

METHODS

       get_handle

       Determines what replica class to use and instantiates it. Returns the new replica object.

   store_local_metadata KEY => VALUE
       Takes a key and a value.

       Store some bit of metadata in a durable local datastore.  Metadata isn't propagated when
       replicas are synced.

       Returns true or false.

   fetch_local_metadata KEY
       Takes a scalar key.

       Fetches a bit of metadata from the local metadata store.

       Returns the value of the key found in the local metadata store.

       Returns undef if there's no value for the key in the local metadata store.

       _url_to_replica_class

       Returns the replica class for the given url based on its scheme.

       import_changesets { from => Prophet::Replica ... }

       Given a Prophet::Replica to import changes from, traverse all the changesets we haven't
       seen before and integrate them into this replica.

       This routine calls traverse_changesets on the 'from' replica, passing in the most recent
       changeset the current replica has seen and a callback routine which calls
       integrate_changeset on the local replica.

       That callback itself takes a callback, after_integrate_changeset , which a replica
       implementation can use to perform some action after a changeset is integrated into a peer.
       after_integrate_changeset takes a paramhash, currently with only a single key,
       'changeset'.

       import_resolutions_from_remote_replica { from => Prophet::Replica ... }

       Takes a Prophet::Replica object (and possibly some optional arguments) and imports its
       resolution changesets into this replica's resolution database.

       Returns immediately if either the source replica or the target replica lack a resolution
       database.

       integrate_changeset Prophet::ChangeSet

       Given a Prophet::ChangeSet, integrate each and every change within that changeset into the
       handle's replica.

       If there are conflicts, generate a nullification change, figure out a conflict resolution
       and apply the nullification, original change and resolution all at once (as three separate
       changes).

       If there are no conflicts, just apply the change.

       This routine also records that we've seen this changeset (and hence everything before it)
       from both the peer who sent it to us AND the replica which originally created it.

       record_changeset_and_integration Prophet::ChangeSet

       Given a Prophet::ChangeSet, integrate each and every change within that changeset into the
       handle's replica.

       If the state handle is in the middle of an edit, the integration of this changeset is
       recorded as part of that edit; if not, it is recorded as a new edit.

       last_changeset_from_source $SOURCE_UUID

       Returns the last changeset id seen from the replica identified by $SOURCE_UUID.

       has_seen_changeset { source_uuid => <uuid>, sequence_no => <int> }

       Returns true if we've previously integrated this changeset, even if we originally received
       it from a different peer.

       changeset_will_conflict Prophet::ChangeSet

       Returns true if any change that's part of this changeset won't apply cleanly to the head
       of the current replica.

       conflicts_from_changeset Prophet::ChangeSet

       Returns a Prophet::Conflict object if the supplied Prophet::ChangeSet will generate
       conflicts if applied to the current replica.

       Returns undef if the current changeset wouldn't generate a conflict.

       should_accept_changeset { from => Prophet::Replica, changeset => Prophet::ChangeSet }

       Returns true if this replica should integrate "changeset", false otherwise.

       fetch_changesets { after => SEQUENCE_NO }

       Fetch all changesets from this replica after the local sequence number SEQUENCE_NO.

       Returns a reference to an array of Prophet::ChangeSet objects.

       See also traverse_changesets for replica implementations to provide streamly interface.

   methods to be implemented by a replica backend
       uuid

       Returns this replica's uuid.

       latest_sequence_no

       Returns the sequence # of the most recently committed changeset.

       find_or_create_luid { uuid => UUID }

       Finds or creates a LUID for the given UUID.

       find_uuid_by_luid { luid => LUID }

       Finds the UUID for the given LUID. Returns "undef" if the LUID is not known.

       _create_luid ( 'uuid' => 'luid' )

       Given a UUID => LUID hash mapping, return a new unused LUID (one higher than the mapping's
       current highest luid).

       _do_userdata_read $PATH $DEFAULT

       Returns a reference to the parsed JSON contents of the file given by $PATH in the
       replica's userdata directory.

       Returns $DEFAULT if the file does not exist.

       _do_userdata_write $PATH $VALUE

       serializes $VALUE to JSON and writes it to the file given by $PATH in the replica's
       userdata directory, creating parent directories as necessary.

       _upstream_replica_cache_file

       A string representing the name of the file where replica URLs that have been previously
       pulled from are cached.

       _read_cached_upstream_replicas

       Returns a list of cached upstream replica URLs, or an empty list if there are no cached
       URLs.

       _write_cached_upstream_replicas @REPLICAS

       writes the replica URLs given by @REPLICAS to the upstream replica cache file.

       _guid2luid_file

       The file in the replica's userdata directory which contains a serialized JSON UUID => LUID
       hash mapping.

       _read_guid2luid_mappings

       Returns a UUID => LUID hashref for this replica.

       _write_guid2luid_mappings ( 'uuid' => 'luid' )

       Writes the given UUID => LUID hash map to "/_guid2luid_file" as serialized JSON.

       _read_luid2guid_mappings

       Returns a LUID => UUID hashref for this replica.

       traverse_changesets { after => SEQUENCE_NO, until => SEQUENCE_NO, callback => sub { my
       %data = (changeset => undef, @_} }

       Walk through each changeset in the replica after SEQUENCE_NO, calling the "callback" for
       each one in turn.

       can_read_changesets

       Returns true if this source is one we know how to read from (and have permission to do
       so).

       can_write_changesets

       Returns true if this source is one we know how to write to (and have permission to write
       to).

       Returns false otherwise.

       record_resolutions Prophet::ChangeSet

       Given a resolution changeset, record all the resolution changesets as well as resolution
       records in the local resolution database.

       Called ONLY on local resolution creation. (Synced resolutions are just synced as records.)

       _record_resolution Prophet::Change

       Called ONLY on local resolution creation. (Synced resolutions are just synced as records.)

   routines dealing with integrating changesets into a replica
       record_changes Prophet::ChangeSet

       Inside an edit (transaction), integrate all changes in this changeset and then call the
       _after_record_changes() hook.

       integrate_changes Prophet::ChangeSet

       This routine is called by "record_changes" with a Prophet::ChangeSet object. It integrates
       all changes from that object into the current replica.

       All bookkeeping, such as opening and closing an edit, is done by "record_changes".

       If your replica type needs to play games to integrate multiple changes as a single record,
       this is what you'd override.

   integrate_change Prophet::Change <Prophet::ChangeSet>
       Integrates the given change into the current replica using the currently active replica
       backend. Used in "integrate_changes".

       Changes can have the following types: - add_file - add_dir - update_file - delete

       Trying to integrate a change of an unknown type will result in a fatal error.

       record_integration_of_changeset Prophet::ChangeSet

       This routine records the immediately upstream and original source uuid and sequence
       numbers for this changeset. Prophet uses this data to make sane choices about later replay
       and merge operations

   routines which need to be implemented by any Prophet backend store
       uuid

       Returns this replica's UUID.

       create_record { type => $TYPE, uuid => $UUID, props => { key-value pairs } }

       Create a new record of type $TYPE with uuid $UUID within the current replica.

       Sets the record's properties to the key-value hash passed in as the "props" argument.

       If called from within an edit, it uses the current edit. Otherwise it manufactures and
       finalizes one of its own.

       delete_record {uuid => $UUID, type => $TYPE }

       Deletes the record $UUID of type $TYPE from the current replica.

       Manufactures its own new edit if "$self-"current_edit> is undefined.

       set_record_props { uuid => $UUID, type => $TYPE, props => {hash of kv pairs }}

       Updates the record of type $TYPE with uuid $UUID to set each property defined by the props
       hash. It does NOT alter any property not defined by the props hash.

       Manufactures its own current edit if none exists.

       get_record_props { uuid => $UUID, type => $TYPE, root => $ROOT }

       Returns a hashref of all properties for the record of type $TYPE with uuid $UUID.

       'root' is an optional argument which you can use to pass in an alternate historical
       version of the replica to inspect.  Code to look at the immediately previous version of a
       record might look like:

           $handle->get_record_props(
               type => $record->type,
               uuid => $record->uuid,
               root => $self->repo_handle->fs->revision_root( $self->repo_handle->fs->youngest_rev - 1 )
           );

       record_exists {uuid => $UUID, type => $TYPE }

       Returns true if the record in question exists and false otherwise.

       list_records { type => $TYPE }

       Returns a reference to a list of all the records of type $TYPE.

       list_types

       Returns a reference to a list of all the known types in your Prophet database.

       type_exists { type => $type }

       Returns true if we have any records of type $TYPE.

   routines which need to be implemented by any _writable_ prophet backend store
   optional routines which are provided for you to override with backend-store specific behaviour
       _after_record_changes Prophet::ChangeSet

       Called after the replica has integrated a new changeset but before closing the current
       transaction/edit.

       The SVN backend, for example, used this to record author metadata about this changeset.

       _set_original_source_metadata_for_current_edit

       Sets "original_source_uuid" and "original_sequence_no" for the current edit.

   helper routines
       log $MSG

       Logs the given message to "STDERR" (but only if the "PROPHET_DEBUG" environmental variable
       is set).

   log_fatal $MSG
       Logs the given message and dies with a stack trace.

   changeset_creator
       The string to use as the creator of a changeset.

   display_name_for_replica [uuid]
       If the user has a "friendly" name for this replica, then use it. Otherwise, display the
       replica's uuid.

       If you pass in a uuid, it will be used instead of the replica's uuid.