Janady13/missionmatch / internal/platform/samawards/client.go

1// Package samawards is a typed client for the SAM.gov Contract Awards API 2// (open.gsa.gov/api/contract-awards), the RESTful replacement for the retiring FPDS Atom feed. It 3// fetches federal contract award and incumbent data using the same SAM api_key the opportunities feed 4// uses, and normalizes it to a flat app shape. It has no database dependency: it fetches and 5// normalizes, the ingest writes the cache. The api_key is held here and only ever added as a query 6// parameter, never logged or placed in an error string. 7package samawards 8 9import ( 10 "context" 11 "encoding/json" 12 "errors" 13 "fmt" 14 "io" 15 "net/http" 16 "net/url" 17 "strconv" 18 "strings" 19 "time" 20) 21 22// Base endpoints. Prod is the default; the alpha (prodlike) is selectable via the env for testing. 23const ( 24 BaseProd = "https://api.sam.gov/contract-awards/v1/search" 25 BaseAlpha = "https://api-alpha.sam.gov/contract-awards/v1/search" 26) 27 28const ( 29 maxLimit = 100 // the API caps a page at 100 30 offsetWindow = 400000 // offset times limit may not exceed this 31 throttleCap = 1024 // max body bytes captured from a 429 32 pageGap = 250 * time.Millisecond 33) 34 35// ErrThrottled is the sentinel for a 429 (daily quota). Detect with errors.Is(err, ErrThrottled). 36var ErrThrottled = errors.New("samawards: rate limited (429)") 37 38// ThrottleError carries the Retry-After hint. It satisfies errors.Is(err, ErrThrottled). 39type ThrottleError struct { 40 RetryAfter string 41 Body string 42} 43 44func (e *ThrottleError) Error() string { 45 if e.RetryAfter != "" { 46 return fmt.Sprintf("samawards: rate limited (429), retry after %s", e.RetryAfter) 47 } 48 return "samawards: rate limited (429)" 49} 50 51func (e *ThrottleError) Is(target error) bool { return target == ErrThrottled } 52 53// Client is a typed Contract Awards client over the built in net/http. 54type Client struct { 55 base string 56 key string 57 http *http.Client 58} 59 60// New builds a client. An empty base defaults to prod. 61func New(base, key string) *Client { 62 if strings.TrimSpace(base) == "" { 63 base = BaseProd 64 } 65 return &Client{base: base, key: key, http: &http.Client{Timeout: 60 * time.Second}} 66} 67 68// SearchParams are the supported filters. NAICS is up to 100 codes (the API joins them with a tilde). 69// Department is a partial contracting department name (for example DEFENSE). AwardeeUEIs scopes to 70// specific recipients for own past performance. The Signed window filters by dateSigned. 71type SearchParams struct { 72 NAICS []string 73 Department string 74 AwardeeUEIs []string 75 SignedFrom time.Time 76 SignedTo time.Time 77 Limit int 78 Offset int 79} 80 81// SearchResult is one page: the raw award records and the total match count the API reports. 82type SearchResult struct { 83 Records []json.RawMessage 84 Total int 85} 86 87// Search fetches one page. It maps a 429 to *ThrottleError and any other non 200 to an error that never 88// includes the api_key. 89func (c *Client) Search(ctx context.Context, p SearchParams) (SearchResult, error) { 90 limit := p.Limit 91 if limit < 1 { 92 limit = 10 93 } 94 if limit > maxLimit { 95 limit = maxLimit 96 } 97 q := url.Values{} 98 q.Set("api_key", c.key) 99 q.Set("limit", strconv.Itoa(limit)) 100 q.Set("offset", strconv.Itoa(p.Offset)) 101 if len(p.NAICS) > 0 { 102 q.Set("naicsCode", strings.Join(cap100(p.NAICS), "~")) 103 } 104 if d := strings.TrimSpace(p.Department); d != "" { 105 q.Set("contractingDepartmentName", d) 106 } 107 if len(p.AwardeeUEIs) > 0 { 108 q.Set("awardeeUniqueEntityId", strings.Join(cap100(p.AwardeeUEIs), "~")) 109 } 110 if !p.SignedFrom.IsZero() && !p.SignedTo.IsZero() { 111 q.Set("dateSigned", fmt.Sprintf("[%s,%s]", p.SignedFrom.Format("01/02/2006"), p.SignedTo.Format("01/02/2006"))) 112 } 113 114 req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.base+"?"+q.Encode(), nil) 115 if err != nil { 116 // The error embeds the full URL including the api_key, so return a generic message. 117 return SearchResult{}, errors.New("samawards: failed to build request") 118 } 119 req.Header.Set("Accept", "application/json") 120 121 resp, err := c.http.Do(req) 122 if err != nil { 123 return SearchResult{}, fmt.Errorf("samawards: request: %w", err) 124 } 125 defer resp.Body.Close() 126 127 if resp.StatusCode == http.StatusTooManyRequests { 128 body, _ := io.ReadAll(io.LimitReader(resp.Body, throttleCap)) 129 return SearchResult{}, &ThrottleError{RetryAfter: resp.Header.Get("Retry-After"), Body: string(body)} 130 } 131 if resp.StatusCode != http.StatusOK { 132 body, _ := io.ReadAll(io.LimitReader(resp.Body, throttleCap)) 133 return SearchResult{}, fmt.Errorf("samawards: status %d: %s", resp.StatusCode, strings.TrimSpace(string(body))) 134 } 135 136 var env struct { 137 AwardSummary []json.RawMessage `json:"awardSummary"` 138 TotalRecords NumericText `json:"totalRecords"` 139 } 140 if err := json.NewDecoder(resp.Body).Decode(&env); err != nil { 141 return SearchResult{}, fmt.Errorf("samawards: decode: %w", err) 142 } 143 return SearchResult{Records: env.AwardSummary, Total: env.TotalRecords.Int()}, nil 144} 145 146// NumericText decodes a field the Contract Awards API returns inconsistently as either a JSON number or 147// a quoted string (totalRecords and the dollar amounts both arrive as strings) into the literal text, so 148// both forms parse the same way downstream. This was a real wire mismatch: the count and the dollars are 149// strings on the wire, which a plain int or json.Number field cannot decode. 150type NumericText string 151 152// UnmarshalJSON accepts a JSON number, a quoted string, or null. 153func (t *NumericText) UnmarshalJSON(b []byte) error { 154 s := strings.TrimSpace(string(b)) 155 if s == "null" { 156 *t = "" 157 return nil 158 } 159 *t = NumericText(strings.TrimSpace(strings.Trim(s, `"`))) 160 return nil 161} 162 163// Int parses the text as an integer, tolerating a decimal point. It returns 0 when the text is empty or 164// unparseable, which for a record count safely stops pagination rather than looping. 165func (t NumericText) Int() int { 166 s := string(t) 167 if n, err := strconv.Atoi(s); err == nil { 168 return n 169 } 170 if f, err := strconv.ParseFloat(s, 64); err == nil { 171 return int(f) 172 } 173 return 0 174} 175 176// SearchAll paginates by offset up to pageCap pages, stopping at the total or the API offset ceiling. On 177// a 429 it returns the records collected so far together with ErrThrottled so the caller keeps the 178// partial pull and stops gracefully. 179func (c *Client) SearchAll(ctx context.Context, p SearchParams, pageCap int) (recs []json.RawMessage, total int, capped bool, err error) { 180 limit := p.Limit 181 if limit < 1 { 182 limit = maxLimit 183 } 184 if limit > maxLimit { 185 limit = maxLimit 186 } 187 for page := 0; page < pageCap; page++ { 188 pp := p 189 pp.Limit = limit 190 pp.Offset = page * limit 191 if pp.Offset+limit > offsetWindow { 192 capped = true 193 break 194 } 195 res, e := c.Search(ctx, pp) 196 if e != nil { 197 if errors.Is(e, ErrThrottled) { 198 return recs, total, true, ErrThrottled 199 } 200 return recs, total, capped, e 201 } 202 total = res.Total 203 recs = append(recs, res.Records...) 204 if len(res.Records) < limit || len(recs) >= total { 205 return recs, total, capped, nil 206 } 207 select { 208 case <-ctx.Done(): 209 return recs, total, true, ctx.Err() 210 case <-time.After(pageGap): 211 } 212 } 213 if len(recs) < total { 214 capped = true 215 } 216 return recs, total, capped, nil 217} 218 219// cap100 caps a slice to the API limit of 100 values per multi value parameter. 220func cap100(s []string) []string { 221 if len(s) > 100 { 222 return s[:100] 223 } 224 return s 225} 226