Keep personal notes private by default and require review before publishing shared notes. Restore backups and replay forgotten notes in one transaction, and retain the installed release when an unattended rollback could bring back forgotten notes.
379 lines
13 KiB
Go
379 lines
13 KiB
Go
package memory
|
|
|
|
import (
|
|
"context"
|
|
"errors"
|
|
"net/http"
|
|
"strings"
|
|
|
|
"github.com/danielgtaylor/huma/v2"
|
|
"github.com/google/uuid"
|
|
|
|
"github.com/samcharles93/archie-core/internal/platform/httpapi"
|
|
"github.com/samcharles93/archie-core/modules/governance"
|
|
)
|
|
|
|
// Register adds the memory API. The routes a person uses to read and correct
|
|
// their own notes are scoped to the signed-in caller; the ones that publish,
|
|
// revoke or roll back a shared note need an instance administrator, which
|
|
// httpapi enforces unless an operation opts into SignedIn.
|
|
func (m *Module) Register(api huma.API) {
|
|
tags := []string{"Memory"}
|
|
huma.Register(api, httpapi.SignedIn(huma.Operation{
|
|
OperationID: "list-memory-notes", Method: http.MethodGet, Path: "/api/memory/notes",
|
|
Summary: "List the notes you may read", Tags: tags,
|
|
}), m.notesOfCaller)
|
|
huma.Register(api, httpapi.SignedIn(huma.Operation{
|
|
OperationID: "remember-memory-note", Method: http.MethodPost, Path: "/api/memory/notes",
|
|
Summary: "Remember a note for yourself", Tags: tags,
|
|
}), m.rememberNote)
|
|
huma.Register(api, httpapi.SignedIn(huma.Operation{
|
|
OperationID: "correct-memory-note", Method: http.MethodPatch, Path: "/api/memory/notes/{id}",
|
|
Summary: "Correct one of your notes", Tags: tags,
|
|
}), m.correctNote)
|
|
huma.Register(api, httpapi.SignedIn(huma.Operation{
|
|
OperationID: "disable-memory-note", Method: http.MethodPost, Path: "/api/memory/notes/{id}/disabled",
|
|
Summary: "Stop one of your notes being read, or resume it", Tags: tags,
|
|
}), m.disableNote)
|
|
huma.Register(api, httpapi.SignedIn(huma.Operation{
|
|
OperationID: "forget-memory-note", Method: http.MethodDelete, Path: "/api/memory/notes/{id}",
|
|
Summary: "Forget one of your notes", Tags: tags,
|
|
}), m.forgetNote)
|
|
huma.Register(api, httpapi.SignedIn(huma.Operation{
|
|
OperationID: "propose-shared-note", Method: http.MethodPost, Path: "/api/memory/proposals",
|
|
Summary: "Propose a note for the whole organisation", Tags: tags,
|
|
}), m.proposeNote)
|
|
huma.Register(api, httpapi.SignedIn(huma.Operation{
|
|
OperationID: "list-shared-notes", Method: http.MethodGet, Path: "/api/memory/shared",
|
|
Summary: "List the notes published to the organisation", Tags: tags,
|
|
}), m.sharedNotes)
|
|
huma.Register(api, huma.Operation{
|
|
OperationID: "publish-shared-note", Method: http.MethodPost, Path: "/api/memory/shared",
|
|
Summary: "Publish a note to the whole organisation", Tags: tags,
|
|
}, m.publishNote)
|
|
huma.Register(api, huma.Operation{
|
|
OperationID: "list-note-proposals", Method: http.MethodGet, Path: "/api/memory/proposals",
|
|
Summary: "List notes waiting to be published", Tags: tags,
|
|
}, m.pendingNotes)
|
|
huma.Register(api, huma.Operation{
|
|
OperationID: "approve-note-proposal", Method: http.MethodPost, Path: "/api/memory/proposals/{id}/publish",
|
|
Summary: "Publish a proposed note", Tags: tags,
|
|
}, m.approveNote)
|
|
huma.Register(api, huma.Operation{
|
|
OperationID: "revoke-shared-note", Method: http.MethodDelete, Path: "/api/memory/shared/{id}",
|
|
Summary: "Revoke a shared note, published or proposed", Tags: tags,
|
|
}, m.revokeNote)
|
|
huma.Register(api, huma.Operation{
|
|
OperationID: "list-note-versions", Method: http.MethodGet, Path: "/api/memory/shared/{id}/versions",
|
|
Summary: "List the published versions of a shared note", Tags: tags,
|
|
}, m.noteVersions)
|
|
huma.Register(api, huma.Operation{
|
|
OperationID: "roll-back-shared-note", Method: http.MethodPost, Path: "/api/memory/shared/{id}/rollback",
|
|
Summary: "Publish an earlier version of a shared note again", Tags: tags,
|
|
}, m.rollbackNote)
|
|
}
|
|
|
|
// notes is the response body listing notes.
|
|
type notes struct {
|
|
Notes []Note `json:"notes"`
|
|
}
|
|
|
|
// idInput names one note.
|
|
type idInput struct {
|
|
ID string `path:"id" format:"uuid" doc:"The note's id"`
|
|
}
|
|
|
|
type notesInput struct {
|
|
Class string `query:"class" enum:"working_context,episodic_history,enterprise_retrieval,durable_fact" doc:"The memory class, durable facts by default"`
|
|
}
|
|
|
|
type textInput struct {
|
|
Body struct {
|
|
Text string `json:"text" doc:"The note itself. A credential-shaped value is redacted, and a credential or a security override is refused."`
|
|
}
|
|
}
|
|
|
|
type correctInput struct {
|
|
ID string `path:"id" format:"uuid"`
|
|
Body struct {
|
|
Text string `json:"text" doc:"The corrected note"`
|
|
}
|
|
}
|
|
|
|
type disabledInput struct {
|
|
ID string `path:"id" format:"uuid"`
|
|
Body struct {
|
|
Disabled bool `json:"disabled" doc:"Whether the note stops being read"`
|
|
}
|
|
}
|
|
|
|
type rollbackInput struct {
|
|
ID string `path:"id" format:"uuid"`
|
|
Body struct {
|
|
Version int `json:"version" doc:"The published version to publish again"`
|
|
}
|
|
}
|
|
|
|
// caller is the signed-in person, whose notes the request is about.
|
|
func caller(ctx context.Context) (string, error) {
|
|
p, ok := governance.PrincipalFromContext(ctx)
|
|
if !ok || p.IdentityID == "" {
|
|
return "", huma.NewError(http.StatusUnauthorized, httpapi.ErrUnauthenticated.Error())
|
|
}
|
|
return string(p.IdentityID), nil
|
|
}
|
|
|
|
// classOf reads the class a request is about, defaulting to the durable facts a
|
|
// conversation remembers.
|
|
func classOf(class string) (Class, error) {
|
|
if strings.TrimSpace(class) == "" {
|
|
return ClassDurableFact, nil
|
|
}
|
|
c := Class(class)
|
|
if err := c.Validate(); err != nil {
|
|
return "", huma.NewError(http.StatusBadRequest, "class is one of the memory classes")
|
|
}
|
|
return c, nil
|
|
}
|
|
|
|
func (m *Module) notesOfCaller(ctx context.Context, in *notesInput) (*httpapi.Reply[notes], error) {
|
|
owner, err := caller(ctx)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
class, err := classOf(in.Class)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
mine, err := m.Mine(ctx, owner, class)
|
|
if err != nil {
|
|
m.log.ErrorContext(ctx, "list notes", "error", err)
|
|
return nil, huma.NewError(http.StatusInternalServerError, "couldn't list your notes")
|
|
}
|
|
shared, err := m.Shared(ctx, class)
|
|
if err != nil {
|
|
m.log.ErrorContext(ctx, "list shared notes", "error", err)
|
|
return nil, huma.NewError(http.StatusInternalServerError, "couldn't list the shared notes")
|
|
}
|
|
return httpapi.OK(notes{Notes: append(mine, shared...)}), nil
|
|
}
|
|
|
|
// rememberNote stores a note in the caller's own scope. A conversation's
|
|
// memory_save tool writes the same way, as the person the turn acts for.
|
|
func (m *Module) rememberNote(ctx context.Context, in *textInput) (*httpapi.Reply[Note], error) {
|
|
owner, err := caller(ctx)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
note, err := m.Remember(ctx, owner, in.Body.Text)
|
|
switch {
|
|
case errors.Is(err, ErrInvalidNote):
|
|
return nil, huma.NewError(http.StatusBadRequest, err.Error())
|
|
case err != nil:
|
|
m.log.ErrorContext(ctx, "remember note", "error", err)
|
|
return nil, huma.NewError(http.StatusInternalServerError, "couldn't remember the note")
|
|
}
|
|
return httpapi.OK(note), nil
|
|
}
|
|
|
|
func (m *Module) correctNote(ctx context.Context, in *correctInput) (*httpapi.Reply[Note], error) {
|
|
owner, err := caller(ctx)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
id, err := uuid.Parse(in.ID)
|
|
if err != nil {
|
|
return nil, huma.NewError(http.StatusBadRequest, "id is a note id")
|
|
}
|
|
note, ok, err := m.Correct(ctx, owner, id, in.Body.Text)
|
|
switch {
|
|
case errors.Is(err, ErrInvalidNote):
|
|
return nil, huma.NewError(http.StatusBadRequest, err.Error())
|
|
case err != nil:
|
|
m.log.ErrorContext(ctx, "correct note", "note", id, "error", err)
|
|
return nil, huma.NewError(http.StatusInternalServerError, "couldn't correct the note")
|
|
case !ok:
|
|
return nil, huma.NewError(http.StatusNotFound, "no note of yours has that id")
|
|
}
|
|
return httpapi.OK(note), nil
|
|
}
|
|
|
|
func (m *Module) disableNote(ctx context.Context, in *disabledInput) (*struct{}, error) {
|
|
owner, err := caller(ctx)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
id, err := uuid.Parse(in.ID)
|
|
if err != nil {
|
|
return nil, huma.NewError(http.StatusBadRequest, "id is a note id")
|
|
}
|
|
ok, err := m.Disable(ctx, owner, id, in.Body.Disabled)
|
|
if err != nil {
|
|
m.log.ErrorContext(ctx, "disable note", "note", id, "error", err)
|
|
return nil, huma.NewError(http.StatusInternalServerError, "couldn't change the note")
|
|
}
|
|
if !ok {
|
|
return nil, huma.NewError(http.StatusNotFound, "no note of yours has that id")
|
|
}
|
|
return nil, nil
|
|
}
|
|
|
|
func (m *Module) forgetNote(ctx context.Context, in *idInput) (*struct{}, error) {
|
|
owner, err := caller(ctx)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
id, err := uuid.Parse(in.ID)
|
|
if err != nil {
|
|
return nil, huma.NewError(http.StatusBadRequest, "id is a note id")
|
|
}
|
|
ok, err := m.Forget(ctx, owner, id)
|
|
switch {
|
|
case errors.Is(err, ErrRecordIncomplete):
|
|
// The note is gone; only its record is pending. Saying so exactly is the
|
|
// point: the caller must not be told the deletion is fully durable, and
|
|
// must not be told it failed either.
|
|
m.log.ErrorContext(ctx, "record a deletion", "note", id, "error", err)
|
|
return nil, huma.NewError(http.StatusServiceUnavailable,
|
|
"the note was deleted and the record of its deletion is pending; it is retried until it is written")
|
|
case err != nil:
|
|
m.log.ErrorContext(ctx, "forget note", "note", id, "error", err)
|
|
return nil, huma.NewError(http.StatusInternalServerError, "couldn't forget the note")
|
|
case !ok:
|
|
return nil, huma.NewError(http.StatusNotFound, "no note of yours has that id")
|
|
}
|
|
return nil, nil
|
|
}
|
|
|
|
func (m *Module) proposeNote(ctx context.Context, in *textInput) (*httpapi.Reply[Note], error) {
|
|
owner, err := caller(ctx)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
note, err := m.Propose(ctx, owner, in.Body.Text)
|
|
if errors.Is(err, ErrInvalidNote) {
|
|
return nil, huma.NewError(http.StatusBadRequest, err.Error())
|
|
}
|
|
if err != nil {
|
|
m.log.ErrorContext(ctx, "propose shared note", "error", err)
|
|
return nil, huma.NewError(http.StatusInternalServerError, "couldn't record the proposal")
|
|
}
|
|
return httpapi.OK(note), nil
|
|
}
|
|
|
|
func (m *Module) sharedNotes(ctx context.Context, in *notesInput) (*httpapi.Reply[notes], error) {
|
|
class, err := classOf(in.Class)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
rows, err := m.Shared(ctx, class)
|
|
if err != nil {
|
|
m.log.ErrorContext(ctx, "list shared notes", "error", err)
|
|
return nil, huma.NewError(http.StatusInternalServerError, "couldn't list the shared notes")
|
|
}
|
|
return httpapi.OK(notes{Notes: rows}), nil
|
|
}
|
|
|
|
func (m *Module) pendingNotes(ctx context.Context, _ *struct{}) (*httpapi.Reply[notes], error) {
|
|
rows, err := m.Pending(ctx)
|
|
if err != nil {
|
|
m.log.ErrorContext(ctx, "list note proposals", "error", err)
|
|
return nil, huma.NewError(http.StatusInternalServerError, "couldn't list the proposals")
|
|
}
|
|
return httpapi.OK(notes{Notes: rows}), nil
|
|
}
|
|
|
|
func (m *Module) publishNote(ctx context.Context, in *textInput) (*httpapi.Reply[Note], error) {
|
|
publisher, err := caller(ctx)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
note, err := m.Publish(ctx, publisher, "", in.Body.Text)
|
|
if errors.Is(err, ErrInvalidNote) {
|
|
return nil, huma.NewError(http.StatusBadRequest, err.Error())
|
|
}
|
|
if err != nil {
|
|
m.log.ErrorContext(ctx, "publish shared note", "error", err)
|
|
return nil, huma.NewError(http.StatusInternalServerError, "couldn't publish the note")
|
|
}
|
|
return httpapi.OK(note), nil
|
|
}
|
|
|
|
func (m *Module) approveNote(ctx context.Context, in *idInput) (*httpapi.Reply[Note], error) {
|
|
publisher, err := caller(ctx)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
id, err := uuid.Parse(in.ID)
|
|
if err != nil {
|
|
return nil, huma.NewError(http.StatusBadRequest, "id is a note id")
|
|
}
|
|
note, ok, err := m.Approve(ctx, publisher, id)
|
|
if err != nil {
|
|
m.log.ErrorContext(ctx, "publish proposed note", "note", id, "error", err)
|
|
return nil, huma.NewError(http.StatusInternalServerError, "couldn't publish the note")
|
|
}
|
|
if !ok {
|
|
return nil, huma.NewError(http.StatusNotFound, "no proposal has that id")
|
|
}
|
|
return httpapi.OK(note), nil
|
|
}
|
|
|
|
func (m *Module) revokeNote(ctx context.Context, in *idInput) (*struct{}, error) {
|
|
id, err := uuid.Parse(in.ID)
|
|
if err != nil {
|
|
return nil, huma.NewError(http.StatusBadRequest, "id is a note id")
|
|
}
|
|
ok, err := m.Revoke(ctx, id)
|
|
if errors.Is(err, ErrRecordIncomplete) {
|
|
m.log.ErrorContext(ctx, "record a deletion", "note", id, "error", err)
|
|
return nil, huma.NewError(http.StatusServiceUnavailable,
|
|
"the note was deleted and the record of its deletion is pending; it is retried until it is written")
|
|
}
|
|
if err != nil {
|
|
m.log.ErrorContext(ctx, "revoke shared note", "note", id, "error", err)
|
|
return nil, huma.NewError(http.StatusInternalServerError, "couldn't revoke the note")
|
|
}
|
|
if !ok {
|
|
return nil, huma.NewError(http.StatusNotFound, "no shared note has that id")
|
|
}
|
|
return nil, nil
|
|
}
|
|
|
|
type versions struct {
|
|
Versions []Version `json:"versions"`
|
|
}
|
|
|
|
func (m *Module) noteVersions(ctx context.Context, in *idInput) (*httpapi.Reply[versions], error) {
|
|
id, err := uuid.Parse(in.ID)
|
|
if err != nil {
|
|
return nil, huma.NewError(http.StatusBadRequest, "id is a note id")
|
|
}
|
|
rows, err := m.Versions(ctx, id)
|
|
if err != nil {
|
|
m.log.ErrorContext(ctx, "list note versions", "note", id, "error", err)
|
|
return nil, huma.NewError(http.StatusInternalServerError, "couldn't list the note's versions")
|
|
}
|
|
return httpapi.OK(versions{Versions: rows}), nil
|
|
}
|
|
|
|
func (m *Module) rollbackNote(ctx context.Context, in *rollbackInput) (*httpapi.Reply[Note], error) {
|
|
publisher, err := caller(ctx)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
id, err := uuid.Parse(in.ID)
|
|
if err != nil {
|
|
return nil, huma.NewError(http.StatusBadRequest, "id is a note id")
|
|
}
|
|
note, ok, err := m.Rollback(ctx, publisher, id, in.Body.Version)
|
|
if err != nil {
|
|
m.log.ErrorContext(ctx, "roll back shared note", "note", id, "error", err)
|
|
return nil, huma.NewError(http.StatusInternalServerError, "couldn't roll the note back")
|
|
}
|
|
if !ok {
|
|
return nil, huma.NewError(http.StatusNotFound, "the note has no such published version")
|
|
}
|
|
return httpapi.OK(note), nil
|
|
}
|