Janady13/missionmatch / internal/modules/recruiting/ownership.go

1package recruiting 2 3import ( 4 "context" 5 "errors" 6 7 "github.com/google/uuid" 8 "github.com/jackc/pgx/v5" 9 10 "github.com/missionworkforce/missionmatch/internal/platform/security" 11 "github.com/missionworkforce/missionmatch/internal/platform/tenant" 12) 13 14// ErrNotOwner is returned when a recruiter tries to edit an account someone else holds. It carries the 15// holder so the caller can be told WHO to talk to, which is the entire point of showing ownership: the 16// answer to a collision is a conversation, not a retry. 17type ErrNotOwner struct { 18 OwnerUserID string 19 OwnerName string 20 // Entity is the noun shown to the user. Clients and requisitions share this lock, and telling a 21 // recruiter their job order is "assigned to" someone as a CLIENT would send them looking in the wrong 22 // place. Empty falls back to a neutral word rather than guessing. 23 Entity string 24} 25 26func (e *ErrNotOwner) noun() string { 27 if e.Entity == "" { 28 return "record" 29 } 30 return e.Entity 31} 32 33func (e *ErrNotOwner) Error() string { 34 if e.OwnerName != "" { 35 return "recruiting: this " + e.noun() + " is assigned to " + e.OwnerName 36 } 37 return "recruiting: this " + e.noun() + " is assigned to another recruiter" 38} 39 40// owner is the ownership state of one client, read inside the caller's transaction. 41type owner struct { 42 userID *uuid.UUID 43 name string 44 entity string 45} 46 47// loadOwner reads current ownership FOR UPDATE. 48// 49// The row lock matters. Two recruiters claiming the same unassigned client at the same moment would 50// both read NULL and both write themselves in, and the last writer would silently take it while the 51// first believed they had it. FOR UPDATE serializes the pair so the second sees the first's claim and 52// is refused. This is the one place a pessimistic lock is correct: it is held for microseconds inside a 53// single transaction, not across a user's editing session. 54func loadOwner(ctx context.Context, tx pgx.Tx, clientID uuid.UUID) (owner, error) { 55 o := owner{entity: "client"} 56 var name *string 57 err := tx.QueryRow(ctx, ` 58 SELECT c.owner_user_id, u.full_name 59 FROM clients c 60 LEFT JOIN users u ON u.organization_id = c.organization_id AND u.id = c.owner_user_id 61 WHERE c.id = $1 62 FOR UPDATE OF c`, clientID).Scan(&o.userID, &name) 63 if err != nil { 64 if errors.Is(err, pgx.ErrNoRows) { 65 return owner{}, ErrNotFound 66 } 67 return owner{}, translatePG(err) 68 } 69 if name != nil { 70 o.name = *name 71 } 72 return o, nil 73} 74 75// canOverride reports whether the caller may act on an account they do not hold. 76// 77// Gated on desk.reassign rather than on a role. That capability is held by manager and above, which is 78// the point of the manager tier: reassigning a desk is the most common thing a team lead does, and 79// requiring admin for it meant handing them PII deletion and account management as well. 80// 81// A recruiter still cannot take an account from a peer. That is a management decision, and making it one 82// is the difference between a shared system and a land grab. 83func canOverride(ctx context.Context) bool { 84 p, ok := tenant.UserFromContext(ctx) 85 if !ok { 86 return false 87 } 88 return security.Has(security.Role(p.Role), security.CapDeskReassign) 89} 90 91// assertCanEdit is the gate every client write passes through. 92// 93// Unclaimed accounts are editable by anyone with write capability, and the edit claims them. That is 94// deliberate: requiring a separate claim step before a first edit adds a click to the most common path, 95// and an unowned client sitting in the pool benefits nobody. 96func assertCanEdit(ctx context.Context, tx pgx.Tx, clientID uuid.UUID) (claim bool, err error) { 97 o, err := loadOwner(ctx, tx, clientID) 98 if err != nil { 99 return false, err 100 } 101 actor := actorPtr(ctx) 102 if actor == nil { 103 return false, tenant.ErrNoTenant 104 } 105 return ownershipDecision(o, actor, canOverride(ctx)) 106} 107 108// ownershipDecision is the whole access rule, pure and free of a database, so every combination of 109// holder, actor and role is provable in a unit test rather than only reachable by logging in as three 110// different people. 111// 112// Returns claim=true when the caller takes an unowned account by editing it. 113func ownershipDecision(o owner, actor *uuid.UUID, isAdmin bool) (bool, error) { 114 switch { 115 case o.userID == nil: 116 // Unclaimed. This edit takes it. 117 return true, nil 118 case *o.userID == *actor: 119 return false, nil 120 case isAdmin: 121 // An admin edits without silently seizing the account. Taking it is a separate, explicit action 122 // so the audit trail distinguishes a manager fixing a typo from the account changing hands. 123 return false, nil 124 default: 125 return false, &ErrNotOwner{OwnerUserID: o.userID.String(), OwnerName: o.name, Entity: o.entity} 126 } 127} 128 129// Claim assigns an unclaimed client to the calling recruiter. 130func (s *Service) Claim(ctx context.Context, clientID uuid.UUID) (Client, error) { 131 if s.db == nil { 132 return Client{}, ErrNoDatabase 133 } 134 actor := actorPtr(ctx) 135 if actor == nil { 136 return Client{}, tenant.ErrNoTenant 137 } 138 err := s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 139 o, err := loadOwner(ctx, tx, clientID) 140 if err != nil { 141 return err 142 } 143 if o.userID != nil { 144 if *o.userID == *actor { 145 return nil // already held by the caller, claiming again is a no op rather than an error 146 } 147 if !canOverride(ctx) { 148 return &ErrNotOwner{OwnerUserID: o.userID.String(), OwnerName: o.name, Entity: o.entity} 149 } 150 } 151 return s.setOwner(ctx, tx, clientID, actor, "client.claimed") 152 }) 153 if err != nil { 154 return Client{}, err 155 } 156 return s.clientRow(ctx, clientID) 157} 158 159// Release returns a client to the unassigned pool. 160func (s *Service) Release(ctx context.Context, clientID uuid.UUID) (Client, error) { 161 if s.db == nil { 162 return Client{}, ErrNoDatabase 163 } 164 err := s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 165 if _, err := assertCanEdit(ctx, tx, clientID); err != nil { 166 return err 167 } 168 return s.setOwner(ctx, tx, clientID, nil, "client.released") 169 }) 170 if err != nil { 171 return Client{}, err 172 } 173 return s.clientRow(ctx, clientID) 174} 175 176// Reassign moves a client to another recruiter. Admin or owner only: moving an account between people 177// is a management decision. 178func (s *Service) Reassign(ctx context.Context, clientID, toUser uuid.UUID) (Client, error) { 179 if s.db == nil { 180 return Client{}, ErrNoDatabase 181 } 182 if !canOverride(ctx) { 183 return Client{}, &ValidationError{Field: "owner_user_id", Message: "only an admin or owner can reassign an account"} 184 } 185 err := s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 186 if _, err := loadOwner(ctx, tx, clientID); err != nil { 187 return err 188 } 189 // The target must be a real, active member of this tenant. RLS scopes the lookup, so a user id 190 // from another organization simply does not exist here. 191 var active bool 192 if err := tx.QueryRow(ctx, 193 `SELECT status = 'active' FROM users WHERE id = $1`, toUser).Scan(&active); err != nil { 194 if errors.Is(err, pgx.ErrNoRows) { 195 return &ValidationError{Field: "owner_user_id", Message: "is not a user in this organization"} 196 } 197 return translatePG(err) 198 } 199 if !active { 200 return &ValidationError{Field: "owner_user_id", Message: "is not an active user"} 201 } 202 return s.setOwner(ctx, tx, clientID, &toUser, "client.reassigned") 203 }) 204 if err != nil { 205 return Client{}, err 206 } 207 return s.clientRow(ctx, clientID) 208} 209 210// setOwner writes ownership and its timestamp together and records the change. owner_since is set from 211// the database clock rather than the application so two nodes cannot disagree about tenure. 212func (s *Service) setOwner(ctx context.Context, tx pgx.Tx, clientID uuid.UUID, to *uuid.UUID, action string) error { 213 var since any 214 if to != nil { 215 since = "now" 216 } 217 _, err := tx.Exec(ctx, ` 218 UPDATE clients 219 SET owner_user_id = $2, 220 owner_since = CASE WHEN $3::text IS NULL THEN NULL ELSE now() END, 221 updated_at = now() 222 WHERE id = $1`, clientID, to, since) 223 if err != nil { 224 return translatePG(err) 225 } 226 return s.auditOwnership(ctx, tx, "client", clientID, to, action) 227} 228