op.go

package openapi

import (
	"net/http"
	"reflect"
	"sync"

	kin "github.com/getkin/kin-openapi/openapi3"
)

// Parameter documents a query or path parameter.
type Parameter struct {
	in          string
	name        string
	description string
	required    bool
	typ         string
	dataType    any
}

// PathParameter returns a path parameter with the given name and description.
func PathParameter(name, description string) Parameter {
	return Parameter{
		in:          kin.ParameterInPath,
		name:        name,
		description: description,
		required:    true,
		dataType:    "",
	}
}

// QueryParameter returns a query parameter where the type will be resolved.
func QueryParameter(name, description string, typ any) Parameter {
	return Parameter{
		in:          kin.ParameterInQuery,
		name:        name,
		description: description,
		dataType:    typ,
	}
}

// QueryParameterWithType returns a query parameter with the given type.
func QueryParameterWithType(name, description, typ string) Parameter {
	return Parameter{
		in:          kin.ParameterInQuery,
		name:        name,
		description: description,
		typ:         typ,
	}
}

// HeaderParameter returns a header parameter with the given type.
func HeaderParameter(name, description string) Parameter {
	return Parameter{
		in:          kin.ParameterInHeader,
		name:        name,
		description: description,
	}
}

// Response documents a request response.
type Response struct {
	code        int
	description string
	writes      any
	headers     []string
	mediaTypes  []string
}

// ResponseOptFunc is an option function for configuration the response.
type ResponseOptFunc func(*Response)

// WithResponseHeader adds a header to the response.
func WithResponseHeader(name string) ResponseOptFunc {
	return func(resp *Response) {
		resp.headers = append(resp.headers, name)
	}
}

// WithMediaTypes sets the specific media types for this response.
func WithMediaTypes(mediaTypes ...string) ResponseOptFunc {
	return func(resp *Response) {
		resp.mediaTypes = mediaTypes
	}
}

const (
	secTypeBearer = "bearer"
	secTypeBasic  = "basic"
	secTypeAPIKey = "apiKey"
)

// Security represents a security configuration.
type Security struct {
	// Type is the security type, valid values are "bearer", "auth" and "apiKey".
	Type string

	// BearerFormat is a hint to the client to identify how the bearer token is formatted.
	// Bearer tokens are usually generated by an authorization server,
	// so this information is primarily for documentation purposes.
	BearerFormat string

	// APIKeyName contains the name of the header, query or cookie parameter to be used.
	APIKeyName string

	// APIKeyIn is required for type "apiKey", valid values are "query", "header" or "cookie".
	APIKeyIn string
}

// SecurityNone means no security is required for this endpoint.
var (
	SecurityNone   = Security{}
	SecurityBearer = Security{
		Type: secTypeBearer,

		// BearerFormat is a hint to the client to identify how the bearer token is formatted.
		// Bearer tokens are usually generated by an authorization server,
		// so this information is primarily for documentation purposes.
		BearerFormat: "",
	}
	SecurityBasic = Security{
		Type: secTypeBasic,
	}
)

// Operation documents a request.
type Operation struct {
	id       string
	tags     []string
	doc      string
	params   []Parameter
	consumes []string
	reads    any
	produces []string
	returns  []Response
	security map[string]Security
}

// Merge merges the operation with the given operation.
func (o Operation) Merge(newOp Operation) Operation {
	if newOp.id != "" {
		o.id = newOp.id
	}
	if newOp.doc != "" {
		o.doc = newOp.doc
	}
	if len(newOp.tags) > 0 {
		o.tags = append([]string{}, o.tags...)
		o.tags = append(o.tags, newOp.tags...)
	}
	if len(newOp.params) > 0 {
		o.params = append([]Parameter{}, o.params...)
		o.params = append(o.params, newOp.params...)
	}
	if len(newOp.consumes) > 0 {
		o.consumes = append([]string{}, o.consumes...)
		o.consumes = append(o.consumes, newOp.consumes...)
	}
	if newOp.reads != nil {
		o.reads = newOp.reads
	}
	if len(newOp.produces) > 0 {
		o.produces = append([]string{}, o.produces...)
		o.produces = append(o.produces, newOp.produces...)
	}
	if len(newOp.returns) > 0 {
		o.returns = append([]Response{}, o.returns...)
		o.returns = append(o.returns, newOp.returns...)
	}
	if len(newOp.security) != 0 {
		if o.security == nil {
			o.security = map[string]Security{}
		}
		for k, v := range newOp.security {
			o.security[k] = v
		}
	}
	return o
}

// OpBuilder builds an operation. An operation describes a request route.
type OpBuilder struct {
	op *Operation
}

// Op returns an op builder.
func Op() *OpBuilder {
	return &OpBuilder{op: &Operation{}}
}

// ID set the operation id.
func (o *OpBuilder) ID(id string) *OpBuilder {
	o.op.id = id
	return o
}

// Doc sets the operation summary.
func (o *OpBuilder) Doc(doc string) *OpBuilder {
	o.op.doc = doc
	return o
}

// Tag appends the given tag to the operation.
func (o *OpBuilder) Tag(tag string) *OpBuilder {
	o.op.tags = append(o.op.tags, tag)
	return o
}

// Param appends the given parameter to the operation.
func (o *OpBuilder) Param(param Parameter) *OpBuilder {
	o.op.params = append(o.op.params, param)
	return o
}

// Params appends the given parameters to the operation.
func (o *OpBuilder) Params(params ...Parameter) *OpBuilder {
	o.op.params = append(o.op.params, params...)
	return o
}

// Consumes appends the given consumable media types to the operation.
func (o *OpBuilder) Consumes(mediaTypes ...string) *OpBuilder {
	o.op.consumes = mediaTypes
	return o
}

// Reads sets the request body type on the operation.
func (o *OpBuilder) Reads(obj any) *OpBuilder {
	o.op.reads = obj
	return o
}

// Produces appends the given producible media types to the operation.
func (o *OpBuilder) Produces(mediaTypes ...string) *OpBuilder {
	o.op.produces = mediaTypes
	return o
}

// Returns appends the given response to the operation.
func (o *OpBuilder) Returns(code int, description string, obj any, opts ...ResponseOptFunc) *OpBuilder {
	resp := Response{
		code:        code,
		description: description,
		writes:      obj,
	}

	for _, opt := range opts {
		opt(&resp)
	}

	o.op.returns = append(o.op.returns, resp)
	return o
}

// RequiresAuth requires authentication for this endpoint.
//
// The supported authentication types are "bearer", "basic" and "apiKey".
// The same name requires the same Security object, as all security schemes are registered under its name. The behavior for not
// following this directive is undetermined.
func (o *OpBuilder) RequiresAuth(name string, sec Security) *OpBuilder {
	if o.op.security == nil {
		o.op.security = map[string]Security{}
	}
	o.op.security[name] = sec
	return o
}

// Build builds a middleware that will return an Operation when queried.
// In all other situations, the given handler is returned, effectively
// removing the middleware from the stack.
func (o *OpBuilder) Build() func(http.Handler) http.Handler {
	return func(next http.Handler) http.Handler {
		if _, ok := next.(opHandler); ok {
			return opHandler{Op: *o.op}
		}
		return next
	}
}

// BuildHandler builds a wrapper handler that contains an Operation.
//
// The operation is registered globally with the operation registrar
// as there is no other way to retrieve the operation from a handler func.
func (o *OpBuilder) BuildHandler() func(http.HandlerFunc) http.HandlerFunc {
	return func(next http.HandlerFunc) http.HandlerFunc {
		opReg.Register(next, *o.op)

		return next
	}
}

type opHandler struct {
	Op Operation
}

func (o opHandler) ServeHTTP(_ http.ResponseWriter, _ *http.Request) {}

var opReg = registrar{}

type registrar struct {
	mu  sync.Mutex
	ops map[reflect.Value]Operation
}

func (r *registrar) Register(i any, op Operation) {
	r.mu.Lock()
	defer r.mu.Unlock()

	if r.ops == nil {
		r.ops = map[reflect.Value]Operation{}
	}

	v := reflect.ValueOf(i)
	r.ops[v] = op
}

func (r *registrar) Op(i any) (Operation, bool) {
	r.mu.Lock()
	defer r.mu.Unlock()

	v := reflect.ValueOf(i)
	op, ok := r.ops[v]
	return op, ok
}