README.md

# About

The remote-gerrit-account-cache lib provides a way to sync accounts from
a remote Gerrit system. This library overrides the Accounts cache
implementation from core and loads accounts from a remote Gerrit
system using /accounts/ REST APIs. Upon fetching the account info from
the remote Gerrit REST API, the account is saved into NoteDb and re-indexed.
If the remote Gerrit REST API fails to return the account, the cache falls
back to the account stored in NoteDb.

The HTTP user needs to have 'View All Accounts', 'Modify Account' and
'View Secondary Emails' Capabilities in remote gerrit site inorder to
fetch account details using /accounts/{account-id}/detail and
/accounts/{account-id}/external.ids REST APIs.

The remote REST APIs fired from this lib module are rate limited to
8 per second. This can be changed with a config if needed.


## Test scenarios:
#### Add new email
Add new email address for a user in the remote Gerrit site.
The new email address must be visible on the internal site either after
accounts cache expiry or flushing the accounts cache.

#### Update preferred email
Update preferred email for a user in the remote Gerrit site.
The update must be visible on the internal site either after
accounts cache expiry or flushing the accounts cache.

#### Delete an email
Delete an email for a user in the remote Gerrit site.
The update must be visible on the internal site either after
accounts cache expiry or flushing the accounts cache.

#### Add a new account
Add a new account in the remote Gerrit site. The new account must
be visible on the internal site whenever the new account is
queried for.

#### Delete an account
Delete an account in the remote Gerrit site. The internal
Gerrit site continues to return the account as it falls-back
to NoteDB when /accounts/ API fails to return an account.

#### Accounts cache timeout
The entries in the accounts cache must be evicted after maxAge
duration reaches.

#### API throttling
The remote REST APIs must be throttled based on the requestsPerSecond
gerrit setting.


# How to build
This libModule is built like a Gerrit in-tree plugin, using Bazelisk.

Build in Gerrit tree
Create a symbolic link of the repository source to the Gerrit source tree /plugins/remote-gerrit-account-cache directory.

Example:
```
git clone https://gerrit.googlesource.com/gerrit
git clone https://gerrit.googlesource.com/modules/remote-gerrit-account-cache
cd gerrit/plugins
ln -s ../../remote-gerrit-account-cache .
```
From the Gerrit source tree issue the command bazelisk build plugins/remote-gerrit-account-cache

Example:
```
bazelisk build plugins/remote-gerrit-account-cache
```
The libModule jar file is created under bazel-bin/plugins/remote-gerrit-account-cache/remote-gerrit-account-cache.jar

To execute the tests run bazelisk test plugins/remote-gerrit-account-cache/... from the Gerrit source tree.

Example:
```
bazelisk test plugins/remote-gerrit-account-cache/...
```

# How to import into Eclipse as a project
Add remote-gerrit-account-cache in the CUSTOM_PLUGINS section of the tools/bzl/plugins.bzl.

Example:
```
CUSTOM_PLUGINS = [
    "remote-gerrit-account-cache",
]
```
Run tools/eclipse/project.py for generating or updating the Eclipse project.

# How to install

Copy the remote-gerrit-account-cache.jar into the `${GERRIT_SITE}/lib/`
so that it is being loaded when the Gerrit instance is started. Note
that the following configuration options need to be added.

# Configuration

## Section gerrit

### gerrit.installModule

AccountCache module which will be overriding the core AccountCache
implementation. By default, unset.

Example:
```
[gerrit]
    installModule = com.googlesource.gerrit.plugins.remotegerritaccountcache.AccountCacheImpl$AccountCacheModule
```

## Section remote-gerrit-account-cache

### remote-gerrit-account-cache.remoteGerritBaseUrl

The remote Gerrit site base URL. By default, unset.

Example:
```
[remote-gerrit-account-cache]
    remoteGerritBaseUrl = https://gerrit.example.com
```

### remote-gerrit-account-cache.httpUsername

The remote Gerrit site HTTP username. By default, unset.

Example:
```
[remote-gerrit-account-cache]
    httpUsername = example
```

### remote-gerrit-account-cache.httpPassword

The remote Gerrit site HTTP password. By default, unset.

Example:
```
[remote-gerrit-account-cache]
    httpPassword = ***
```

### remote-gerrit-account-cache.requestsPerSecond

The maximum rate at which the remote REST APIs are fired.
By default, set to 8 per second.

Example:
```
[remote-gerrit-account-cache]
    requestsPerSecond = 10
```

## Section cache

### cache.accounts.maxAge

Maximum age to keep an entry in the accounts cache. By default,
the entries in accounts cache expire in a day.

Example:
```
[cache "accounts"]
    maxAge = 1d
```

### cache.accounts.refreshAfterWrite

Duration after which account cache entries are eligible for asynchronous
refresh. By default, set to 23h.

Example:
```
[cache "accounts"]
    refreshAfterWrite = 23h
```