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.

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

FilePurpose
core/data/model/src/main/proto/app_settings.protoSchema definition for persisted app settings
core/data/settings/src/main/kotlin/com/poyka/ripdpi/data/AppSettingsSerializer.ktSerializer with default values
core/data/settings/src/main/kotlin/com/poyka/ripdpi/data/AppDataStore.ktDataStore extension property
core/engine/.../core/RipDpiProxyPreferences.ktProto -> native preferences conversion
app/.../ui/screens/settings/SettingsViewModel.ktProto -> UI state conversion
app/.../ui/screens/connection/ConnectionViewModel.ktConfig draft validation and persistence

Adding a New Setting

  1. Add field to proto schema (app_settings.proto):

    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):

    override val defaultValue: AppSettings = AppSettings.newBuilder()
        // ... existing defaults ...
        .setYourNewSetting(false)
        .build()
    
  3. Expose in UI state (SettingsUiState or ConnectionDraft):

    data class SettingsUiState(
        // ... existing fields ...
        val yourNewSetting: Boolean = false,
    )
    
  4. Map in conversion function (AppSettings.toUiState() or toConfigDraft()):

    fun AppSettings.toUiState() = SettingsUiState(
        // ... existing mappings ...
        yourNewSetting = this.yourNewSetting,
    )
    
  5. Persist changes via DataStore:

    context.settingsStore.updateData { current ->
        current.toBuilder().setYourNewSetting(value).build()
    }
    

Reading Settings

// 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

GroupFieldsNotes
Generalapp_theme, ripdpi_mode, dns_ip, ipv6_enableMode is "vpn" or "proxy"
Command modeenable_cmd_settings, cmd_argsRaw CLI args for command-line mode of the native RIPDPI proxy
Proxyproxy_ip, proxy_port, max_connections, buffer_sizeDefaults: 127.0.0.1:1080
Desyncdefault_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
Protocolsdesync_http, desync_https, desync_udpBool flags for which protocols to desync
Hostshosts_mode, hosts_blacklist, hosts_whitelistMode: disable/blacklist/whitelist
TLStls_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
Apponboarding_complete, biometric_enabled, backup_pinApp 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

MistakeFix
Reusing proto field numbersAlways use next available number; old numbers are reserved forever
Forgetting default in serializerEvery field needs an explicit default in AppSettingsSerializer.defaultValue
Reading DataStore on main threadAlways use Flow.collect or updateData (both suspend)
Not updating toUiState() mappingNew fields must be mapped in all conversion functions
String enums without validationProto 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: 321kUpdated 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: 197kUpdated 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: 197kUpdated 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: 197kUpdated Claude CodeCodexVerifiedInstall