---
name: "Prophet::Replica"
section: "3pm"
platform: "linux"
package: "libprophet-perl"
version: "0.743-1"
release: "Debian 7 (Wheezy)"
platforms: ["linux"]
url: "https://new.carta.tech/Prophet::Replica"
---

# Prophet::Replica(3pm)

## 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 hasn't yet seen the changeset `"changeset"`.

*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. Used in "integrate\_changes".

*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\_records*

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.