Skip to content

po4yka/RIPDPI / .agents/skills/protobuf-datastore

protobuf-datastore

Verified

Kotlin mapping for the AppSettings proto-backed DataStore: UI-state and native-preferences conversion. Use when adding or reading an app-settings field. Removing a field: use protobuf-schema-evolution first.

FileKindSize
SKILL.mdskill md4.8 KB
---
name: protobuf-datastore
description: 'Kotlin mapping for the AppSettings proto-backed DataStore: UI-state and native-preferences conversion. Use when adding or reading an app-settings field. Removing a field: use protobuf-schema-evolution first.'
---

# Protobuf DataStore

## Overview

RIPDPI persists all app settings as a single Protobuf message (`AppSettings`) stored via Jetpack DataStore. The schema is the source of truth for all configurable values.

## Key Files

| File | Purpose |
|------|---------|
| `core/data/model/src/main/proto/app_settings.proto` | Schema definition for persisted app settings |
| `core/data/settings/src/main/kotlin/com/poyka/ripdpi/data/AppSettingsSerializer.kt` | Serializer with default values |
| `core/data/settings/src/main/kotlin/com/poyka/ripdpi/data/AppDataStore.kt` | DataStore extension property |
| `core/engine/.../core/RipDpiProxyPreferences.kt` | Proto -> native preferences conversion |
| `app/.../ui/screens/settings/SettingsViewModel.kt` | Proto -> UI state conversion |
| `app/.../ui/screens/connection/ConnectionViewModel.kt` | Config draft validation and persistence |

## Adding a New Setting

1. **Add field to proto schema** (`app_settings.proto`):
   ```protobuf
   bool your_new_setting = <next_field_number>;
   ```
   Use next available field number. Never reuse or renumber existing fields.

2. **Set default in serializer** (`AppSettingsSerializer.kt`):
   ```kotlin
   override val defaultValue: AppSettings = AppSettings.newBuilder()
       // ... existing defaults ...
       .setYourNewSetting(false)
       .build()
   ```

3. **Expose in UI state** (`SettingsUiState` or `ConnectionDraft`):
   ```kotlin
   data class SettingsUiState(
       // ... existing fields ...
       val yourNewSetting: Boolean = false,
   )
   ```

4. **Map in conversion function** (`AppSettings.toUiState()` or `toConfigDraft()`):
   ```kotlin
   fun AppSettings.toUiState() = SettingsUiState(
       // ... existing mappings ...
       yourNewSetting = this.yourNewSetting,
   )
   ```

5. **Persist changes** via DataStore:
   ```kotlin
   context.settingsStore.updateData { current ->
       current.toBuilder().setYourNewSetting(value).build()
   }
   ```

## Reading Settings

```kotlin
// Reactive (preferred): Flow<AppSettings>
context.settingsStore.data.collect { settings ->
    val value = settings.yourSetting
}

// In ViewModel: combine with other flows
val uiState = combine(application.settingsStore.data, otherFlow) { settings, other ->
    UiState(setting = settings.yourSetting, /* ... */)
}.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), UiState())
```

## Proto Field Groups

| Group | Fields | Notes |
|-------|--------|-------|
| General | app_theme, ripdpi_mode, dns_ip, ipv6_enable | Mode is "vpn" or "proxy" |
| Command mode | enable_cmd_settings, cmd_args | Raw CLI args for command-line mode of the native RIPDPI proxy |
| Proxy | proxy_ip, proxy_port, max_connections, buffer_size | Defaults: 127.0.0.1:1080 |
| Desync | default_ttl, custom_ttl, fake_ttl, fake_sni, fake_offset, oob_data, drop_sack, etc. | `desync_method` and `split_position` are reserved/removed; grep `app_settings.proto` for the current field list |
| Protocols | desync_http, desync_https, desync_udp | Bool flags for which protocols to desync |
| Hosts | hosts_mode, hosts_blacklist, hosts_whitelist | Mode: disable/blacklist/whitelist |
| TLS | tls_minor_enabled, etc. | `tlsrec_*` names are reserved/removed (TLS record splitting is a desync chain step now); grep `app_settings.proto` for the current field list |
| App | onboarding_complete, biometric_enabled, backup_pin | App lifecycle settings |

## Preferences Conversion (Proto -> Native)

`RipDpiProxyPreferences.fromSettingsStore(context)` reads the proto and creates either:
- `RipDpiProxyCmdPreferences(args)` if `enable_cmd_settings` is true
- `RipDpiProxyUIPreferences(...)` mapping all 27 proxy parameters

## Diagnostics Interaction

- `enable_cmd_settings = true` is a hard stop for automatic probing/audit. Those workflows require UI-config JSON so they can launch isolated strategy trials.
- If a change touches diagnostics availability or recommendation flow, also inspect `core:diagnostics` and the diagnostics UI layer. The proto flag alone is not the whole behavior.

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Reusing proto field numbers | Always use next available number; old numbers are reserved forever |
| Forgetting default in serializer | Every field needs an explicit default in `AppSettingsSerializer.defaultValue` |
| Reading DataStore on main thread | Always use `Flow.collect` or `updateData` (both suspend) |
| Not updating `toUiState()` mapping | New fields must be mapped in all conversion functions |
| String enums without validation | Proto stores strings ("vpn", "proxy") -- validate on read |
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall