Tutorials/Auditing

Auditing with entity callbacks

Most tables carry createdAt and updatedAt, and service code should not set them by hand. An EntityCallback runs on the write path. Entities are immutable, so the callback returns a changed copy instead of mutating the one it was given.

Series · The Storm way4 min readKotlin

01The task

Stamp audit timestamps on every insert and update of an owner, refuse an owner without a last name, and keep both out of the service code that writes owners.

02The audit callback

EntityCallback<E> is typed to the entity it applies to, with a hook before and after each insert, update, upsert and remove. The before-hooks for insert, update and upsert return the entity that is written:

AuditCallback.kt Kotlin · Storm
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
data class Owner(
    @PK val id: Int = 0,
    val firstName: String,
    val lastName: String,
    @Persist(updatable = false) val createdAt: Instant? = null,
    val updatedAt: Instant? = null,
) : Entity<Int>

// A before-hook returns the entity to write
class AuditCallback : EntityCallback<Owner> {

    override fun beforeInsert(entity: Owner): Owner {
        val now = Instant.now()
        return entity.copy(createdAt = now, updatedAt = now)
    }

    override fun beforeUpdate(entity: Owner): Owner =
        entity.copy(updatedAt = Instant.now())
}

@Persist(updatable = false) keeps createdAt out of every UPDATE, so an update from a form that does not carry it leaves the stored value alone. An upsert runs beforeInsert unless the callback overrides beforeUpsert, and its update branch skips createdAt for the same reason.

03Registration

Register the callback on a template. withEntityCallback returns a new template that applies it; the original is unchanged:

Setup.kt Kotlin · Storm
1
2
3
4
5
// A new template with the callback; the original is unchanged
val orm = dataSource.orm.withEntityCallback(AuditCallback())

val owner = orm insert Owner(firstName = "Betty", lastName = "Davis")
// owner.createdAt and owner.updatedAt are set

The entity can declare it instead, with @EntityCallbacks(AuditCallback::class), and then it applies on every template. With the Spring Boot starter a callback bean is registered for you; the Ktor plugin takes entityCallback(AuditCallback()) in its configuration.

The after-hooks receive what the call returns: insert passes the entity as sent, without a generated id; insertAndFetchId adds the id; insertAndFetch, which Kotlin's orm insert calls, passes the row as read back.

The update() query builder sets columns on rows it does not read, so no callback fires for it. Write set(Owner_.updatedAt, ...) into the builder yourself.

04Validation

A before-hook runs before the statement, so it can also refuse a write with an error in domain terms. Several callbacks fire in the order they were registered:

Callbacks.kt Kotlin · Storm
1
2
3
4
5
6
7
8
9
10
11
12
// A before-hook runs ahead of the statement, so it can refuse the write
class OwnerValidation : EntityCallback<Owner> {
    override fun beforeInsert(entity: Owner): Owner {
        require(entity.lastName.isNotBlank()) { "Last name must not be blank" }
        return entity
    }
}

// Callbacks fire in registration order
val orm = dataSource.orm
    .withEntityCallback(OwnerValidation())
    .withEntityCallback(AuditCallback())

To audit many entity types with one callback, register an EntityCallback<Entity<*>> that handles a shared Auditable interface. The lifecycle docs show that pattern and how callbacks route for upserts.

05Keep going

The reference documentation covers the details: