Documentation
¶
Overview ¶
Package models defines the persisted document shapes for admin-api.
Index ¶
- func CompleteAudit(id primitive.ObjectID, status AuditStatus, errMessage string) error
- func EnsureAuditIndexes(ctx context.Context) error
- func EnsureIndexes(ctx context.Context) error
- func EnsureMaintenanceModeIndexes(ctx context.Context) error
- func RecordAuditAttempt(actingUserSub, action, resourceID, detail string) (primitive.ObjectID, error)
- type AdminActionAuditLog
- type AuditStatus
- type BannerMessage
- type MaintenanceMode
- type MaintenanceScopeType
- type ScopeType
- type Severity
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CompleteAudit ¶ added in v0.2.0
func CompleteAudit(id primitive.ObjectID, status AuditStatus, errMessage string) error
CompleteAudit updates an audit record to its final status after the mutation it covers has run. Best-effort: a failure here doesn't undo a mutation that already happened, so callers should log a warning rather than fail the request on error.
func EnsureAuditIndexes ¶ added in v0.2.0
EnsureAuditIndexes creates the TTL index on admin_action_audit_logs: audit records are retained for 1 year (longer than banners' expiry-driven TTL - see design.md's Open Questions), independent of any per-document field. Safe to call on every startup - CreateOne is idempotent for an identical index definition.
func EnsureIndexes ¶
EnsureIndexes creates the indexes admin-api relies on: a MongoDB TTL index on expires_at that physically removes expired documents, and a compound index on (scope_type, scope_value) to keep the scoped-query path fast. Safe to call on every startup - CreateOne is idempotent for an identical index definition.
func EnsureMaintenanceModeIndexes ¶ added in v0.3.0
EnsureMaintenanceModeIndexes creates a unique compound index on (scope_type, scope_value) so at most one record exists per scope - a create for an existing scope updates in place instead of accumulating duplicates. Safe to call on every startup - CreateOne is idempotent for an identical index definition.
func RecordAuditAttempt ¶ added in v0.2.0
func RecordAuditAttempt(actingUserSub, action, resourceID, detail string) (primitive.ObjectID, error)
RecordAuditAttempt writes the "attempted" audit record for a write-route mutation before the mutation itself runs. Returns the record's ID for a later CompleteAudit call. Callers must not perform the mutation if this returns an error.
Types ¶
type AdminActionAuditLog ¶ added in v0.2.0
type AdminActionAuditLog struct {
ID primitive.ObjectID `bson:"_id,omitempty" json:"id"`
ActingUserSub string `bson:"acting_user_sub,omitempty" json:"acting_user_sub"`
Action string `bson:"action,omitempty" json:"action"`
ResourceID string `bson:"resource_id,omitempty" json:"resource_id,omitempty"`
Detail string `bson:"detail,omitempty" json:"detail,omitempty"`
Status AuditStatus `bson:"status" json:"status"`
AttemptedAt time.Time `bson:"attempted_at,omitempty" json:"attempted_at"`
CompletedAt *time.Time `bson:"completed_at,omitempty" json:"completed_at,omitempty"`
ErrorMessage string `bson:"error_message,omitempty" json:"error_message,omitempty"`
}
AdminActionAuditLog attributes a write-route mutation to the acting user who made it. Written *before* the mutation is attempted (status "attempted") and updated *after* it completes - see RecordAuditAttempt and CompleteAudit. If the "before" write fails, the mutation must not be performed: an audit trail that can silently fail to exist is not an audit trail, mirroring users-api's AdminActionAuditLog/performAudited pattern. bson tags on every field but ID/Status use omitempty: database.Update replaces the stored document with a $set of every marshaled field of whatever doc it's given, so CompleteAudit - which only ever populates Status/CompletedAt/ErrorMessage on top of an existing record's ID - must not marshal its unset fields as empty values, or it would overwrite the original ActingUserSub/Action/AttemptedAt with blanks.
type AuditStatus ¶ added in v0.2.0
type AuditStatus string
AuditStatus tracks whether the mutation an AdminActionAuditLog record covers actually completed.
const ( AuditAttempted AuditStatus = "attempted" AuditSucceeded AuditStatus = "succeeded" AuditFailed AuditStatus = "failed" )
type BannerMessage ¶
type BannerMessage struct {
ID primitive.ObjectID `bson:"_id,omitempty" json:"id"`
ScopeType ScopeType `bson:"scope_type" json:"scope_type"`
ScopeValue string `bson:"scope_value" json:"scope_value"`
Severity Severity `bson:"severity" json:"severity"`
Message string `bson:"message" json:"message"`
StartsAt *time.Time `bson:"starts_at,omitempty" json:"starts_at,omitempty"`
ExpiresAt time.Time `bson:"expires_at" json:"expires_at"`
CreatedBy string `bson:"created_by" json:"created_by"`
CreatedAt time.Time `bson:"created_at" json:"created_at"`
UpdatedAt time.Time `bson:"updated_at" json:"updated_at"`
}
BannerMessage is the MongoDB document for a platform-wide, service-scoped, or page-scoped admin banner.
func (*BannerMessage) Validate ¶
func (b *BannerMessage) Validate() error
Validate checks that the banner satisfies the invariants required by the spec: a known scope type, a scope value present exactly when the scope requires one, a known severity, a non-empty message, and a required expires_at.
type MaintenanceMode ¶ added in v0.3.0
type MaintenanceMode struct {
ID primitive.ObjectID `bson:"_id,omitempty" json:"id"`
ScopeType MaintenanceScopeType `bson:"scope_type" json:"scope_type"`
ScopeValue string `bson:"scope_value" json:"scope_value"`
Enabled bool `bson:"enabled" json:"enabled"`
StartsAt time.Time `bson:"starts_at" json:"starts_at"`
EndsAt *time.Time `bson:"ends_at,omitempty" json:"ends_at,omitempty"`
Label string `bson:"label" json:"label"`
Description string `bson:"description" json:"description"`
CreatedAt time.Time `bson:"created_at" json:"created_at"`
UpdatedAt time.Time `bson:"updated_at" json:"updated_at"`
}
MaintenanceMode is the MongoDB document for a platform-wide or service-scoped maintenance state. Unlike BannerMessage, it's a durable on/off record - one per scope, edited in place rather than accumulated - with enabled as the explicit gate; starts_at/ends_at are informational for display only.
func (*MaintenanceMode) Validate ¶ added in v0.3.0
func (m *MaintenanceMode) Validate() error
Validate checks that the record satisfies the invariants required by the spec: a known scope type, a scope value present exactly when the scope requires one, a required starts_at, and required label/description.
type MaintenanceScopeType ¶ added in v0.3.0
type MaintenanceScopeType string
MaintenanceScopeType identifies what a maintenance-mode record applies to. Unlike BannerMessage's ScopeType, maintenance mode has no page scope - it's app/platform granularity only.
const ( MaintenanceScopePlatform MaintenanceScopeType = "platform" MaintenanceScopeService MaintenanceScopeType = "service" )
Source Files