Janady13/missionmatch / internal/modules/careers/handler.go

1package careers 2 3import ( 4 "encoding/json" 5 "errors" 6 "io" 7 "log" 8 "net/http" 9 "strings" 10 11 "github.com/go-chi/chi/v5" 12 "github.com/google/uuid" 13 14 "github.com/missionworkforce/missionmatch/internal/platform/security" 15) 16 17type Handler struct{ svc *Service } 18 19func NewHandler(svc *Service) *Handler { return &Handler{svc: svc} } 20 21// PublicRoutes are UNAUTHENTICATED and are the only surface in this product a stranger can reach that touches 22// a tenant's data. They are mounted behind their own rate limiter in cmd/api, they take no cookie, and they 23// return only fields that were written for publication. 24// 25// THERE IS NO CSRF HERE, deliberately and correctly: CSRF protects a request that carries ambient authority, 26// and these carry none. There is no session to ride. What protects them is that they can only ever read a 27// PUBLISHED posting and only ever write a row into job_applications, which is a staging table nothing 28// downstream trusts. 29func (h *Handler) PublicRoutes(r chi.Router) { 30 r.Get("/careers/{slug}", h.publicList) 31 r.Get("/careers/{slug}/postings/{token}", h.publicPosting) 32 r.Post("/careers/{slug}/postings/{token}/apply", h.publicApply) 33 // Interview self scheduling. Same public shape as a job posting: an opaque token, no session, and one 34 // 404 for every reason a link might not work. 35 r.Get("/careers/{slug}/schedule/{token}", h.publicOffer) 36 r.Post("/careers/{slug}/schedule/{token}/book", h.publicBook) 37} 38 39// Routes are the tenant side. Publishing is requirement.write, the tier that already owns a requisition, 40// because a posting is the public face of one. Reviewing inbound applications is candidate.write, because 41// deciding what happens to a person who applied is recruiting work. 42func (h *Handler) Routes(r chi.Router) { 43 read := security.RequireCapability(security.CapCandidateRead) 44 write := security.RequireCapability(security.CapCandidateWrite) 45 publish := security.RequireCapability(security.CapRequirementEdit) 46 47 r.With(read).Get("/job-postings", h.listPostings) 48 r.With(publish).Post("/job-postings", h.createPosting) 49 r.With(publish).Post("/job-postings/{postingID}/status", h.setStatus) 50 r.With(read).Get("/job-applications", h.listApplications) 51 r.With(write).Post("/job-applications/{appID}/review", h.review) 52 r.With(write).Post("/job-applications/{appID}/convert", h.convert) 53 54 r.With(read).Get("/interview-offers", h.listOffers) 55 r.With(write).Post("/interview-offers", h.createOffer) 56 r.With(write).Post("/interview-offers/{offerID}/withdraw", h.withdrawOffer) 57} 58 59func (h *Handler) publicOffer(w http.ResponseWriter, r *http.Request) { 60 o, err := h.svc.GetPublicOffer(r.Context(), chi.URLParam(r, "slug"), chi.URLParam(r, "token")) 61 if err != nil { 62 h.failPublic(w, err) 63 return 64 } 65 writeJSON(w, http.StatusOK, o) 66} 67 68func (h *Handler) publicBook(w http.ResponseWriter, r *http.Request) { 69 var in struct { 70 SlotID string `json:"slot_id"` 71 } 72 if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 4<<10)).Decode(&in); err != nil { 73 writeErr(w, http.StatusBadRequest, "invalid request") 74 return 75 } 76 when, err := h.svc.BookSlot(r.Context(), chi.URLParam(r, "slug"), chi.URLParam(r, "token"), 77 in.SlotID, clientIP(r)) 78 if err != nil { 79 h.failPublic(w, err) 80 return 81 } 82 writeJSON(w, http.StatusOK, map[string]any{ 83 "booked": true, "scheduled_at": when, 84 "note": "your interview is confirmed, a calendar invitation has been sent if an address is on file", 85 }) 86} 87 88func (h *Handler) listOffers(w http.ResponseWriter, r *http.Request) { 89 out, err := h.svc.ListOffers(r.Context()) 90 if err != nil { 91 writeErr(w, http.StatusInternalServerError, "could not read scheduling offers") 92 return 93 } 94 writeJSON(w, http.StatusOK, map[string]any{"offers": out, "count": len(out)}) 95} 96 97func (h *Handler) createOffer(w http.ResponseWriter, r *http.Request) { 98 var in OfferInput 99 if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 16<<10)).Decode(&in); err != nil { 100 writeErr(w, http.StatusBadRequest, "invalid body") 101 return 102 } 103 id, token, err := h.svc.CreateOffer(r.Context(), in, clientIP(r), r.UserAgent()) 104 if err != nil { 105 if strings.Contains(err.Error(), "careers:") { 106 writeErr(w, http.StatusUnprocessableEntity, strings.TrimPrefix(err.Error(), "careers: ")) 107 return 108 } 109 // The cause is LOGGED, not returned. A generic message to the caller is right; a generic message in 110 // the server log is how a 500 becomes an afternoon of guessing. 111 log.Printf("careers: create offer: %v", err) 112 writeErr(w, http.StatusInternalServerError, "could not create the scheduling offer") 113 return 114 } 115 writeJSON(w, http.StatusCreated, map[string]any{ 116 "id": id, "public_token": token, 117 "note": "send the candidate the scheduling link, the interview is created when they pick a time", 118 }) 119} 120 121func (h *Handler) withdrawOffer(w http.ResponseWriter, r *http.Request) { 122 id, err := uuid.Parse(chi.URLParam(r, "offerID")) 123 if err != nil { 124 writeErr(w, http.StatusBadRequest, "that is not an offer identifier") 125 return 126 } 127 if err := h.svc.WithdrawOffer(r.Context(), id, clientIP(r), r.UserAgent()); err != nil { 128 if errors.Is(err, ErrNotFound) { 129 writeErr(w, http.StatusNotFound, "no such open offer") 130 return 131 } 132 writeErr(w, http.StatusInternalServerError, "could not withdraw the offer") 133 return 134 } 135 writeJSON(w, http.StatusOK, map[string]any{"withdrawn": true}) 136} 137 138func (h *Handler) publicList(w http.ResponseWriter, r *http.Request) { 139 posts, employer, err := h.svc.ListPublicPostings(r.Context(), chi.URLParam(r, "slug")) 140 if err != nil { 141 h.failPublic(w, err) 142 return 143 } 144 writeJSON(w, http.StatusOK, map[string]any{ 145 "employer": employer, "postings": posts, "count": len(posts), 146 }) 147} 148 149func (h *Handler) publicPosting(w http.ResponseWriter, r *http.Request) { 150 p, err := h.svc.GetPublicPosting(r.Context(), chi.URLParam(r, "slug"), chi.URLParam(r, "token")) 151 if err != nil { 152 h.failPublic(w, err) 153 return 154 } 155 writeJSON(w, http.StatusOK, p) 156} 157 158// MaxApplyBytes bounds a public upload. A resume is tens of kilobytes; ten megabytes is generous and small 159// enough that an unauthenticated endpoint cannot be used to fill a volume. 160const MaxApplyBytes = 10 << 20 161 162func (h *Handler) publicApply(w http.ResponseWriter, r *http.Request) { 163 // The body is bounded BEFORE it is parsed, because this is the one endpoint anybody on the internet can 164 // post to and the reader is the only place a flood can be stopped cheaply. 165 r.Body = http.MaxBytesReader(w, r.Body, MaxApplyBytes+(1<<20)) 166 var in Submission 167 if strings.HasPrefix(r.Header.Get("Content-Type"), "multipart/form-data") { 168 if err := r.ParseMultipartForm(4 << 20); err != nil { 169 writeErr(w, http.StatusRequestEntityTooLarge, "the submission is too large") 170 return 171 } 172 in = Submission{ 173 FullName: r.FormValue("full_name"), 174 Email: r.FormValue("email"), 175 Phone: r.FormValue("phone"), 176 Location: r.FormValue("location"), 177 CoverNote: r.FormValue("cover_note"), 178 Clearance: r.FormValue("clearance"), 179 Source: r.FormValue("source"), 180 ConsentText: r.FormValue("consent_text"), 181 Consented: r.FormValue("consented") == "true", 182 } 183 if file, hdr, ferr := r.FormFile("resume"); ferr == nil { 184 defer file.Close() 185 b, rerr := io.ReadAll(io.LimitReader(file, MaxApplyBytes+1)) 186 if rerr != nil || len(b) > MaxApplyBytes { 187 writeErr(w, http.StatusRequestEntityTooLarge, "that resume is too large") 188 return 189 } 190 in.ResumeBytes, in.ResumeName, in.ResumeType = b, hdr.Filename, hdr.Header.Get("Content-Type") 191 } 192 } else { 193 if err := json.NewDecoder(r.Body).Decode(&in); err != nil { 194 writeErr(w, http.StatusBadRequest, "invalid submission") 195 return 196 } 197 } 198 in.SubmittedIP = clientIP(r) 199 id, err := h.svc.Apply(r.Context(), chi.URLParam(r, "slug"), chi.URLParam(r, "token"), in) 200 if err != nil { 201 h.failPublic(w, err) 202 return 203 } 204 // The response says only that it arrived. It carries no candidate identifier, no indication of whether 205 // this person is already known, and nothing about the organization's pipeline, because a public endpoint 206 // that answers those questions answers them for anybody. 207 writeJSON(w, http.StatusCreated, map[string]any{ 208 "received": true, "reference": id, 209 "note": "your application has been received, the recruiting team will be in touch if there is a fit", 210 }) 211} 212 213func (h *Handler) failPublic(w http.ResponseWriter, err error) { 214 switch { 215 case errors.Is(err, ErrSlotTaken): 216 // Distinguishable from a dead link, deliberately: the candidate needs to know to pick another time 217 // rather than to ask whether the link is broken. 218 writeErr(w, http.StatusConflict, "that time has just been taken, please choose another") 219 case errors.Is(err, ErrOfferUnavailable): 220 writeErr(w, http.StatusNotFound, "that scheduling link is no longer available") 221 case errors.Is(err, ErrNotFound), errors.Is(err, ErrPostingClosed): 222 // ONE ANSWER for a missing employer, a missing posting, a draft posting and a closed one. A 223 // distinguishable response would let anybody map which customers exist and which roles they are 224 // quietly working. 225 writeErr(w, http.StatusNotFound, "that job posting is not available") 226 case errors.Is(err, ErrAlreadyApplied): 227 // Deliberately unrevealing: it does not confirm anything about the person, only that this posting 228 // already has a submission under that address. 229 writeErr(w, http.StatusConflict, "an application for this posting has already been submitted with that email address") 230 case errors.Is(err, ErrInvalid): 231 writeErr(w, http.StatusUnprocessableEntity, strings.TrimPrefix(err.Error(), "careers: ")) 232 case errors.Is(err, ErrNoDatabase): 233 writeErr(w, http.StatusServiceUnavailable, "applications are temporarily unavailable") 234 default: 235 writeErr(w, http.StatusInternalServerError, "could not accept the application") 236 } 237} 238 239func (h *Handler) listPostings(w http.ResponseWriter, r *http.Request) { 240 out, err := h.svc.ListPostings(r.Context()) 241 if err != nil { 242 writeErr(w, http.StatusInternalServerError, "could not read postings") 243 return 244 } 245 writeJSON(w, http.StatusOK, map[string]any{"postings": out, "count": len(out)}) 246} 247 248func (h *Handler) createPosting(w http.ResponseWriter, r *http.Request) { 249 var in PostingInput 250 if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 64<<10)).Decode(&in); err != nil { 251 writeErr(w, http.StatusBadRequest, "invalid body") 252 return 253 } 254 id, token, err := h.svc.CreatePosting(r.Context(), in) 255 if err != nil { 256 if strings.Contains(err.Error(), "careers:") { 257 writeErr(w, http.StatusUnprocessableEntity, strings.TrimPrefix(err.Error(), "careers: ")) 258 return 259 } 260 writeErr(w, http.StatusInternalServerError, "could not create the posting") 261 return 262 } 263 writeJSON(w, http.StatusCreated, map[string]any{ 264 "id": id, "public_token": token, "status": "draft", 265 "note": "the posting is a DRAFT and is not public yet, publish it when the copy is right", 266 }) 267} 268 269func (h *Handler) setStatus(w http.ResponseWriter, r *http.Request) { 270 id, err := uuid.Parse(chi.URLParam(r, "postingID")) 271 if err != nil { 272 writeErr(w, http.StatusBadRequest, "that is not a posting identifier") 273 return 274 } 275 var in struct { 276 Status string `json:"status"` 277 } 278 if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 2<<10)).Decode(&in); err != nil { 279 writeErr(w, http.StatusBadRequest, "invalid body") 280 return 281 } 282 if err := h.svc.SetPostingStatus(r.Context(), id, in.Status, clientIP(r), r.UserAgent()); err != nil { 283 if errors.Is(err, ErrNotFound) { 284 writeErr(w, http.StatusNotFound, "no such posting") 285 return 286 } 287 writeErr(w, http.StatusUnprocessableEntity, strings.TrimPrefix(err.Error(), "careers: ")) 288 return 289 } 290 writeJSON(w, http.StatusOK, map[string]any{"status": in.Status}) 291} 292 293func (h *Handler) listApplications(w http.ResponseWriter, r *http.Request) { 294 out, err := h.svc.ListApplications(r.Context(), r.URL.Query().Get("status")) 295 if err != nil { 296 writeErr(w, http.StatusInternalServerError, "could not read applications") 297 return 298 } 299 writeJSON(w, http.StatusOK, map[string]any{"applications": out, "count": len(out)}) 300} 301 302func (h *Handler) review(w http.ResponseWriter, r *http.Request) { 303 id, err := uuid.Parse(chi.URLParam(r, "appID")) 304 if err != nil { 305 writeErr(w, http.StatusBadRequest, "that is not an application identifier") 306 return 307 } 308 var in struct { 309 Status string `json:"status"` 310 Reason string `json:"reason"` 311 } 312 if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 8<<10)).Decode(&in); err != nil { 313 writeErr(w, http.StatusBadRequest, "invalid body") 314 return 315 } 316 if err := h.svc.ReviewApplication(r.Context(), id, in.Status, in.Reason, clientIP(r), r.UserAgent()); err != nil { 317 if errors.Is(err, ErrNotFound) { 318 writeErr(w, http.StatusNotFound, "no such application, or it has already been converted") 319 return 320 } 321 writeErr(w, http.StatusUnprocessableEntity, strings.TrimPrefix(err.Error(), "careers: ")) 322 return 323 } 324 writeJSON(w, http.StatusOK, map[string]any{"status": in.Status}) 325} 326 327func (h *Handler) convert(w http.ResponseWriter, r *http.Request) { 328 id, err := uuid.Parse(chi.URLParam(r, "appID")) 329 if err != nil { 330 writeErr(w, http.StatusBadRequest, "that is not an application identifier") 331 return 332 } 333 candID, err := h.svc.ConvertApplication(r.Context(), id, clientIP(r), r.UserAgent()) 334 if err != nil { 335 if errors.Is(err, ErrNotFound) { 336 writeErr(w, http.StatusNotFound, "no such application, or it has already been converted") 337 return 338 } 339 writeErr(w, http.StatusInternalServerError, "could not convert the application") 340 return 341 } 342 writeJSON(w, http.StatusOK, map[string]any{"candidate_id": candID, "status": "converted"}) 343} 344 345func clientIP(r *http.Request) string { 346 if v := r.Header.Get("X-Forwarded-For"); v != "" { 347 if i := strings.IndexByte(v, ','); i > 0 { 348 return strings.TrimSpace(v[:i]) 349 } 350 return strings.TrimSpace(v) 351 } 352 return "" 353} 354 355func writeJSON(w http.ResponseWriter, code int, v any) { 356 w.Header().Set("Content-Type", "application/json") 357 w.WriteHeader(code) 358 _ = json.NewEncoder(w).Encode(v) 359} 360 361func writeErr(w http.ResponseWriter, code int, msg string) { 362 writeJSON(w, code, map[string]string{"error": msg}) 363} 364