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

1package recruiting 2 3import ( 4 "context" 5 "encoding/json" 6 "errors" 7 "net/http" 8 "strings" 9 10 "github.com/go-chi/chi/v5" 11 "github.com/google/uuid" 12 "github.com/jackc/pgx/v5" 13 14 "github.com/missionworkforce/missionmatch/internal/platform/security" 15) 16 17// MessagingRoutes serves correspondence and the templates behind it. 18// 19// SENDING IS candidate.write, NOT a management capability. Writing to a candidate you are working is ordinary 20// recruiting, and a recruiter who cannot send is a recruiter who cannot do the job. Reading correspondence is 21// candidate.read, because a colleague picking up the record needs to know what has already been said before 22// they say it again. 23// 24// TEMPLATE WRITES ARE org.settings.write. A template goes out under the organization's name to people who are 25// not its employees, so who may author one is the same authority that configures the organization. 26func (h *Handler) MessagingRoutes(r chi.Router) { 27 read := security.RequireCapability(security.CapCandidateRead) 28 write := security.RequireCapability(security.CapCandidateWrite) 29 admin := security.RequireCapability(security.CapOrgSettings) 30 31 r.With(write).Post("/messages", h.sendMessage) 32 r.With(read).Get("/candidates/{candidateID}/messages", h.candidateMessages) 33 r.With(read).Get("/contacts/{contactID}/messages", h.contactMessages) 34 35 r.With(read).Get("/message-templates", h.listTemplates) 36 r.With(admin).Post("/message-templates", h.createTemplate) 37 r.With(admin).Patch("/message-templates/{templateID}", h.updateTemplate) 38 // The preview resolves placeholders against the REAL record and returns exactly what would be sent. It is 39 // a read, gated at the read tier, and it exists so nobody ever discovers a broken greeting by sending it. 40 r.With(read).Post("/message-templates/preview", h.previewTemplate) 41} 42 43func (h *Handler) sendMessage(w http.ResponseWriter, r *http.Request) { 44 var in MessageInput 45 if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 64<<10)).Decode(&in); err != nil { 46 writeErr(w, http.StatusBadRequest, "invalid body", "") 47 return 48 } 49 msg, err := h.svc.SendMessage(r.Context(), in, r.Header.Get("X-Forwarded-For"), r.UserAgent()) 50 if err != nil { 51 h.failMessage(w, err, msg) 52 return 53 } 54 writeJSON(w, http.StatusCreated, msg) 55} 56 57func (h *Handler) candidateMessages(w http.ResponseWriter, r *http.Request) { 58 h.messagesFor(w, r, "candidate", "candidateID") 59} 60 61func (h *Handler) contactMessages(w http.ResponseWriter, r *http.Request) { 62 h.messagesFor(w, r, "contact", "contactID") 63} 64 65func (h *Handler) messagesFor(w http.ResponseWriter, r *http.Request, kind, param string) { 66 id, err := uuid.Parse(chi.URLParam(r, param)) 67 if err != nil { 68 writeErr(w, http.StatusBadRequest, "that is not an identifier", "") 69 return 70 } 71 msgs, err := h.svc.ListMessages(r.Context(), kind, id) 72 if err != nil { 73 writeErr(w, http.StatusInternalServerError, "could not read correspondence", "") 74 return 75 } 76 writeJSON(w, http.StatusOK, map[string]any{"messages": msgs, "count": len(msgs)}) 77} 78 79func (h *Handler) failMessage(w http.ResponseWriter, err error, msg Message) { 80 switch { 81 case errors.Is(err, ErrMailNotConfigured): 82 // 409 rather than 500: nothing is broken, the organization simply has not finished setting mail up, 83 // and the message says which screen fixes it. 84 writeErr(w, http.StatusConflict, 85 "outbound mail is not set up for this organization yet, configure it in settings and send a test message", "") 86 case errors.Is(err, ErrRecipientUnknown): 87 writeErr(w, http.StatusNotFound, "no such recipient", "") 88 case errors.Is(err, ErrNoRecipient): 89 writeErr(w, http.StatusUnprocessableEntity, "that record has no email address", "") 90 case errors.Is(err, ErrMessageEmpty): 91 writeErr(w, http.StatusUnprocessableEntity, "a message needs a subject and a body", "") 92 case errors.Is(err, ErrTemplateUnknown): 93 writeErr(w, http.StatusNotFound, "no such template", "") 94 case msg.Status == "failed": 95 // THE MESSAGE ROW EXISTS. This is reported as a delivery failure with the transport's own scrubbed 96 // words, not as a lost message, so a recruiter knows the attempt is on the record and can retry. 97 writeJSON(w, http.StatusBadGateway, map[string]any{ 98 "error": err.Error(), "message_id": msg.ID, "status": "failed", 99 "note": "the message is recorded against the candidate and can be retried", 100 }) 101 default: 102 writeErr(w, http.StatusInternalServerError, "could not send the message", "") 103 } 104} 105 106type templateRequest struct { 107 Name string `json:"name"` 108 Audience string `json:"audience"` 109 Subject string `json:"subject"` 110 Body string `json:"body"` 111 Status *string `json:"status"` 112} 113 114type templateView struct { 115 ID string `json:"id"` 116 Name string `json:"name"` 117 Audience string `json:"audience"` 118 Subject string `json:"subject"` 119 Body string `json:"body"` 120 Status string `json:"status"` 121} 122 123func (h *Handler) listTemplates(w http.ResponseWriter, r *http.Request) { 124 out := make([]templateView, 0, 16) 125 err := h.svc.db.RunInTenantTx(r.Context(), func(ctx context.Context, tx pgx.Tx) error { 126 rows, e := tx.Query(ctx, `SELECT id::text, name, audience, subject, body, status 127 FROM message_templates ORDER BY status, lower(name)`) 128 if e != nil { 129 return e 130 } 131 defer rows.Close() 132 for rows.Next() { 133 var t templateView 134 if e := rows.Scan(&t.ID, &t.Name, &t.Audience, &t.Subject, &t.Body, &t.Status); e != nil { 135 return e 136 } 137 out = append(out, t) 138 } 139 return rows.Err() 140 }) 141 if err != nil { 142 writeErr(w, http.StatusInternalServerError, "could not read templates", "") 143 return 144 } 145 writeJSON(w, http.StatusOK, map[string]any{ 146 "templates": out, "count": len(out), 147 // The vocabulary is returned WITH the list so the interface never has to hard code it and drift. 148 "placeholders": Placeholders(), 149 }) 150} 151 152func (h *Handler) createTemplate(w http.ResponseWriter, r *http.Request) { 153 var in templateRequest 154 if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 64<<10)).Decode(&in); err != nil { 155 writeErr(w, http.StatusBadRequest, "invalid body", "") 156 return 157 } 158 if field, err := validTemplate(in); err != nil { 159 writeJSON(w, http.StatusUnprocessableEntity, map[string]string{"error": err.Error(), "field": field}) 160 return 161 } 162 actor := actorPtr(r.Context()) 163 var id string 164 err := h.svc.db.RunInTenantTx(r.Context(), func(ctx context.Context, tx pgx.Tx) error { 165 return tx.QueryRow(ctx, ` 166 INSERT INTO message_templates (organization_id, name, audience, subject, body, created_by) 167 VALUES (NULLIF(current_setting('app.current_org_id', true), '')::uuid, $1,$2,$3,$4,$5) 168 RETURNING id::text`, 169 strings.TrimSpace(in.Name), in.Audience, in.Subject, in.Body, actor).Scan(&id) 170 }) 171 if err != nil { 172 if strings.Contains(err.Error(), "duplicate key") { 173 writeErr(w, http.StatusConflict, "a template with that name already exists", "") 174 return 175 } 176 writeErr(w, http.StatusInternalServerError, "could not create the template", "") 177 return 178 } 179 writeJSON(w, http.StatusCreated, map[string]any{"id": id}) 180} 181 182func (h *Handler) updateTemplate(w http.ResponseWriter, r *http.Request) { 183 id, err := uuid.Parse(chi.URLParam(r, "templateID")) 184 if err != nil { 185 writeErr(w, http.StatusBadRequest, "that is not an identifier", "") 186 return 187 } 188 var in templateRequest 189 if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 64<<10)).Decode(&in); err != nil { 190 writeErr(w, http.StatusBadRequest, "invalid body", "") 191 return 192 } 193 if in.Status != nil && *in.Status != "active" && *in.Status != "archived" { 194 writeJSON(w, http.StatusUnprocessableEntity, 195 map[string]string{"error": "a template is either active or archived", "field": "status"}) 196 return 197 } 198 err = h.svc.db.RunInTenantTx(r.Context(), func(ctx context.Context, tx pgx.Tx) error { 199 tag, e := tx.Exec(ctx, ` 200 UPDATE message_templates 201 SET name = coalesce(nullif(btrim($2),''), name), 202 subject = coalesce($3, subject), 203 body = coalesce($4, body), 204 status = coalesce($5, status), 205 updated_at = now() 206 WHERE id = $1`, id, in.Name, nullIfEmptyStr(in.Subject), nullIfEmptyStr(in.Body), in.Status) 207 if e != nil { 208 return e 209 } 210 if tag.RowsAffected() == 0 { 211 return ErrTemplateUnknown 212 } 213 return nil 214 }) 215 if err != nil { 216 if errors.Is(err, ErrTemplateUnknown) { 217 writeErr(w, http.StatusNotFound, "no such template", "") 218 return 219 } 220 writeErr(w, http.StatusInternalServerError, "could not update the template", "") 221 return 222 } 223 writeJSON(w, http.StatusOK, map[string]any{"updated": true}) 224} 225 226// previewTemplate resolves a template against a real record and returns exactly what would be sent, without 227// sending it. This is the difference between a template feature people trust and one they test by mailing 228// themselves. 229func (h *Handler) previewTemplate(w http.ResponseWriter, r *http.Request) { 230 var in MessageInput 231 if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 64<<10)).Decode(&in); err != nil { 232 writeErr(w, http.StatusBadRequest, "invalid body", "") 233 return 234 } 235 subject, body, to, err := h.svc.PreviewMessage(r.Context(), in) 236 if err != nil { 237 h.failMessage(w, err, Message{}) 238 return 239 } 240 resp := map[string]any{ 241 "to_address": to, "subject": subject, "body": body, 242 "sendable": to != "", 243 "note": "this is exactly what would be sent, nothing has been sent", 244 } 245 if to == "" { 246 // The text still renders, and the reason it cannot go out is stated plainly. Refusing the whole 247 // preview because a field is blank would send a recruiter hunting a bug that is not there. 248 resp["note"] = "this record has no email address, so the message can be previewed but not sent" 249 } 250 writeJSON(w, http.StatusOK, resp) 251} 252 253func validTemplate(in templateRequest) (string, error) { 254 if n := strings.TrimSpace(in.Name); n == "" || len(n) > 120 { 255 return "name", errors.New("a template needs a name of up to 120 characters") 256 } 257 if in.Audience != "candidate" && in.Audience != "contact" { 258 return "audience", errors.New("a template is written for a candidate or a contact") 259 } 260 if len(in.Subject) > 300 { 261 return "subject", errors.New("a subject may be up to 300 characters") 262 } 263 if strings.TrimSpace(in.Body) == "" || len(in.Body) > 20000 { 264 return "body", errors.New("a template needs a body of up to 20000 characters") 265 } 266 if bad := unknownPlaceholders(in.Subject + " " + in.Body); bad != "" { 267 // REFUSED RATHER THAN LEFT TO RENDER LITERALLY. A template carrying an unknown token sends a message 268 // with a visible curly brace to a candidate, which reads as a broken mail merge and costs the 269 // relationship. 270 return "body", errors.New("this template uses a placeholder this system cannot fill: " + bad) 271 } 272 return "", nil 273} 274 275func nullIfEmptyStr(s string) any { 276 if s == "" { 277 return nil 278 } 279 return s 280} 281 282// MailSyncRoutes are the caller's OWN mailbox. Every route here acts on the signed in user and takes no user 283// parameter, deliberately: a mailbox belongs to a person, and an endpoint that let one person configure 284// another's would be a way to point somebody else's credentials at a server you control. 285// 286// The tier is candidate.write, the same as sending, because connecting a mailbox is a recruiter setting up 287// their own working tools rather than an administrative act over the organization. 288func (h *Handler) MailSyncRoutes(r chi.Router) { 289 write := security.RequireCapability(security.CapCandidateWrite) 290 r.With(write).Get("/mail/account", h.getMailAccount) 291 r.With(write).Put("/mail/account", h.putMailAccount) 292 r.With(write).Delete("/mail/account", h.deleteMailAccount) 293 r.With(write).Post("/mail/account/test", h.testMailAccount) 294 r.With(write).Post("/mail/account/enabled", h.setMailEnabled) 295 r.With(write).Post("/mail/sync", h.syncMail) 296} 297 298func (h *Handler) getMailAccount(w http.ResponseWriter, r *http.Request) { 299 a, found, err := h.svc.GetMailAccount(r.Context()) 300 if err != nil { 301 writeErr(w, http.StatusInternalServerError, "could not read the mailbox configuration", "") 302 return 303 } 304 writeJSON(w, http.StatusOK, map[string]any{ 305 "connected": found, "account": a, 306 "note": "only message HEADERS are read, never message bodies, and correspondence with people who " + 307 "are not in this organization is discarded and never stored", 308 }) 309} 310 311func (h *Handler) putMailAccount(w http.ResponseWriter, r *http.Request) { 312 var in MailAccountInput 313 if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 8<<10)).Decode(&in); err != nil { 314 writeErr(w, http.StatusBadRequest, "invalid body", "") 315 return 316 } 317 if err := h.svc.SaveMailAccount(r.Context(), in, clientIPOf(r), r.UserAgent()); err != nil { 318 h.failMail(w, err) 319 return 320 } 321 writeJSON(w, http.StatusOK, map[string]any{ 322 "saved": true, 323 "note": "test the connection before switching sync on, an unproven mailbox never syncs", 324 }) 325} 326 327func (h *Handler) deleteMailAccount(w http.ResponseWriter, r *http.Request) { 328 if err := h.svc.DisconnectMailbox(r.Context(), clientIPOf(r), r.UserAgent()); err != nil { 329 h.failMail(w, err) 330 return 331 } 332 writeJSON(w, http.StatusOK, map[string]any{ 333 "disconnected": true, 334 "note": "the stored password and the sync history are gone, the activities already logged remain", 335 }) 336} 337 338func (h *Handler) testMailAccount(w http.ResponseWriter, r *http.Request) { 339 if err := h.svc.TestMailbox(r.Context()); err != nil { 340 h.failMail(w, err) 341 return 342 } 343 writeJSON(w, http.StatusOK, map[string]any{"verified": true}) 344} 345 346func (h *Handler) setMailEnabled(w http.ResponseWriter, r *http.Request) { 347 var in struct { 348 Enabled bool `json:"enabled"` 349 } 350 if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<10)).Decode(&in); err != nil { 351 writeErr(w, http.StatusBadRequest, "invalid body", "") 352 return 353 } 354 if err := h.svc.SetMailboxEnabled(r.Context(), in.Enabled); err != nil { 355 h.failMail(w, err) 356 return 357 } 358 writeJSON(w, http.StatusOK, map[string]any{"enabled": in.Enabled}) 359} 360 361func (h *Handler) syncMail(w http.ResponseWriter, r *http.Request) { 362 res, err := h.svc.SyncMailbox(r.Context()) 363 if err != nil { 364 h.failMail(w, err) 365 return 366 } 367 writeJSON(w, http.StatusOK, res) 368} 369 370func (h *Handler) failMail(w http.ResponseWriter, err error) { 371 switch { 372 case errors.Is(err, ErrMailboxNotConfigured): 373 writeErr(w, http.StatusNotFound, "no mailbox is connected", "") 374 case errors.Is(err, ErrMailInvalid): 375 // A configuration mistake, not a transport failure. These shared a message prefix with connection 376 // errors, so every validation error reported itself as a bad gateway until a sentinel separated them. 377 writeErr(w, http.StatusUnprocessableEntity, strings.TrimPrefix(err.Error(), "recruiting: "), "") 378 case errors.Is(err, ErrMailboxUnverified): 379 writeErr(w, http.StatusConflict, 380 "this mailbox has not been verified, test the connection before switching sync on", "") 381 case strings.Contains(err.Error(), "recruiting: "): 382 // The transport's own words, already scrubbed of the credentials by the service, because "could not 383 // connect" sends somebody to a support queue while "no such host" sends them to their typo. 384 writeErr(w, http.StatusBadGateway, strings.TrimPrefix(err.Error(), "recruiting: "), "") 385 default: 386 writeErr(w, http.StatusInternalServerError, "could not reach the mailbox", "") 387 } 388} 389 390func clientIPOf(r *http.Request) string { return r.Header.Get("X-Forwarded-For") } 391