Libraries

Documentation for shared libraries in bidder-libraries/.

Context Library

Unified DSL for establishing caller context in coroutine-based applications.

Location: bidder-libraries/context/

Module Structure

context/
└── src/main/kotlin/ru/savbros/bidder/common/context/
    ├── AuthContextUtil.kt       # DSL entry point
    ├── Caller.kt                # Sealed interface
    ├── CallerContext.kt         # Coroutine context element
    ├── CallerContextBuilder.kt  # DSL builder
    └── model/
        ├── UserPrincipal.kt
        └── SystemPrincipal.kt

Caller Types

sealed interface Caller {
    data class User(val principal: UserPrincipal) : Caller
    data class System(
        val principal: SystemPrincipal,
        val initiatedBy: UserPrincipal? = null  // Audit trail
    ) : Caller
}

DSL Usage

// Controllers (HTTP requests)
suspend fun create(...) = withCallerContext({ fromSecurityContext() }) {
    service.create(getCurrentUser().userId, ...)
}

// Scheduled jobs
withCallerContext({ asSystem("CampaignSync") }) {
    syncService.syncAll()
}

// Testing
withCallerContext({ asUser(testPrincipal) }) {
    // test code
}

Builder Methods

Method	Purpose
`fromSecurityContext()`	Extract user from JWT (ReactiveSecurityContextHolder)
`asSystem(name)`	System caller for internal/scheduled operations
`asUser(principal)`	Explicit user principal (testing)
`asCaller(caller)`	Pre-constructed caller (advanced)

Utility Functions

Function	Returns	Description
`getCaller()`	`Caller`	Current caller (sealed type)
`getCurrentUser()`	`UserPrincipal`	User principal
`isSystemCall()`	`Boolean`	Check if system call
`getCallingSubsystem()`	`SystemPrincipal?`	System principal if system call

Authorization Integration

AuthorizationManager uses isSystemCall() to skip auth for trusted internal calls
SubjectFactory uses getCurrentUser() to create authorization subjects
System calls bypass user-level authorization

Role-Model Library

Custom RBAC framework with Resources, Actions, Subjects, and Policies.

Location: bidder-libraries/role-model/

Full documentation: bidder-libraries/role-model/ROLE_MODEL_USER_MANUAL.md

Quick Reference

// Define resource
class OrganizationResource(override val id: UUID) : Resource

// Define action
enum class OrganizationAction : Action {
    VIEW, EDIT, DELETE
}

// Authorize
authorizationManager.authorize(OrganizationAction.VIEW, resourceRef)

State Machine Library

Type-safe, coroutine-based state machine framework.

Location: bidder-libraries/state-machine/

Full documentation: bidder-libraries/state-machine/STATE_MACHINE_USER_MANUAL.md

Quick Reference

val machine = stateMachine<State, Event, Entity> {
    state(State.PENDING) {
        on(Event.CONFIRM) {
            target(State.CONFIRMED)
            guard { entity -> entity.isValid }
            action { entity -> notify(entity) }
        }
    }
}

Features:

Type-safe state/event definitions
Guards and actions for transitions
Nested states support
Persistence via StatePersister
History tracking via TransitionHistoryWriter

Money Library

Type-safe money value classes.

Location: bidder-libraries/money/

val kopecks = Kopecks(10000)
val rubles = kopecks.toRubles()  // Rubles(100)

Weekly Activity Library

Weekly activity bitmap for recurring schedules.

Location: bidder-libraries/weekly-activity/

Represents which hours of each day are active using a bitmap structure.

Errors Library

Centralized error handling.

Location: bidder-libraries/errors/

// Throw error
coreError("Message", "Локализованное сообщение")

// Require not null
val value = coreRequireNotNull(nullable, "Not found", "Не найдено")

// Validation
throw ValidationException(listOf(Violation("field", "invalid", "некорректно")))

Util Library

Common utilities and extension functions.

Location: bidder-libraries/util/

asResponseEntity() - wrap in ResponseEntity
receiveOne() - select first non-null parameter handler
createAliasFromName() - transliterate to URL-safe alias