Recommendations/Documention for implementing an Audit Hook

[cliedeman]

Hi there, looking for some guidance/ideas on how to implement a basic auditing hook in ent

Lets say I have the following Mixin

// AuditMixin struct
type AuditMixin struct{}

// Fields Default audit fields
func (AuditMixin) Fields() []ent.Field {
	return []ent.Field{
		field.Time("created_at").
			Immutable().
			Default(time.Now),
		field.Int("created_by").Optional(),
		field.Time("updated_at").
			Default(time.Now).
			UpdateDefault(time.Now),
		field.Int("updated_by").Optional(),
	}
}

... rest omitted

And I Implement the following hook (first attempt)

const (
	FieldCreatedBy = "created_by"
	FieldCreatedAt = "created_at"
	FieldUpdatedBy = "updated_by"
	FieldUpdatedAt = "updated_at"
)

// AuditHook extracts the user from the context and populates the audit fields
func AuditHook(next ent.Mutator) ent.Mutator {
	return ent.MutateFunc(func(ctx context.Context, m ent.Mutation) (ent.Value, error) {
		// TODO: some way to find out if Auditing is applicable to this object
		usr, err := internal.UserFromContext(ctx)

		if err != nil {
			return nil, err
		}

		if m.Op() == ent.OpCreate {
			err := m.SetField(FieldCreatedAt, time.Now())

			if err != nil {
				return nil, err
			}

			_, set := m.Field(FieldCreatedBy)

			if !set {
				err = m.SetField(FieldCreatedBy, usr.ID)

				if err != nil {
					return nil, err
				}
			}
		}

		if m.Op() == ent.OpUpdate || m.Op() == ent.OpUpdateOne {
			_, set := m.Field("updated_by")

			if !set {
				err = m.SetField("updated_by", usr.ID)

				if err != nil {
					return nil, err
				}

				err = m.SetField("updated_at", time.Now())

				if err != nil {
					return nil, err
				}
			}
		}

		return next.Mutate(ctx, m)
	})
}

The first issue I have encountered is that there is no easy way (that I could find) to identify which mixins apply to an object. Having access to the annotations could also work if we wanted to mark special processing for an update in that way.

[a8m]

Hey @cliedeman and great to see you here again 😃

I can help with that, but I'd love to get a better context on your end-goal before, because an audit-log can be implemented in different ways (@masseelch, you're welcome to share your thoughts as well).

So, it will be easier if you can elaborate what do you expect that such hook will do? Update the current mutation, write to a different table, log it somewhere (and what? the mutation diff or just the updated fields, etc...)?

[cliedeman]

Hi @a8m thanks, great to be writing some go again 😃.

I just re-read the documentation and I think I found a solution

// Fields Default audit fields
func (AuditMixin) Fields() []ent.Field {
	return []ent.Field{
		field.Time("created_at").
			Immutable().
			Default(time.Now),
		field.Int("created_by").Optional(),
		field.Time("updated_at").
			Default(time.Now).
			UpdateDefault(time.Now),
		field.Int("updated_by").Optional(),
	}
}

//Hooks AuditMixin Export
func (AuditMixin) Hooks() []ent.Hook {
	return []ent.Hook{hooks.AuditHook}
}

I was not aware you can embed hooks into the mixin. This solves the issue above as the hook will always be attached to nodes that have the revelant columns

[a8m]

Great @cliedeman, you can also write this as follows:

// AuditLogger wraps the methods that are shared between all mutations of
// schemas that embed the AuditLog mixin. The variable "exists" is true, if
// the field already exists in the mutation (e.g. was set by a different hook).
type AuditLogger interface {
	SetCreatedAt(time.Time)
	CreatedAt() (value time.Time, exists bool)
	SetCreatedBy(int)
	CreatedBy() (id int, exists bool)
	SetUpdatedAt(time.Time)
	UpdatedAt() (value time.Time, exists bool)
	SetUpdatedBy(int)
	UpdatedBy() (id int, exists bool)
}

func AuditHook(next ent.Mutator) ent.Mutator {
	return ent.MutateFunc(func(ctx context.Context, m ent.Mutation) (ent.Value, error) {
		ml, ok := m.(AuditLogger)
		if !ok {
			return nil, fmt.Errorf("unexpected audit-log call from mutation type %T", m)
		}
		usr, err := viewer.UserFromContext(ctx)
		if err != nil {
			return nil, err
		}
		switch op := m.Op(); {
		case op.Is(ent.OpCreate):
			ml.SetCreatedAt(time.Now())
			if _, exists := ml.CreatedBy(); !exists {
				ml.SetCreatedBy(usr.ID)
			}
		case op.Is(ent.OpUpdateOne | ent.OpUpdate):
			ml.SetUpdatedAt(time.Now())
			if _, exists := ml.UpdatedBy(); !exists {
				ml.SetUpdatedBy(usr.ID)
			}
		}
		return next.Mutate(ctx, m)
	})
}

See also, how to limit the hooks execution to specific mutation operations using the hook-helpers.

Also note that in the upcoming weeks I'm going to add support for generating interfaces for ent.Mixins, and provide an API as follows:

func AuditHook(next ent.Mutator) ent.Mutator {
	return hook.AuditFunc(func(ctx context.Context, m hook.AuditMixin) (ent.Value, error) {
		// Type assertion is not needed here.
	})
}

[a8m]

Can we close this issue @cliedeman?

[cliedeman]

Hi @a8m yes we can. I will try out the suggestion probably tomorrow. Should this be added to the docs under a guide or cook book section?

[a8m]

Hi @a8m yes we can. I will try out the suggestion probably tomorrow. Should this be added to the docs under a guide or cook book section?

Yeah, I wanted to create another page for faq or a cook-book for ent - #832.

[cliedeman]

@a8m Thanks sounds good to me. I tried out your method and it worked great.
Thanks.

[masseelch]

I can help with that, but I'd love to get a better context on your end-goal before, because an audit-log can be implemented in different ways (@masseelch, you're welcome to share your thoughts as well).

Well, your solution is working like a charm. Thanks :-)

[a8m]

Wonderful!

I'll add it to the website in the upcoming days. Currently focused on something else 😃