2022-06-14 08:46:33 -05:00
package httpapi
import (
2024-07-03 08:42:23 -10:00
"database/sql"
2025-02-18 14:14:30 +00:00
"encoding/json"
2024-03-22 14:22:47 -05:00
"errors"
2022-06-14 08:46:33 -05:00
"fmt"
"net/url"
2026-09-09 11:25:17 -07:00
"slices"
2022-06-14 08:46:33 -05:00
"strconv"
"strings"
2023-03-01 23:28:56 -06:00
"time"
2022-06-14 08:46:33 -05:00
"github.com/google/uuid"
"golang.org/x/xerrors"
2023-03-01 23:28:56 -06:00
2023-08-18 13:55:43 -05:00
"github.com/coder/coder/v2/codersdk"
2022-06-14 08:46:33 -05:00
)
// QueryParamParser is a helper for parsing all query params and gathering all
// errors in 1 sweep. This means all invalid fields are returned at once,
// rather than only returning the first error
type QueryParamParser struct {
// Errors is the set of errors to return via the API. If the length
// of this set is 0, there are no errors!.
2022-07-12 19:15:02 -05:00
Errors [] codersdk . ValidationError
2023-03-01 23:28:56 -06:00
// Parsed is a map of all query params that were parsed. This is useful
// for checking if extra query params were passed in.
Parsed map [ string ] bool
2024-02-20 15:58:43 -08:00
// RequiredNotEmptyParams is a map of all query params that are required. This is useful
2023-04-03 20:59:59 -05:00
// for forcing a value to be provided.
2024-02-20 15:58:43 -08:00
RequiredNotEmptyParams map [ string ] bool
2022-06-14 08:46:33 -05:00
}
func NewQueryParamParser () * QueryParamParser {
return & QueryParamParser {
2024-02-20 15:58:43 -08:00
Errors : [] codersdk . ValidationError {},
Parsed : map [ string ] bool {},
RequiredNotEmptyParams : map [ string ] bool {},
2022-06-14 08:46:33 -05:00
}
}
2023-03-01 23:28:56 -06:00
// ErrorExcessParams checks if any query params were passed in that were not
// parsed. If so, it adds an error to the parser as these values are not valid
// query parameters.
func ( p * QueryParamParser ) ErrorExcessParams ( values url . Values ) {
for k := range values {
if _ , ok := p . Parsed [ k ]; ! ok {
p . Errors = append ( p . Errors , codersdk . ValidationError {
Field : k ,
2023-08-13 11:47:44 -05:00
Detail : fmt . Sprintf ( "%q is not a valid query param" , k ),
2023-03-01 23:28:56 -06:00
})
}
}
}
func ( p * QueryParamParser ) addParsed ( key string ) {
p . Parsed [ key ] = true
}
2023-04-03 20:59:59 -05:00
func ( p * QueryParamParser ) UInt ( vals url . Values , def uint64 , queryParam string ) uint64 {
v , err := parseQueryParam ( p , vals , func ( v string ) ( uint64 , error ) {
return strconv . ParseUint ( v , 10 , 64 )
}, def , queryParam )
if err != nil {
p . Errors = append ( p . Errors , codersdk . ValidationError {
Field : queryParam ,
2024-03-21 08:37:19 -05:00
Detail : fmt . Sprintf ( "Query param %q must be a valid positive integer: %s" , queryParam , err . Error ()),
2023-04-03 20:59:59 -05:00
})
return 0
}
return v
}
2022-06-14 08:46:33 -05:00
func ( p * QueryParamParser ) Int ( vals url . Values , def int , queryParam string ) int {
2023-03-01 23:28:56 -06:00
v , err := parseQueryParam ( p , vals , strconv . Atoi , def , queryParam )
2022-06-14 08:46:33 -05:00
if err != nil {
2022-07-12 19:15:02 -05:00
p . Errors = append ( p . Errors , codersdk . ValidationError {
2022-06-14 08:46:33 -05:00
Field : queryParam ,
2024-03-21 08:37:19 -05:00
Detail : fmt . Sprintf ( "Query param %q must be a valid integer: %s" , queryParam , err . Error ()),
2022-06-14 08:46:33 -05:00
})
}
return v
}
2025-03-21 13:30:47 +01:00
func ( p * QueryParamParser ) Int64 ( vals url . Values , def int64 , queryParam string ) int64 {
v , err := parseQueryParam ( p , vals , func ( v string ) ( int64 , error ) {
return strconv . ParseInt ( v , 10 , 64 )
}, def , queryParam )
if err != nil {
p . Errors = append ( p . Errors , codersdk . ValidationError {
Field : queryParam ,
Detail : fmt . Sprintf ( "Query param %q must be a valid 64-bit integer: %s" , queryParam , err . Error ()),
})
return 0
}
return v
}
2024-03-05 15:05:15 +01:00
// PositiveInt32 function checks if the given value is 32-bit and positive.
//
// We can't use `uint32` as the value must be within the range <0,2147483647>
// as database expects it. Otherwise, the database query fails with `pq: OFFSET must not be negative`.
func ( p * QueryParamParser ) PositiveInt32 ( vals url . Values , def int32 , queryParam string ) int32 {
v , err := parseQueryParam ( p , vals , func ( v string ) ( int32 , error ) {
intValue , err := strconv . ParseInt ( v , 10 , 32 )
if err != nil {
return 0 , err
}
if intValue < 0 {
return 0 , xerrors . Errorf ( "value is negative" )
}
return int32 ( intValue ), nil
}, def , queryParam )
if err != nil {
p . Errors = append ( p . Errors , codersdk . ValidationError {
Field : queryParam ,
2024-03-21 08:37:19 -05:00
Detail : fmt . Sprintf ( "Query param %q must be a valid 32-bit positive integer: %s" , queryParam , err . Error ()),
2024-03-05 15:05:15 +01:00
})
}
return v
}
2025-09-09 15:12:24 -08:00
// PositiveInt64 function checks if the given value is 64-bit and positive.
func ( p * QueryParamParser ) PositiveInt64 ( vals url . Values , def int64 , queryParam string ) int64 {
v , err := parseQueryParam ( p , vals , func ( v string ) ( int64 , error ) {
intValue , err := strconv . ParseInt ( v , 10 , 64 )
if err != nil {
return 0 , err
}
if intValue < 0 {
return 0 , xerrors . Errorf ( "value is negative" )
}
return intValue , nil
}, def , queryParam )
if err != nil {
p . Errors = append ( p . Errors , codersdk . ValidationError {
Field : queryParam ,
Detail : fmt . Sprintf ( "Query param %q must be a valid 64-bit positive integer: %s" , queryParam , err . Error ()),
})
}
return v
}
2024-07-03 08:42:23 -10:00
// NullableBoolean will return a null sql value if no input is provided.
// SQLc still uses sql.NullBool rather than the generic type. So converting from
// the generic type is required.
func ( p * QueryParamParser ) NullableBoolean ( vals url . Values , def sql . NullBool , queryParam string ) sql . NullBool {
v , err := parseNullableQueryParam [ bool ]( p , vals , strconv . ParseBool , sql . Null [ bool ]{
V : def . Bool ,
Valid : def . Valid ,
}, queryParam )
if err != nil {
p . Errors = append ( p . Errors , codersdk . ValidationError {
Field : queryParam ,
Detail : fmt . Sprintf ( "Query param %q must be a valid boolean: %s" , queryParam , err . Error ()),
})
}
return sql . NullBool {
Bool : v . V ,
Valid : v . Valid ,
}
}
2023-10-11 09:26:22 -05:00
func ( p * QueryParamParser ) Boolean ( vals url . Values , def bool , queryParam string ) bool {
v , err := parseQueryParam ( p , vals , strconv . ParseBool , def , queryParam )
if err != nil {
p . Errors = append ( p . Errors , codersdk . ValidationError {
Field : queryParam ,
2024-03-21 08:37:19 -05:00
Detail : fmt . Sprintf ( "Query param %q must be a valid boolean: %s" , queryParam , err . Error ()),
2023-10-11 09:26:22 -05:00
})
}
return v
}
2024-02-20 15:58:43 -08:00
func ( p * QueryParamParser ) RequiredNotEmpty ( queryParam ... string ) * QueryParamParser {
for _ , q := range queryParam {
p . RequiredNotEmptyParams [ q ] = true
}
2023-04-03 20:59:59 -05:00
return p
}
2024-08-15 13:40:15 -05:00
// UUIDorName will parse a string as a UUID, if it fails, it uses the "fetchByName"
// function to return a UUID based on the value as a string.
// This is useful when fetching something like an organization by ID or by name.
func ( p * QueryParamParser ) UUIDorName ( vals url . Values , def uuid . UUID , queryParam string , fetchByName func ( name string ) ( uuid . UUID , error )) uuid . UUID {
return ParseCustom ( p , vals , def , queryParam , func ( v string ) ( uuid . UUID , error ) {
id , err := uuid . Parse ( v )
if err == nil {
return id , nil
}
return fetchByName ( v )
})
}
2022-06-14 08:46:33 -05:00
func ( p * QueryParamParser ) UUIDorMe ( vals url . Values , def uuid . UUID , me uuid . UUID , queryParam string ) uuid . UUID {
2023-03-01 23:28:56 -06:00
return ParseCustom ( p , vals , def , queryParam , func ( v string ) ( uuid . UUID , error ) {
if v == "me" {
return me , nil
}
return uuid . Parse ( v )
})
2022-06-14 08:46:33 -05:00
}
func ( p * QueryParamParser ) UUID ( vals url . Values , def uuid . UUID , queryParam string ) uuid . UUID {
2023-03-01 23:28:56 -06:00
v , err := parseQueryParam ( p , vals , uuid . Parse , def , queryParam )
2022-06-14 08:46:33 -05:00
if err != nil {
2022-07-12 19:15:02 -05:00
p . Errors = append ( p . Errors , codersdk . ValidationError {
2022-06-14 08:46:33 -05:00
Field : queryParam ,
Detail : fmt . Sprintf ( "Query param %q must be a valid uuid" , queryParam ),
})
}
return v
}
func ( p * QueryParamParser ) UUIDs ( vals url . Values , def [] uuid . UUID , queryParam string ) [] uuid . UUID {
2023-03-01 23:28:56 -06:00
return ParseCustomList ( p , vals , def , queryParam , func ( v string ) ( uuid . UUID , error ) {
return uuid . Parse ( strings . TrimSpace ( v ))
})
}
2022-06-14 08:46:33 -05:00
2026-09-09 11:25:17 -07:00
// RedirectURL parses queryParam as a URL and requires it to match the primary
// callback or one of the alternates. When the param is absent it returns primary.
func ( p * QueryParamParser ) RedirectURL ( vals url . Values , primary * url . URL , alternates [] * url . URL , queryParam string ) * url . URL {
v , err := parseQueryParam ( p , vals , url . Parse , primary , queryParam )
2024-02-20 15:58:43 -08:00
if err != nil {
p . Errors = append ( p . Errors , codersdk . ValidationError {
Field : queryParam ,
Detail : fmt . Sprintf ( "Query param %q must be a valid url: %s" , queryParam , err . Error ()),
})
2026-09-02 12:43:32 -07:00
// url.Parse returns a nil URL alongside its error, so the comparison
2026-09-09 11:25:17 -07:00
// below would panic. primary stands in: p.Errors is already non-empty,
// so every caller rejects the request before reading this.
return primary
2024-02-20 15:58:43 -08:00
}
2026-09-09 11:25:17 -07:00
// OAuth 2.1 §2.3.1 requires an exact match against a registered URI. RFC 8252
// §7.3 excepts the port of a loopback redirect URI; the comparator owns that rule.
matches := func ( a * url . URL ) bool { return codersdk . RedirectURIMatches ( v , a ) }
if ! matches ( primary ) && ! slices . ContainsFunc ( alternates , matches ) {
2024-02-20 15:58:43 -08:00
p . Errors = append ( p . Errors , codersdk . ValidationError {
Field : queryParam ,
2026-09-09 11:25:17 -07:00
Detail : fmt . Sprintf ( "Query param %q must match one of the application's registered redirect URIs; only the port of a loopback URI may differ" , queryParam ),
2024-02-20 15:58:43 -08:00
})
}
return v
}
2023-06-22 15:24:48 -05:00
func ( p * QueryParamParser ) Time ( vals url . Values , def time . Time , queryParam , layout string ) time . Time {
return p . timeWithMutate ( vals , def , queryParam , layout , nil )
}
// Time uses the default time format of RFC3339Nano and always returns a UTC time.
func ( p * QueryParamParser ) Time3339Nano ( vals url . Values , def time . Time , queryParam string ) time . Time {
layout := time . RFC3339Nano
2025-03-26 01:56:39 -05:00
// All search queries are forced to lowercase. But the RFC format requires
// upper case letters. So just uppercase the term.
return p . timeWithMutate ( vals , def , queryParam , layout , strings . ToUpper )
2023-06-22 15:24:48 -05:00
}
func ( p * QueryParamParser ) timeWithMutate ( vals url . Values , def time . Time , queryParam , layout string , mutate func ( term string ) string ) time . Time {
2023-03-01 23:28:56 -06:00
v , err := parseQueryParam ( p , vals , func ( term string ) ( time . Time , error ) {
2023-06-22 15:24:48 -05:00
if mutate != nil {
term = mutate ( term )
}
t , err := time . Parse ( layout , term )
if err != nil {
return time . Time {}, err
}
return t . UTC (), nil
2022-06-14 08:46:33 -05:00
}, def , queryParam )
if err != nil {
2022-07-12 19:15:02 -05:00
p . Errors = append ( p . Errors , codersdk . ValidationError {
2022-06-14 08:46:33 -05:00
Field : queryParam ,
2023-06-22 15:24:48 -05:00
Detail : fmt . Sprintf ( "Query param %q must be a valid date format (%s): %s" , queryParam , layout , err . Error ()),
2022-06-14 08:46:33 -05:00
})
}
return v
}
2023-03-01 23:28:56 -06:00
func ( p * QueryParamParser ) String ( vals url . Values , def string , queryParam string ) string {
2024-03-21 08:37:19 -05:00
v , err := parseQueryParam ( p , vals , func ( v string ) ( string , error ) {
2022-06-14 08:46:33 -05:00
return v , nil
}, def , queryParam )
2024-03-21 08:37:19 -05:00
if err != nil {
p . Errors = append ( p . Errors , codersdk . ValidationError {
Field : queryParam ,
Detail : fmt . Sprintf ( "Query param %q must be a valid string: %s" , queryParam , err . Error ()),
})
}
2022-06-24 10:02:23 -05:00
return v
}
2023-03-01 23:28:56 -06:00
func ( p * QueryParamParser ) Strings ( vals url . Values , def [] string , queryParam string ) [] string {
return ParseCustomList ( p , vals , def , queryParam , func ( v string ) ( string , error ) {
return v , nil
})
}
2025-02-18 14:14:30 +00:00
func ( p * QueryParamParser ) JSONStringMap ( vals url . Values , def map [ string ] string , queryParam string ) map [ string ] string {
v , err := parseQueryParam ( p , vals , func ( v string ) ( map [ string ] string , error ) {
var m map [ string ] string
if err := json . NewDecoder ( strings . NewReader ( v )). Decode ( & m ); err != nil {
return nil , err
}
return m , nil
}, def , queryParam )
if err != nil {
p . Errors = append ( p . Errors , codersdk . ValidationError {
Field : queryParam ,
Detail : fmt . Sprintf ( "Query param %q must be a valid JSON object: %s" , queryParam , err . Error ()),
})
}
return v
}
2025-08-21 15:03:34 -05:00
func ( p * QueryParamParser ) ProvisionerDaemonStatuses ( vals url . Values , def [] codersdk . ProvisionerDaemonStatus , queryParam string ) [] codersdk . ProvisionerDaemonStatus {
return ParseCustomList ( p , vals , def , queryParam , func ( v string ) ( codersdk . ProvisionerDaemonStatus , error ) {
return codersdk . ProvisionerDaemonStatus ( v ), nil
})
}
func ( p * QueryParamParser ) Duration ( vals url . Values , def time . Duration , queryParam string ) time . Duration {
v , err := parseQueryParam ( p , vals , func ( v string ) ( time . Duration , error ) {
d , err := time . ParseDuration ( v )
if err != nil {
return 0 , err
}
return d , nil
}, def , queryParam )
if err != nil {
p . Errors = append ( p . Errors , codersdk . ValidationError {
Field : queryParam ,
Detail : fmt . Sprintf ( "Query param %q must be a valid duration (e.g., '24h', '30m', '1h30m'): %s" , queryParam , err . Error ()),
})
}
return v
}
2023-09-04 19:39:14 +03:00
// ValidEnum represents an enum that can be parsed and validated.
2023-03-01 23:28:56 -06:00
type ValidEnum interface {
2023-09-04 19:39:14 +03:00
// Add more types as needed (avoid importing large dependency trees).
~ string
2023-03-01 23:28:56 -06:00
// Valid is required on the enum type to be used with ParseEnum.
Valid () bool
}
// ParseEnum is a function that can be passed into ParseCustom that handles enum
// validation.
func ParseEnum [ T ValidEnum ]( term string ) ( T , error ) {
enum := T ( term )
if enum . Valid () {
return enum , nil
}
var empty T
return empty , xerrors . Errorf ( "%q is not a valid value" , term )
2022-06-24 10:02:23 -05:00
}
// ParseCustom has to be a function, not a method on QueryParamParser because generics
// cannot be used on struct methods.
func ParseCustom [ T any ]( parser * QueryParamParser , vals url . Values , def T , queryParam string , parseFunc func ( v string ) ( T , error )) T {
2023-03-01 23:28:56 -06:00
v , err := parseQueryParam ( parser , vals , parseFunc , def , queryParam )
2022-06-14 08:46:33 -05:00
if err != nil {
2022-07-12 19:15:02 -05:00
parser . Errors = append ( parser . Errors , codersdk . ValidationError {
2022-06-14 08:46:33 -05:00
Field : queryParam ,
2022-06-24 19:55:28 -04:00
Detail : fmt . Sprintf ( "Query param %q has invalid value: %s" , queryParam , err . Error ()),
2022-06-14 08:46:33 -05:00
})
}
return v
}
2024-03-21 08:37:19 -05:00
// ParseCustomList is a function that handles csv query params or multiple values
// for a query param.
// Csv is supported as it is a common way to pass multiple values in a query param.
// Multiple values is supported (key=value&key=value2) for feature parity with GitHub issue search.
2023-03-01 23:28:56 -06:00
func ParseCustomList [ T any ]( parser * QueryParamParser , vals url . Values , def [] T , queryParam string , parseFunc func ( v string ) ( T , error )) [] T {
2024-03-21 08:37:19 -05:00
v , err := parseQueryParamSet ( parser , vals , func ( set [] string ) ([] T , error ) {
// Gather all terms.
allTerms := make ([] string , 0 , len ( set ))
for _ , s := range set {
// If a term is a csv, break it out into individual terms.
terms := strings . Split ( s , "," )
allTerms = append ( allTerms , terms ... )
}
2024-03-22 14:22:47 -05:00
var badErrors error
2023-03-01 23:28:56 -06:00
var output [] T
2024-03-21 08:37:19 -05:00
for _ , s := range allTerms {
2023-03-01 23:28:56 -06:00
good , err := parseFunc ( s )
if err != nil {
2024-03-22 14:22:47 -05:00
badErrors = errors . Join ( badErrors , err )
2023-03-01 23:28:56 -06:00
continue
}
output = append ( output , good )
}
2024-03-22 14:22:47 -05:00
if badErrors != nil {
return [] T {}, badErrors
2023-03-01 23:28:56 -06:00
}
return output , nil
}, def , queryParam )
if err != nil {
parser . Errors = append ( parser . Errors , codersdk . ValidationError {
Field : queryParam ,
Detail : fmt . Sprintf ( "Query param %q has invalid values: %s" , queryParam , err . Error ()),
})
}
return v
}
2024-07-03 08:42:23 -10:00
func parseNullableQueryParam [ T any ]( parser * QueryParamParser , vals url . Values , parse func ( v string ) ( T , error ), def sql . Null [ T ], queryParam string ) ( sql . Null [ T ], error ) {
setParse := parseSingle ( parser , parse , def . V , queryParam )
return parseQueryParamSet [ sql . Null [ T ]]( parser , vals , func ( set [] string ) ( sql . Null [ T ], error ) {
if len ( set ) == 0 {
return sql . Null [ T ]{
Valid : false ,
}, nil
}
value , err := setParse ( set )
if err != nil {
return sql . Null [ T ]{}, err
}
return sql . Null [ T ]{
V : value ,
Valid : true ,
}, nil
}, def , queryParam )
}
2024-03-21 08:37:19 -05:00
// parseQueryParam expects just 1 value set for the given query param.
2023-03-01 23:28:56 -06:00
func parseQueryParam [ T any ]( parser * QueryParamParser , vals url . Values , parse func ( v string ) ( T , error ), def T , queryParam string ) ( T , error ) {
2024-07-03 08:42:23 -10:00
setParse := parseSingle ( parser , parse , def , queryParam )
return parseQueryParamSet ( parser , vals , setParse , def , queryParam )
}
func parseSingle [ T any ]( parser * QueryParamParser , parse func ( v string ) ( T , error ), def T , queryParam string ) func ( set [] string ) ( T , error ) {
return func ( set [] string ) ( T , error ) {
2024-03-21 08:37:19 -05:00
if len ( set ) > 1 {
// Set as a parser.Error rather than return an error.
// Returned errors are errors from the passed in `parse` function, and
// imply the query param value had attempted to be parsed.
// By raising the error this way, we can also more easily control how it
// is presented to the user. A returned error is wrapped with more text.
parser . Errors = append ( parser . Errors , codersdk . ValidationError {
Field : queryParam ,
Detail : fmt . Sprintf ( "Query param %q provided more than once, found %d times. Only provide 1 instance of this query param." , queryParam , len ( set )),
})
return def , nil
}
return parse ( set [ 0 ])
}
}
func parseQueryParamSet [ T any ]( parser * QueryParamParser , vals url . Values , parse func ( set [] string ) ( T , error ), def T , queryParam string ) ( T , error ) {
2023-03-01 23:28:56 -06:00
parser . addParsed ( queryParam )
2023-04-03 20:59:59 -05:00
// If the query param is required and not present, return an error.
2024-02-20 15:58:43 -08:00
if parser . RequiredNotEmptyParams [ queryParam ] && (! vals . Has ( queryParam ) || vals . Get ( queryParam ) == "" ) {
2023-04-03 20:59:59 -05:00
parser . Errors = append ( parser . Errors , codersdk . ValidationError {
Field : queryParam ,
2024-02-20 15:58:43 -08:00
Detail : fmt . Sprintf ( "Query param %q is required and cannot be empty" , queryParam ),
2023-04-03 20:59:59 -05:00
})
return def , nil
}
// If the query param is not present, return the default value.
2022-06-14 08:46:33 -05:00
if ! vals . Has ( queryParam ) || vals . Get ( queryParam ) == "" {
return def , nil
}
2023-03-01 23:28:56 -06:00
2024-03-21 08:37:19 -05:00
return parse ( vals [ queryParam ])
2022-06-14 08:46:33 -05:00
}