Go SDK · Behaviors worth knowing

Empty Action is a no-op

Events with no Action set are dropped at send time. Useful when you want a default-audit handler that conditionally opts out. Set Action only when something audit-worthy happens.

Dropping an unnamed event is a deliberate opt-out for an outcome that is not audit-worthy, not a way to skip failures. The difference is whether an auditor would want to see the exit path.

A read that found nothing, or a malformed request that reached no resource, is not audit-worthy: leave Action unset. That is what the handler below does on its 404.

A failed attempt at an audit-worthy action is the opposite. A denied authorization, a rejected payment, an invite that errored: all of those must be recorded, which means naming the event before the early return that handles them.

func readSecret(v *vault) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        e := event.Current(r.Context())

        s, err := v.get(r.PathValue("id"))
        if err != nil {
            http.NotFound(w, r)
            return  // Action never set → event silently dropped
        }
        e.Action = "secret.read"
        e.Target = event.Target{Type: "secret", ID: s.ID}
        writeJSON(w, http.StatusOK, s)
    }
}

Naming an event whose target does not exist yet

When the target's ID only exists after the operation succeeds, name the event anyway and backfill the ID. Moving the naming below the error return is what silently drops the failure.

e := event.Current(r.Context())
e.Action = "member.invited"
e.Target = event.Target{Type: "user"}   // no ID yet, and that is fine

u, err := s.InviteMember(r.Context(), req)
if err != nil {
    httpError(w, err)
    return          // recorded, Result filled by the adapter
}
e.Target.ID = u.ID  // backfilled on the success path

An event whose target has a type but no ID is still a useful audit record: it says who tried to do what, and that it failed. An event that was never named says nothing at all.

The rule generalizes past Target.ID. Any field you cannot populate until the operation succeeds gets assigned after the error return, never used as a reason to delay naming the event.

Record is non-blocking

Record enqueues the event on the in-memory buffer and returns immediately. The background goroutine handles the HTTP call on the next flush. Don't await audit acks in critical paths, and don't wrap Record in your own goroutine "for safety" (you'll lose context propagation and gain nothing).

start := time.Now()
_ = rec.Record(ctx, e)
fmt.Println(time.Since(start))  // microseconds — no network round-trip

Caller-set fields take precedence

The middleware auto-populates Result from the response status. If you set Result yourself, that wins. Useful for anti-enumeration handlers that return the same HTTP status for different audit outcomes.

func revealSecret(v *vault) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        me, _ := actorFromRequest(r)
        id := r.PathValue("id")

        e := event.Current(r.Context())
        e.Action = "secret.reveal"
        e.Target = event.Target{Type: "secret", ID: id}

        s, err := v.get(id)
        if err != nil {
            http.NotFound(w, r)  // genuinely doesn't exist
            return               // middleware records Result{Status: "error", Code: 404}
        }
        if s.TenantID != me.TenantID {
            // Return 404 instead of 403 so attackers can't probe for
            // secret IDs in other tenants. The user-facing response
            // can't tell the two cases apart — but the audit log should.
            e.Result = event.Result{Status: "denied", Code: 403, Message: "cross-tenant access"}
            http.NotFound(w, r)
            return
        }
        writeJSON(w, http.StatusOK, map[string]string{"value": s.Value})
    }
}

Context cancellation is respected

Record short-circuits on a cancelled context. No enqueue attempt, no allocation. The buffered recorder also bails on cancellation when blocked waiting for buffer space under PolicyBlock.

ctx, cancel := context.WithCancel(context.Background())
cancel()

err := rec.Record(ctx, e)
// err == context.Canceled; e was never enqueued.