github.com/google/go-safeweb@v0.0.0-20231219055052-64d8cfc90fbb/safehttp/interceptor.go (about)

     1  // Copyright 2020 Google LLC
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //	https://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  package safehttp
    16  
    17  // Interceptor alter the processing of incoming requests.
    18  //
    19  // See the documentation for ServeMux.ServeHTTP to understand how interceptors
    20  // are run, what happens in case of errors during request processing (i.e. which
    21  // interceptor methods are guaranteed to be run) etc.
    22  //
    23  // Interceptors keep their state across many requests and their methods can be
    24  // called concurrently. If you need per-request state, use FlightValues.
    25  type Interceptor interface {
    26  	// Before runs before the IncomingRequest is sent to the handler. If a
    27  	// response is written to the ResponseWriter, then the remaining
    28  	// interceptors and the handler won't execute. If Before panics, it will be
    29  	// recovered and the ServeMux will respond with 500 Internal Server Error.
    30  	Before(w ResponseWriter, r *IncomingRequest, cfg InterceptorConfig) Result
    31  
    32  	// Commit runs before the response is written by the Dispatcher. If an error
    33  	// is written to the ResponseWriter, then the Commit phases from the
    34  	// remaining interceptors won't execute.
    35  	Commit(w ResponseHeadersWriter, r *IncomingRequest, resp Response, cfg InterceptorConfig)
    36  
    37  	// Match checks whether the given config is meant to be applied to the Interceptor.
    38  	Match(InterceptorConfig) bool
    39  }
    40  
    41  // InterceptorConfig is a configuration for an interceptor.
    42  type InterceptorConfig interface{}
    43  
    44  // configuredInterceptor holds an interceptor together with its configuration.
    45  type configuredInterceptor struct {
    46  	interceptor Interceptor
    47  	config      InterceptorConfig
    48  }
    49  
    50  // Before runs before the IncomingRequest is sent to the handler. If a
    51  // response is written to the ResponseWriter, then the remaining
    52  // interceptors and the handler won't execute. If Before panics, it will be
    53  // recovered and the ServeMux will respond with 500 Internal Server Error.
    54  func (ci *configuredInterceptor) Before(w ResponseWriter, r *IncomingRequest) Result {
    55  	return ci.interceptor.Before(w, r, ci.config)
    56  }
    57  
    58  // Commit runs before the response is written by the Dispatcher. If an error
    59  // is written to the ResponseWriter, then the Commit phases from the
    60  // remaining interceptors won't execute.
    61  func (ci *configuredInterceptor) Commit(w ResponseHeadersWriter, r *IncomingRequest, resp Response) {
    62  	ci.interceptor.Commit(w, r, resp, ci.config)
    63  }