Clio

https://github.com/xrplf/clio
Admin
Clio is an XRP Ledger API server optimized for RPC calls, storing validated historical ledger and...
Tokens:41,727
Snippets:149
Trust Score:9.6
License:ISC
Update:1 year ago
Show doc for...
Tokens:
Raw
### Start Clio Server

Source: https://github.com/xrplf/clio/blob/develop/docs/run-clio.md

Command to start the Clio server with a specified configuration file. Clio will automatically wait for rippled to sync and begin extracting ledgers.

```sh
./clio_server config.json
```

--------------------------------

### Conan Install and Build Clio

Source: https://github.com/xrplf/clio/blob/develop/docs/build-clio.md

Steps to install dependencies using Conan and build the Clio project with CMake. This includes creating a build directory, installing packages with specific settings and options, configuring with CMake using the Conan toolchain, and finally building the project.

```sh
mkdir build && cd build
conan install .. --output-folder . --build missing --settings build_type=Release -o '&:tests=True'
cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel 8
```

--------------------------------

### Run Local ScyllaDB

Source: https://github.com/xrplf/clio/blob/develop/docs/trouble_shooting.md

Starts a local ScyllaDB instance in a Docker container. This is useful for testing Clio's database connectivity without a separate ScyllaDB installation. Ensure Docker is installed and running.

```sh
docker run --rm -p 9042:9042 --name clio-scylla -d scylladb/scylla
```

--------------------------------

### Conan Mac apple-clang Profile Example

Source: https://github.com/xrplf/clio/blob/develop/docs/build-clio.md

Example Conan profile configuration for macOS using apple-clang compiler, specifying settings for architecture, build type, compiler version, and C++ standard. It also includes a configuration for passing specific CXX flags to the grpc dependency.

```text
[settings]
arch={{detect_api.detect_arch()}}
build_type=Release
compiler=apple-clang
compiler.cppstd=20
compiler.libcxx=libc++
compiler.version=17
os=Macos

[conf]
grpc/1.50.1:tools.build.cxxflags+=["-Wno-missing-template-arg-list-after-template-kw"]
```

--------------------------------

### Conan Linux GCC Profile Example

Source: https://github.com/xrplf/clio/blob/develop/docs/build-clio.md

Example Conan profile configuration for Linux using GCC compiler, specifying settings for architecture, build type, compiler version, and C++ standard. It also includes a configuration to specify the exact executables for C and C++ compilers.

```text
[settings]
arch={{detect_api.detect_arch()}}
build_type=Release
compiler=gcc
compiler.cppstd=20
compiler.libcxx=libstdc++11
compiler.version=12
os=Linux

[conf]
tools.build:compiler_executables={"c": "/usr/bin/gcc-12", "cpp": "/usr/bin/g++-12"}
```

--------------------------------

### Install and Enable Pre-commit Hooks

Source: https://github.com/xrplf/clio/blob/develop/CONTRIBUTING.md

Installs the pre-commit package and enables pre-commit and pre-push hooks to ensure code quality and style. These hooks run tools defined in the .pre-commit-config.yaml file.

```bash
pip3 install pre-commit
pre-commit install --hook-type pre-commit --hook-type pre-push

```

--------------------------------

### Install Git LFS Hooks

Source: https://github.com/xrplf/clio/blob/develop/CONTRIBUTING.md

Installs the Git Large File Storage (LFS) hooks, which are necessary before installing pre-commit hooks.

```bash
git lfs install

```

--------------------------------

### Docker Compose for Prometheus and Grafana

Source: https://github.com/xrplf/clio/blob/develop/docs/examples/infrastructure/README.md

This snippet defines the Docker Compose setup for running Prometheus and Grafana containers. It includes configurations for Prometheus to scrape metrics from Clio and for Grafana to visualize these metrics.

```yaml
services:
  prometheus:
    image: prom/prometheus
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yaml:/etc/prometheus/prometheus.yaml

  grafana:
    image: grafana/grafana
    container_name: grafana
    ports:
      - "3000:3000"
    volumes:
      - ./grafana/datasources.yaml:/etc/grafana/provisioning/datasources/datasources.yaml
      - ./grafana/dashboard_local.yaml:/etc/grafana/provisioning/dashboards/dashboard_local.yaml
      - ./grafana/clio_dashboard.json:/etc/grafana/dashboards/clio_dashboard.json
```

--------------------------------

### Clio Integration Tests Setup

Source: https://github.com/xrplf/clio/blob/develop/tests/integration/CMakeLists.txt

Configures the 'clio_integration_tests' executable, specifies its source files, compile options, include directories, and link libraries. It also sets the runtime output directory.

```cmake
add_executable(clio_integration_tests)

target_sources(
  clio_integration_tests
  PRIVATE data/BackendFactoryTests.cpp
          data/cassandra/BackendTests.cpp
          data/cassandra/BaseTests.cpp
          migration/cassandra/DBRawData.cpp
          migration/cassandra/CassandraMigrationManagerTests.cpp
          migration/cassandra/ExampleTransactionsMigrator.cpp
          migration/cassandra/ExampleObjectsMigrator.cpp
          migration/cassandra/ExampleLedgerMigrator.cpp
          migration/cassandra/ExampleDropTableMigrator.cpp
          util/CassandraDBHelper.cpp
          # Test runner
          TestGlobals.cpp
          Main.cpp
)

# Fix for dwarf5 bug on ci. IS STILL NEEDED???
target_compile_options(clio_options INTERFACE -gdwarf-4)

target_include_directories(clio_integration_tests PRIVATE .)
target_link_libraries(clio_integration_tests PUBLIC clio_testing_common PRIVATE Boost::program_options)
set_target_properties(clio_integration_tests PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
```

--------------------------------

### Clio Installation and Packaging

Source: https://github.com/xrplf/clio/blob/develop/CMakeLists.txt

Handles the installation process for the Clio project and includes specific packaging logic if the 'packaging' option is enabled. This often involves including a separate CMake script for packaging.

```cmake
include(install/install)
if (packaging)
  include(cmake/packaging.cmake) # This file exists only in build runner
endif ()
```

--------------------------------

### Grafana Dashboard Provisioning

Source: https://github.com/xrplf/clio/blob/develop/docs/examples/infrastructure/README.md

This YAML file tells Grafana where to find dashboard JSON files. It enables Grafana to automatically load and display the pre-configured Clio dashboard.

```yaml
apiVersion: 1

providers:
  - name: 'Default Provider'
    orgId: 1
    folder: ''
    type: file
    disableDeletion: false
    editable: true
    options:
      path: /etc/grafana/dashboards
```

--------------------------------

### Run clang-tidy for Static Analysis

Source: https://github.com/xrplf/clio/blob/develop/docs/build-clio.md

Instructions on how to enable and use clang-tidy for static analysis during the Clio build process. This involves a specific Conan install option and optionally setting an environment variable for the clang-tidy binary path.

```sh
conan install .. --output-folder . --build missing --settings build_type=Release -o '&:tests=True' -o '&:lint=True' --profile:all clang

export CLIO_CLANG_TIDY_BIN=/opt/homebrew/opt/llvm/bin/clang-tidy
```

--------------------------------

### Generate Clio API Documentation

Source: https://github.com/xrplf/clio/blob/develop/docs/build-clio.md

Instructions for generating Clio's API documentation using Doxygen. This involves setting specific Conan install options and CMake build targets. Ensure Doxygen 1.12.0 is installed.

```sh
mkdir build && cd build
conan install .. --output-folder . --build missing --settings build_type=Release -o '&:tests=True' -o '&:docs=True'

cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel 8 --target docs
```

--------------------------------

### General Clio Settings

Source: https://github.com/xrplf/clio/blob/develop/docs/config-description.md

General configuration parameters for Clio, including whether to allow starting without ETL, the number of markers for ledger download, and the number of worker threads.

```APIDOC
allow_no_etl:
  Required: True
  Type: boolean
  Default value: `False`
  Constraints: None
  Description: If set to `True`, allows Clio to start without any ETL source.

num_markers:
  Required: False
  Type: int
  Default value: None
  Constraints: The minimum value is `1`. The maximum value is `256`.
  Description: Specifies the number of coroutines used to download the initial ledger.

workers:
  Required: True
  Type: int
  Default value: The number of available CPU cores.
  Constraints: The minimum value is `1`. The maximum value is `4294967295`.
  Description: The number of threads used to process RPC requests.
```

--------------------------------

### Start Migration

Source: https://github.com/xrplf/clio/blob/develop/src/migration/README.md

Command to initiate a migration for a specific migrator. The migration runs only if it hasn't been completed before. The migrator is marked as completed upon successful execution.

```bash
./clio_server --migrate ExampleMigrator  ~/config/migrator.json
```

--------------------------------

### Clio Web Library Configuration

Source: https://github.com/xrplf/clio/blob/develop/src/web/CMakeLists.txt

Configures the 'clio_web' library by adding it and specifying its source files. This is a standard CMake setup for defining a library and its associated code.

```cmake
add_library(clio_web)

target_sources(
  clio_web
  PRIVATE AdminVerificationStrategy.cpp
          dosguard/DOSGuard.cpp
          dosguard/IntervalSweepHandler.cpp
          dosguard/Weights.cpp
          dosguard/WhitelistHandler.cpp
          ng/Connection.cpp
          ng/impl/ErrorHandling.cpp
          ng/impl/ConnectionHandler.cpp
          ng/impl/ServerSslContext.cpp
          ng/Request.cpp
          ng/Response.cpp
          ng/Server.cpp
          ng/SubscriptionContext.cpp
          Resolver.cpp
          SubscriptionContext.cpp
)

target_link_libraries(clio_web PUBLIC clio_util)
```

--------------------------------

### Regular Operation: Awaiting and Reading Values

Source: https://github.com/xrplf/clio/blob/develop/src/util/async/README.md

Demonstrates how to execute a regular operation and retrieve its result. It shows how to get a value directly or wait for an operation to complete and update a variable.

```cpp
auto res = ctx.execute([]() { return 42; });
EXPECT_EQ(res.get().value(), 42);

auto value = 0;
auto res = ctx.execute([&value]() { value = 42; });

res.wait();
ASSERT_EQ(value, 42);
```

--------------------------------

### ExampleDropTableMigrator

Source: https://github.com/xrplf/clio/blob/develop/src/migration/README.md

This migrator demonstrates how to drop a Cassandra table named 'diff'. It serves as a basic example for table manipulation during migration.

```python
class ExampleDropTableMigrator:
    """This migrator drops `diff` table."""
    pass
```

--------------------------------

### Prometheus Configuration for Clio Metrics

Source: https://github.com/xrplf/clio/blob/develop/docs/examples/infrastructure/README.md

This YAML configuration specifies how Prometheus should discover and scrape metrics from a Clio instance. It includes settings for the target Clio instance and authorization details.

```yaml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'clio'
    static_configs:
      - targets: ['host.docker.internal:5000'] # Replace with your Clio instance address
        labels:
          instance: 'clio-instance-1'
    # Add authorization if needed, e.g., basic_auth or bearer_token
```

--------------------------------

### Build Clio with Docker

Source: https://github.com/xrplf/clio/blob/develop/docs/build-clio.md

Steps to build Clio using Docker, which avoids local dependency installations. This includes pulling the Docker image, cloning the Clio repository, and running the build commands.

```sh
docker run -it ghcr.io/xrplf/clio-ci:a446d85297b3006e6d2c4dc7640368f096afecf5
git clone https://github.com/XRPLF/clio
mkdir build && cd build
conan install .. --output-folder . --build missing --settings build_type=Release -o '&:tests=True'
cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel 8 # or without the number if you feel extra adventurous
```

--------------------------------

### Build Clio with Code Coverage

Source: https://github.com/xrplf/clio/blob/develop/docs/build-clio.md

Command to build Clio with code coverage enabled. This involves including the coverage option in the conan install command and then building the test executable with coverage enabled.

```sh
mkdir build && cd build
conan install .. --output-folder . --build missing --settings build_type=Release -o '&:tests=True' -o '&:coverage=True'
cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release ..
make clio_tests-ccov
```

--------------------------------

### Build Clio with Custom libxrpl

Source: https://github.com/xrplf/clio/blob/develop/docs/build-clio.md

Guide for building Clio with a custom version of libxrpl, useful for developing compatibility with specific rippled branches or amendments. It involves exporting a custom Conan package and patching the Clio conanfile.py.

```sh
git clone https://github.com/XRPLF/rippled/
cd rippled
git checkout 2.5.0-rc1

conan export . --user=my --channel=feature
```

```py
# ... (excerpt from conanfile.py)
requires = [
    'boost/1.83.0',
    'cassandra-cpp-driver/2.17.0',
    'fmt/10.1.1',
    'protobuf/3.21.9',
    'grpc/1.50.1',
    'openssl/1.1.1v',
    'xrpl/2.5.0-rc1@my/feature', # Use your exported version here
    'zlib/1.3.1',
    'libbacktrace/cci.20210118'
]
```

--------------------------------

### Clio Migration Library Configuration

Source: https://github.com/xrplf/clio/blob/develop/src/migration/CMakeLists.txt

Configures the 'clio_migration' library by adding it to the build and specifying its source files and linked libraries. This setup is crucial for the migration functionalities within the Clio project.

```cmake
add_library(clio_migration)

target_sources(
  clio_migration PRIVATE MigrationApplication.cpp impl/MigrationManagerFactory.cpp MigratorStatus.cpp
                         cassandra/impl/ObjectsAdapter.cpp cassandra/impl/TransactionsAdapter.cpp
)

target_link_libraries(clio_migration PRIVATE clio_util clio_data)
```

--------------------------------

### Clio Test Suite Configuration

Source: https://github.com/xrplf/clio/blob/develop/tests/unit/CMakeLists.txt

Configures the Clio test executable, including discovering tests, setting compile options, linking libraries, and managing runtime output directory. It also includes conditional setup for generating code coverage reports using gcovr.

```cmake
gtest_discover_tests(clio_tests DISCOVERY_TIMEOUT 90)

# Fix for dwarf5 bug on ci
target_compile_options(clio_options INTERFACE -gdwarf-4)

target_include_directories(clio_tests PRIVATE .)
target_link_libraries(clio_tests PUBLIC clio_testing_common)
set_target_properties(clio_tests PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})

# Generate `coverage_report` target if coverage is enabled
if (coverage)
  if (DEFINED CODE_COVERAGE_REPORT_FORMAT)
    set(CODE_COVERAGE_FORMAT ${CODE_COVERAGE_REPORT_FORMAT})
  else ()
    set(CODE_COVERAGE_FORMAT html-details)
  endif ()

  if (DEFINED CODE_COVERAGE_TESTS_ARGS)
    set(TESTS_ADDITIONAL_ARGS ${CODE_COVERAGE_TESTS_ARGS})
    separate_arguments(TESTS_ADDITIONAL_ARGS)
  else ()
    set(TESTS_ADDITIONAL_ARGS "")
  endif ()

  set(GCOVR_ADDITIONAL_ARGS --exclude-throw-branches -s)

  setup_target_for_coverage_gcovr(
    NAME
    coverage_report
    FORMAT
    ${CODE_COVERAGE_FORMAT}
    EXECUTABLE
    clio_tests
    EXECUTABLE_ARGS
    --gtest_brief=1
    ${TESTS_ADDITIONAL_ARGS}
    EXCLUDE
    "tests"
    "src/data/cassandra"
    "src/data/CassandraBackend.hpp"
    "src/data/BackendFactory.*"
    DEPENDENCIES
    clio_tests
  )
endif ()
```

--------------------------------

### Project Configuration and Initialization

Source: https://github.com/xrplf/clio/blob/develop/docs/doxygen-awesome-theme/header.html

This snippet shows common project configuration variables and initialization calls for features like dark mode, search, and interactive table of contents.

```html
$projectname: $title $title    var page_layout=1; $treeview $search $mathjax $darkmode  $extrastylesheet DoxygenAwesomeDarkModeToggle.init() DoxygenAwesomeInteractiveToc.init()

![Logo]($relpath^$projectlogo)

$projectname $projectnumber

$projectbrief

$projectbrief

$searchbox

$searchbox
```

--------------------------------

### Configure Clio to Start Without rippled Node

Source: https://github.com/xrplf/clio/blob/develop/docs/trouble_shooting.md

Allows Clio to start even if it cannot reach the configured rippled node. This is achieved by setting the `allow_no_etl` configuration option to `true` in Clio's configuration file. This is useful for development or testing scenarios where a rippled node might not be available.

```text
"allow_no_etl": true
```

--------------------------------

### ExampleLedgerMigrator

Source: https://github.com/xrplf/clio/blob/develop/src/migration/README.md

This migrator illustrates migrating data without requiring a full table scan. It involves creating an index table `ledger_example` to map ledger sequences to account hashes, optimizing data access.

```python
class ExampleLedgerMigrator:
    """This migrator shows how to migrate data when we don't need to do full table scan. This migrator creates an index table `ledger_example` which maintains the map of ledger sequence and its account hash."""
    pass
```

--------------------------------

### Go Snapshot Tool Build Configuration

Source: https://github.com/xrplf/clio/blob/develop/tools/snapshot/CMakeLists.txt

Configures the build process for the Clio snapshot tool using CMake. It sets up Go environment variables, identifies Go source files, and defines paths for protobuf definitions and generated Go code.

```cmake
set(GO_EXECUTABLE "go")
set(GO_SOURCE_DIR "${CMAKE_SOURCE_DIR}/tools/snapshot")
set(PROTO_INC_DIR "${xrpl_PACKAGE_FOLDER_RELEASE}/include/xrpl/proto")
set(PROTO_SOURCE_DIR "${PROTO_INC_DIR}/org/xrpl/rpc/v1/")
set(GO_OUTPUT "${CMAKE_BINARY_DIR}/clio_snapshot")
file(GLOB_RECURSE GO_SOURCES ${GO_SOURCE_DIR}/*.go)

set(PROTO_FILES
    ${PROTO_SOURCE_DIR}/xrp_ledger.proto ${PROTO_SOURCE_DIR}/ledger.proto ${PROTO_SOURCE_DIR}/get_ledger.proto
    ${PROTO_SOURCE_DIR}/get_ledger_entry.proto ${PROTO_SOURCE_DIR}/get_ledger_data.proto
    ${PROTO_SOURCE_DIR}/get_ledger_diff.proto
)

execute_process(COMMAND go env GOPATH OUTPUT_VARIABLE GOPATH_VALUE OUTPUT_STRIP_TRAILING_WHITESPACE)

# Target Go package path
set(GO_IMPORT_PATH "org/xrpl/rpc/v1")

# Initialize the options strings
set(GO_OPTS "")
set(GRPC_OPTS "")

# Loop through each proto file
foreach (proto ${PROTO_FILES})
  get_filename_component(proto_filename ${proto} NAME)

  # Build the --go_opt and --go-grpc_opt mappings
  set(GO_OPTS ${GO_OPTS} --go_opt=M${GO_IMPORT_PATH}/${proto_filename}=${GO_IMPORT_PATH})
  set(GRPC_OPTS ${GRPC_OPTS} --go-grpc_opt=M${GO_IMPORT_PATH}/${proto_filename}=${GO_IMPORT_PATH})
endforeach ()
```

--------------------------------

### Protobuf to Go Code Generation

Source: https://github.com/xrplf/clio/blob/develop/tools/snapshot/CMakeLists.txt

Generates Go code from Protocol Buffer definitions using `protoc`. It applies Go and gRPC specific options based on the import path and proto file names, ensuring correct package generation.

```cmake
foreach (proto ${PROTO_FILES})
  get_filename_component(proto_name ${proto} NAME_WE)
  add_custom_command(
    OUTPUT ${GO_SOURCE_DIR}/${GO_IMPORT_PATH}/${proto_name}.pb.go
    COMMAND
      protoc ${GO_OPTS} ${GRPC_OPTS} --go-grpc_out=${GO_SOURCE_DIR} -I${PROTO_INC_DIR} ${proto}
      --plugin=${GOPATH_VALUE}/bin/protoc-gen-go --plugin=${GOPATH_VALUE}/bin/protoc-gen-go-grpc
      --go_out=${GO_SOURCE_DIR}/
    DEPENDS ${proto}
    COMMENT "Generating Go code for ${proto}"
    VERBATIM
  )

  list(APPEND GENERATED_GO_FILES ${GO_SOURCE_DIR}/${GO_IMPORT_PATH}/${proto_name}.pb.go)
endforeach ()
```

--------------------------------

### Ledger Range Table Schema

Source: https://github.com/xrplf/clio/blob/develop/src/data/README.md

Defines the 'ledger_range' table, which indicates the starting and ending sequence numbers of the ledger versions stored on a Cassandra node. It contains two records: one for the starting range (is_latest = false) and one for the stopping range (is_latest = true).

```SQL
CREATE TABLE clio.ledger_range (
 is_latest boolean PRIMARY KEY,  # Whether this sequence is the stopping range
 sequence bigint                 # The sequence number of the starting/stopping range
) ...
```

--------------------------------

### Run Clio Integration Tests

Source: https://github.com/xrplf/clio/blob/develop/tests/integration/README.md

Executes all database integration tests for the Clio project after building it. This command assumes a local Cassandra/ScyllaDB cluster is running and accessible.

```bash
# Build Clio as normal first
./clio_integration_tests
```

--------------------------------

### Clio Configuration: Ledger Sequence

Source: https://github.com/xrplf/clio/blob/develop/docs/configure-clio.md

Specifies the starting and ending ledger sequences for Clio's ETL process. 'start_sequence' defines the first ledger to extract if the database is empty, while 'finish_sequence' sets the upper limit. If 'start_sequence' is present and the database is not empty, an exception is thrown. Absence of 'start_sequence' with an empty database starts ETL with the next validated ledger.

```json
{
    "start_sequence": 12345,
    "finish_sequence": 54321
}
```

--------------------------------

### Clio Benchmark Executable Build Configuration

Source: https://github.com/xrplf/clio/blob/develop/benchmarks/CMakeLists.txt

Configures the clio_benchmark executable using CMake. It defines the source files, includes necessary directories, and links against required libraries like clio_etl and Google Benchmark.

```cmake
add_executable(clio_benchmark)

target_sources(
  clio_benchmark
  PRIVATE # Common
          Main.cpp
          Playground.cpp
          # ExecutionContext
          util/async/ExecutionContextBenchmarks.cpp
)

include(deps/gbench)

target_include_directories(clio_benchmark PRIVATE .)
target_link_libraries(clio_benchmark PUBLIC clio_etl benchmark::benchmark_main)
set_target_properties(clio_benchmark PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
```

--------------------------------

### SystemExecutionContext Overview

Source: https://github.com/xrplf/clio/blob/develop/src/util/async/README.md

Explains the SystemExecutionContext, a system-wide, single-threaded context for fire-and-forget operations and scheduling timers externally, as used by SyncExecutionContext.

```cpp
This context of 1 thread is always readily available system-wide and can be used for
- fire and forget operations where it makes no sense to create an entirely new context for them
- as an external context for scheduling timers (used by SyncExecutionContext automatically)
```

--------------------------------

### Example Log Channel Override

Source: https://github.com/xrplf/clio/blob/develop/docs/logging.md

Demonstrates how to override the log level for a specific channel, in this case, setting the 'Backend' channel to log only 'fatal' messages.

```json
{
  "channel": "Backend",
  "log_level": "fatal"
}
```

--------------------------------

### Grafana Datasource Configuration

Source: https://github.com/xrplf/clio/blob/develop/docs/examples/infrastructure/README.md

This YAML file configures Grafana to use Prometheus as a data source. It allows Grafana to query metrics collected by Prometheus.

```yaml
apiVersion: 1

datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
```

--------------------------------

### ExampleTransactionsMigrator

Source: https://github.com/xrplf/clio/blob/develop/src/migration/README.md

This migrator demonstrates migrating transaction-related data. It employs `TransactionsScanner` for parallel full scans of the `transactions` table and creates an index table `tx_index_example` to track transaction hashes and types.

```python
class ExampleTransactionsMigrator:
    """This migrator shows how to migrate transactions related data. It uses `TransactionsScanner` to proceed the `transactions` table full scan in parallel. It creates an index table `tx_index_example` which tracks the transaction hash and its according transaction type."""
    pass
```

--------------------------------

### Scheduled Operation: Handling an Exception

Source: https://github.com/xrplf/clio/blob/develop/src/util/async/README.md

Shows how exceptions thrown within a scheduled operation are caught and returned. The example demonstrates retrieving the error message from the `ExecutionError` struct.

```cpp
auto res =
    ctx.scheduleAfter(1s, []([[maybe_unused]] auto stopRequested, auto cancelled) {
        if (not cancelled)
            throw std::runtime_error("test");
        return 0;
    });

auto const err = res.get().error();
EXPECT_TRUE(err.message.ends_with("test"));
EXPECT_TRUE(std::string{err}.ends_with("test"));
```

--------------------------------

### Conan Build Presets

Source: https://github.com/xrplf/clio/blob/develop/docker/ci/README.md

Lists the available Conan preset profiles for building the Clio project. These presets simplify the build process by pre-configuring compiler and sanitizer options.

```APIDOC
Conan Profiles:
  clang
    - Uses Clang compiler.
  gcc
    - Uses GCC compiler.

Sanitizer Options (can be appended to compiler profiles):
  asan
    - Enables AddressSanitizer.
  tsan
    - Enables ThreadSanitizer.
  ubsan
    - Enables UndefinedBehaviorSanitizer.

Example Usage:
  --profile:all clang.asan
  --profile:all gcc.tsan
```

--------------------------------

### Run Requests Gun

Source: https://github.com/xrplf/clio/blob/develop/tools/requests_gun/README.md

Execute the Requests Gun tool with command-line arguments. Use `--help` to view all available options for configuring the tool, such as specifying the request file, target server, and requests per second.

```bash
requests_gun --help
```

--------------------------------

### ExampleObjectsMigrator

Source: https://github.com/xrplf/clio/blob/develop/src/migration/README.md

This migrator focuses on migrating ledger states data. It utilizes `ObjectsScanner` for parallel full scans and counts ACCOUNT_ROOT entries, showcasing efficient state data migration.

```python
class ExampleObjectsMigrator:
    """This migrator shows how to migrate ledger states related data. It uses `ObjectsScanner` to proceed the full scan in parallel. It counts the number of ACCOUNT_ROOT."""
    pass
```

--------------------------------

### API Versioning Configuration

Source: https://github.com/xrplf/clio/blob/develop/docs/run-clio.md

Configures the minimum, maximum, and default API versions for Clio. These settings allow for flexible API version management and fallback to hardcoded defaults if not specified or if values are out of range.

```json
{
    "api_version": {
        "min": 1,
        "max": 2,
        "default": 1
    }
}
```

--------------------------------

### Create Conan Lockfile

Source: https://github.com/xrplf/clio/blob/develop/docs/build-clio.md

Command to create a Conan lockfile for reproducible dependencies. It locks the current state of dependencies, including enabling tests and benchmarks.

```bash
conan lock create . -o '&:tests=True' -o '&:benchmark=True'
```

--------------------------------

### Conan Global Configuration for Speed

Source: https://github.com/xrplf/clio/blob/develop/docs/build-clio.md

Configuration to enhance the speed of Conan package downloads and uploads by setting parallel job counts for download and upload operations based on the system's CPU count.

```text
core.download:parallel={{os.cpu_count()}}
core.upload:parallel={{os.cpu_count()}}
```

--------------------------------

### Clio Webserver Tests

Source: https://github.com/xrplf/clio/blob/develop/tests/unit/CMakeLists.txt

This snippet lists C++ test files for Clio's webserver components, including admin verification, DOS guard mechanisms, request/response handling, and server implementation details.

```cpp
#include "web/AdminVerificationTests.cpp"
#include "web/dosguard/DOSGuardTests.cpp"
#include "web/dosguard/IntervalSweepHandlerTests.cpp"
#include "web/dosguard/WeightsTests.cpp"
#include "web/dosguard/WhitelistHandlerTests.cpp"
#include "web/impl/ErrorHandlingTests.cpp"
#include "web/ng/ResponseTests.cpp"
#include "web/ng/RequestTests.cpp"
#include "web/ng/RPCServerHandlerTests.cpp"
#include "web/ng/ServerTests.cpp"
#include "web/ng/SubscriptionContextTests.cpp"
#include "web/ng/impl/ConnectionHandlerTests.cpp"
#include "web/ng/impl/ErrorHandlingTests.cpp"
#include "web/ng/impl/HttpConnectionTests.cpp"
#include "web/ng/impl/ServerSslContextTests.cpp"
#include "web/ng/impl/WsConnectionTests.cpp"
#include "web/RPCServerHandlerTests.cpp"
#include "web/ServerTests.cpp"
#include "web/SubscriptionContextTests.cpp"
```

--------------------------------

### Querying NFT Owner History

Source: https://github.com/xrplf/clio/blob/develop/src/data/README.md

An example SQL query to find the owner of a specific NFT at a given ledger version and check if it was burned. It retrieves the most recent record for the token up to the specified ledger sequence.

```sql
SELECT * FROM nf_tokens
WHERE token_id = N AND seq <= Y
ORDER BY seq DESC LIMIT 1;
```

--------------------------------

### Clio Grafana Dashboard JSON

Source: https://github.com/xrplf/clio/blob/develop/docs/examples/infrastructure/README.md

This is a JSON file containing the definition of a Grafana dashboard specifically designed to visualize Clio metrics. It includes panels for various metrics like requests, errors, and performance.

```json
{
  "__inputs": [],
  "__requires": [
    {
      "type": "grafana",
      "id": "grafana",
      "name": "Grafana",
      "version": "8.0.0"
    },
    {
      "type": "datasource",
      "id": "prometheus",
      "name": "Prometheus",
      "version": "1.0.0"
    }
  ],
  "annotations": {
    "list": []
  },
  "editable": true,
  "gnetId": null,
  "graphTooltip": 0,
  "id": null,
  "links": [],
  "panels": [
    {
      "datasource": {
        "type": "prometheus",
        "uid": "prometheus"
      },
      "gridPos": {
        "h": 8,
        "w": 24,
        "x": 0,
        "y": 0
      },
      "id": 2,
      "targets": [
        {
          "datasource": {
            "type": "prometheus",
            "uid": "prometheus"
          },
          "editorMode": "builder",
          "expr": "clio_requests_total",
          "legendFormat": "{{method}} {{path}}",
          "refId": "A"
        }
      ],
      "title": "Total Requests",
      "type": "timeseries"
    }
  ],
  "schemaVersion": 37,
  "style": "dark",
  "tags": [],
  "templating": {
    "list": []
  },
  "time": {
    "from": "now-1h",
    "to": "now"
  },
  "timepicker": {},
  "timezone": "",
  "title": "Clio Dashboard",
  "uid": "clio-dashboard-example",
  "version": 1
}
```

--------------------------------

### Scheduled Operation: Get Value After Stopping

Source: https://github.com/xrplf/clio/blob/develop/src/util/async/README.md

Illustrates scheduling an operation that waits for a stop signal, then requesting its stop, and finally retrieving its return value. This shows how operations that are stopped before completion handle value retrieval.

```cpp
auto res = ctx.scheduleAfter(1ms, [](auto stopRequested) {
    while (not stopRequested)
        ;

    return 42;
});

res.requestStop();
```

--------------------------------

### Conan Profile Selection for Clio Builds

Source: https://github.com/xrplf/clio/blob/develop/docker/ci/README.md

Demonstrates how to select Conan profiles for building Clio with different compilers and sanitizers. This allows for flexible build configurations, including AddressSanitizer (ASan), ThreadSanitizer (TSan), and UndefinedBehaviorSanitizer (UBSan).

```shell
# Example of selecting a profile with GCC and ThreadSanitizer
conan install . --profile:all gcc.tsan

# Example of selecting a profile with Clang and AddressSanitizer
conan install . --profile:all clang.asan
```

--------------------------------

### Build Clio with Ninja

Source: https://github.com/xrplf/clio/blob/develop/docs/build-clio.md

Command to build Clio using the Ninja build system instead of the default Make, by passing the -GNinja flag to the CMake configuration step.

```sh
mkdir build && cd build
cmake -GNinja -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel 8
```

--------------------------------

### Git Workflow: Rebase and Squash Commits

Source: https://github.com/xrplf/clio/blob/develop/CONTRIBUTING.md

Guides through rebasing and squashing commits for a clean commit history before submitting a pull request. It includes updating the local develop branch, checking out the feature branch, interactive rebase, and squashing commits.

```git
# Create a backup of your branch
git branch <your feature branch>_bk

# Rebase and squash commits into one
git checkout develop
git pull origin develop
git checkout <your feature branch>
git rebase -i develop

```

```git
# You should now have a single commit on top of a commit in `develop`
git log

```

```git
# Use the same commit message as you did above
git commit -m 'Your message'
git rebase --continue

```

```git
# Sign the commit with your GPG key, and push your changes
git commit --amend -S
git push --force

```

--------------------------------

### Backend Interface and Factory (C++)

Source: https://github.com/xrplf/clio/blob/develop/src/data/README.md

Illustrates the C++ interfaces for database backends. The BackendInterface.h defines virtual methods for database operations, and BackendFactory.h uses the Factory pattern to instantiate specific database implementations based on configuration.

```c++
// In BackendInterface.h
class BackendInterface {
public:
    virtual ~BackendInterface() = default;
    // Virtual methods for database operations...
};

// In BackendFactory.h
#include "BackendInterface.h"
#include <string>

class BackendFactory {
public:
    static std::unique_ptr<BackendInterface> createBackend(const std::string& type);
};

```

--------------------------------

### rippled Configuration: gRPC and WebSocket Ports

Source: https://github.com/xrplf/clio/blob/develop/docs/configure-clio.md

Example configuration snippet for rippled, showing how to open ports for gRPC and unencrypted WebSocket connections. The 'port_websocket' and 'port_grpc' sections define the listening ports and associated IP addresses for Clio to connect to.

```APIDOC
port_websocket
  port: 51234
  ip: 127.0.0.1

port_grpc
  port: 5005
  ip: 127.0.0.1
  secure_gateway
    ip: 127.0.0.1
```

--------------------------------

### Check Clio Cache Status

Source: https://github.com/xrplf/clio/blob/develop/docs/trouble_shooting.md

Checks the status of Clio's internal cache by querying the server information. It retrieves `is_full` and `is_enabled` status. `is_full` being false indicates the cache is still loading, while `is_enabled` being false suggests the cache is disabled or corrupted.

```sh
curl -v -d '{"method":"server_info", "params":[{}]}' 127.0.0.1:51233|python3 -m json.tool|grep is_full
```

```sh
curl -v -d '{"method":"server_info", "params":[{}]}' 127.0.0.1:51233|python3 -m json.tool|grep is_enabled
```
Tokens:
Raw