get_handle

_url_to_replica_class

import_changesets { from => Prophet::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 ... }

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

integrate_changeset Prophet::ChangeSet

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

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

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

changeset_will_conflict Prophet::ChangeSet

conflicts_from_changeset Prophet::ChangeSet

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

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

fetch_changesets { after => SEQUENCE_NO }

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

See also traverse_changesets for replica implementations to provide streamly interface.

log $MSG

log_fatal $MSG

changeset_creator

display_name_for_replica [uuid]

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

store_local_metadata KEY => 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

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.

methods to be implemented by a replica backend

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

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>

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

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

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.