Пакет http
Обзор
Пакет http содержит реализации HTTP-клиента и HTTP-сервера.
Get, Head, Post и PostForm выполняют HTTP-запросы (или HTTPS-запросы):
resp, err := http.Get("http://example.com/")
...
resp, err := http.Post("http://example.com/upload", "image/jpeg", &buf)
...
resp, err := http.PostForm("http://example.com/form",
url.Values{"key": {"Value"}, "id": {"123"}})
По завершении работы вызывающий код должен закрыть тело ответа:
resp, err := http.Get("http://example.com/")
if err != nil {
// handle error
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
// ...
Клиенты и транспортные средства
Чтобы управлять заголовками HTTP-клиента, политикой перенаправления и другими настройками, создайте Client:
client := &http.Client{
CheckRedirect: redirectPolicyFunc,
}
resp, err := client.Get("http://example.com")
// ...
req, err := http.NewRequest("GET", "http://example.com", nil)
// ...
req.Header.Add("If-None-Match", `W/"wyzzy"`)
resp, err := client.Do(req)
// ...
Чтобы управлять прокси-серверами, настройками TLS, постоянными соединениями, сжатием и другими параметрами, создайте Transport:
tr := &http.Transport{
MaxIdleConns: 10,
IdleConnTimeout: 30 * time.Second,
DisableCompression: true,
}
client := &http.Client{Transport: tr}
resp, err := client.Get("https://example.com")
Клиенты и транспортные средства безопасны для одновременного использования несколькими горутинами. Для повышения эффективности их следует создавать один раз и использовать повторно.
Серверы
ListenAndServe запускает HTTP-сервер с заданным адресом и обработчиком. Обычно обработчик равен nil, что означает использование DefaultServeMux. Handle и HandleFunc добавляют обработчики в DefaultServeMux:
http.Handle("/foo", fooHandler)
http.HandleFunc("/bar", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "Hello, %q", html.EscapeString(r.URL.Path))
})
log.Fatal(http.ListenAndServe(":8080", nil))
Для более гибкого управления поведением сервера можно создать собственный Server:
s := &http.Server{
Addr: ":8080",
Handler: myHandler,
ReadTimeout: 10 * time.Second,
WriteTimeout: 10 * time.Second,
MaxHeaderBytes: 1 << 20,
}
log.Fatal(s.ListenAndServe())
HTTP/2
Пакет http обеспечивает прозрачную поддержку протокола HTTP/2.
Server и DefaultTransport автоматически включают поддержку HTTP/2 при использовании HTTPS. Transport по умолчанию не включает HTTP/2.
Сведения о включении и отключении поддержки HTTP/1, HTTP/2 и/или незашифрованного HTTP/2 см. в полях конфигурации Server.Protocols и Transport.Protocols.
Сведения о настройке расширенных функций HTTP/2 см. в полях конфигурации Server.HTTP2 и Transport.HTTP2.
Также в настоящее время поддерживаются следующие настройки GODEBUG:
GODEBUG=http2client=0 # disable HTTP/2 client support GODEBUG=http2server=0 # disable HTTP/2 server support GODEBUG=http2debug=1 # enable verbose HTTP/2 debug logs GODEBUG=http2debug=2 # ... even more verbose, with frame dumps
Тег сборки "omithttp2" можно использовать для отключения реализации HTTP/2, входящей в пакет http.
Указатель
Примеры
Файлы пакета
client.go clientconn.go clone.go cookie.go csrf.go doc.go filetransport.go fs.go header.go http.go http2.go jar.go mapping.go method.go pattern.go request.go response.go responsecontroller.go roundtrip.go routing_index.go routing_tree.go servemux121.go server.go sniff.go socks_bundle.go status.go transfer.go transport.go transport_default_other.go
Константы
Стандартные методы HTTP.
Если не указано иное, они определены в разделе 4.3 RFC 7231.
const (
MethodGet = "GET"
MethodHead = "HEAD"
MethodPost = "POST"
MethodPut = "PUT"
MethodPatch = "PATCH" // RFC 5789
MethodDelete = "DELETE"
MethodConnect = "CONNECT"
MethodOptions = "OPTIONS"
MethodTrace = "TRACE"
) Коды состояния HTTP, зарегистрированные в IANA. См. https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
const (
StatusContinue = 100 // RFC 9110, 15.2.1
StatusSwitchingProtocols = 101 // RFC 9110, 15.2.2
StatusProcessing = 102 // RFC 2518, 10.1
StatusEarlyHints = 103 // RFC 8297
StatusOK = 200 // RFC 9110, 15.3.1
StatusCreated = 201 // RFC 9110, 15.3.2
StatusAccepted = 202 // RFC 9110, 15.3.3
StatusNonAuthoritativeInfo = 203 // RFC 9110, 15.3.4
StatusNoContent = 204 // RFC 9110, 15.3.5
StatusResetContent = 205 // RFC 9110, 15.3.6
StatusPartialContent = 206 // RFC 9110, 15.3.7
StatusMultiStatus = 207 // RFC 4918, 11.1
StatusAlreadyReported = 208 // RFC 5842, 7.1
StatusIMUsed = 226 // RFC 3229, 10.4.1
StatusMultipleChoices = 300 // RFC 9110, 15.4.1
StatusMovedPermanently = 301 // RFC 9110, 15.4.2
StatusFound = 302 // RFC 9110, 15.4.3
StatusSeeOther = 303 // RFC 9110, 15.4.4
StatusNotModified = 304 // RFC 9110, 15.4.5
StatusUseProxy = 305 // RFC 9110, 15.4.6
StatusTemporaryRedirect = 307 // RFC 9110, 15.4.8
StatusPermanentRedirect = 308 // RFC 9110, 15.4.9
StatusBadRequest = 400 // RFC 9110, 15.5.1
StatusUnauthorized = 401 // RFC 9110, 15.5.2
StatusPaymentRequired = 402 // RFC 9110, 15.5.3
StatusForbidden = 403 // RFC 9110, 15.5.4
StatusNotFound = 404 // RFC 9110, 15.5.5
StatusMethodNotAllowed = 405 // RFC 9110, 15.5.6
StatusNotAcceptable = 406 // RFC 9110, 15.5.7
StatusProxyAuthRequired = 407 // RFC 9110, 15.5.8
StatusRequestTimeout = 408 // RFC 9110, 15.5.9
StatusConflict = 409 // RFC 9110, 15.5.10
StatusGone = 410 // RFC 9110, 15.5.11
StatusLengthRequired = 411 // RFC 9110, 15.5.12
StatusPreconditionFailed = 412 // RFC 9110, 15.5.13
StatusRequestEntityTooLarge = 413 // RFC 9110, 15.5.14
StatusRequestURITooLong = 414 // RFC 9110, 15.5.15
StatusUnsupportedMediaType = 415 // RFC 9110, 15.5.16
StatusRequestedRangeNotSatisfiable = 416 // RFC 9110, 15.5.17
StatusExpectationFailed = 417 // RFC 9110, 15.5.18
StatusTeapot = 418 // RFC 9110, 15.5.19 (Unused)
StatusMisdirectedRequest = 421 // RFC 9110, 15.5.20
StatusUnprocessableEntity = 422 // RFC 9110, 15.5.21
StatusLocked = 423 // RFC 4918, 11.3
StatusFailedDependency = 424 // RFC 4918, 11.4
StatusTooEarly = 425 // RFC 8470, 5.2.
StatusUpgradeRequired = 426 // RFC 9110, 15.5.22
StatusPreconditionRequired = 428 // RFC 6585, 3
StatusTooManyRequests = 429 // RFC 6585, 4
StatusRequestHeaderFieldsTooLarge = 431 // RFC 6585, 5
StatusUnavailableForLegalReasons = 451 // RFC 7725, 3
StatusInternalServerError = 500 // RFC 9110, 15.6.1
StatusNotImplemented = 501 // RFC 9110, 15.6.2
StatusBadGateway = 502 // RFC 9110, 15.6.3
StatusServiceUnavailable = 503 // RFC 9110, 15.6.4
StatusGatewayTimeout = 504 // RFC 9110, 15.6.5
StatusHTTPVersionNotSupported = 505 // RFC 9110, 15.6.6
StatusVariantAlsoNegotiates = 506 // RFC 2295, 8.1
StatusInsufficientStorage = 507 // RFC 4918, 11.5
StatusLoopDetected = 508 // RFC 5842, 7.2
StatusNotExtended = 510 // RFC 2774, 7
StatusNetworkAuthenticationRequired = 511 // RFC 6585, 6
) DefaultMaxHeaderBytes — максимально допустимый размер заголовков HTTP-запроса. Это значение можно изменить, задав Server.MaxHeaderBytes.
const DefaultMaxHeaderBytes = 1 << 20 // 1 MB
DefaultMaxHeaderValueCount — максимально допустимое количество значений заголовков в HTTP-запросе. Это значение можно изменить, задав Server.MaxHeaderValueCount.
const DefaultMaxHeaderValueCount = 500
DefaultMaxIdleConnsPerHost — значение по умолчанию для MaxIdleConnsPerHost у Transport.
const DefaultMaxIdleConnsPerHost = 2
TimeFormat — формат времени, используемый при формировании времени в HTTP-заголовках. Он похож на time.RFC1123, но часовой пояс GMT задан явно. Чтобы Format сформировал правильный формат, форматируемое время должно быть в UTC.
Сведения о разборе времени в этом формате см. в ParseTime.
const TimeFormat = "Mon, 02 Jan 2006 15:04:05 GMT"
TrailerPrefix — специальный префикс для ключей карты ResponseWriter.Header, который, если он присутствует, указывает, что запись карты предназначена для трейлеров ответа, а не для его заголовков. После завершения вызова ServeHTTP префикс удаляется, а значения отправляются в трейлерах.
Этот механизм предназначен только для трейлеров, которые неизвестны до отправки заголовков. Если набор трейлеров фиксирован или известен до отправки заголовка, предпочтительно использовать обычный механизм трейлеров Go:
https://pkg.go.dev/net/http#ResponseWriter https://pkg.go.dev/net/http#example-ResponseWriter-Trailers
const TrailerPrefix = "Trailer:"
Переменные
var (
// ErrNotSupported indicates that a feature is not supported.
//
// It is returned by ResponseController methods to indicate that
// the handler does not support the method, and by the Push method
// of Pusher implementations to indicate that HTTP/2 Push support
// is not available.
ErrNotSupported = &ProtocolError{"feature not supported"}
// Deprecated: ErrUnexpectedTrailer is no longer returned by
// anything in the net/http package. Callers should not
// compare errors against this variable.
ErrUnexpectedTrailer = &ProtocolError{"trailer header without chunked transfer encoding"}
// ErrMissingBoundary is returned by Request.MultipartReader when the
// request's Content-Type does not include a "boundary" parameter.
ErrMissingBoundary = &ProtocolError{"no multipart boundary param in Content-Type"}
// ErrNotMultipart is returned by Request.MultipartReader when the
// request's Content-Type is not multipart/form-data.
ErrNotMultipart = &ProtocolError{"request Content-Type isn't multipart/form-data"}
// Deprecated: ErrHeaderTooLong is no longer returned by
// anything in the net/http package. Callers should not
// compare errors against this variable.
ErrHeaderTooLong = &ProtocolError{"header too long"}
// Deprecated: ErrShortBody is no longer returned by
// anything in the net/http package. Callers should not
// compare errors against this variable.
ErrShortBody = &ProtocolError{"entity body too short"}
// Deprecated: ErrMissingContentLength is no longer returned by
// anything in the net/http package. Callers should not
// compare errors against this variable.
ErrMissingContentLength = &ProtocolError{"missing ContentLength in HEAD response"}
) Ошибки, используемые HTTP-сервером.
var (
// ErrBodyNotAllowed is returned by ResponseWriter.Write calls
// when the HTTP method or response code does not permit a
// body.
ErrBodyNotAllowed = internal.ErrBodyNotAllowed
// ErrHijacked is returned by ResponseWriter.Write calls when
// the underlying connection has been hijacked using the
// Hijacker interface. A zero-byte write on a hijacked
// connection will return ErrHijacked without any other side
// effects.
ErrHijacked = errors.New("http: connection has been hijacked")
// ErrContentLength is returned by ResponseWriter.Write calls
// when a Handler set a Content-Length response header with a
// declared size and then attempted to write more bytes than
// declared.
ErrContentLength = errors.New("http: wrote more than the declared Content-Length")
// Deprecated: ErrWriteAfterFlush is no longer returned by
// anything in the net/http package. Callers should not
// compare errors against this variable.
ErrWriteAfterFlush = errors.New("unused")
) var (
// ServerContextKey is a context key. It can be used in HTTP
// handlers with Context.Value to access the server that
// started the handler. The associated value will be of
// type *Server.
ServerContextKey = &contextKey{"http-server"}
// LocalAddrContextKey is a context key. It can be used in
// HTTP handlers with Context.Value to access the local
// address the connection arrived on.
// The associated value will be of type net.Addr.
LocalAddrContextKey = &contextKey{"local-addr"}
) DefaultClient — клиент Client по умолчанию, используемый функциями Get, Head и Post.
var DefaultClient = &Client{} DefaultServeMux — ServeMux по умолчанию, используемый функцией Serve.
var DefaultServeMux = &defaultServeMux
ErrAbortHandler — специальное значение паники для прерывания работы обработчика. Любая паника в ServeHTTP прерывает отправку ответа клиенту, но паника со значением ErrAbortHandler также подавляет запись трассировки стека в журнал ошибок сервера.
var ErrAbortHandler = internal.ErrAbortHandler
ErrBodyReadAfterClose возвращается при чтении Body у Request или Response после закрытия тела. Обычно это происходит, когда тело читается после того, как HTTP-обработчик Handler вызывает WriteHeader или Write у своего ResponseWriter.
var ErrBodyReadAfterClose = errors.New("http: invalid Read on closed Body") ErrHandlerTimeout возвращается при вызовах Write у ResponseWriter в обработчиках, время ожидания которых истекло.
var ErrHandlerTimeout = errors.New("http: Handler timeout") ErrLineTooLong возвращается при чтении тел запроса или ответа с некорректной передачей данных блоками.
var ErrLineTooLong = internal.ErrLineTooLong
ErrMissingFile возвращается методом FormFile, если указанное имя поля файла отсутствует в запросе или поле не является полем файла.
var ErrMissingFile = errors.New("http: no such file") ErrNoCookie возвращается методом Cookie у Request, если файл cookie не найден.
var ErrNoCookie = errors.New("http: named cookie not present") ErrNoLocation возвращается методом Response.Location, если заголовок Location отсутствует.
var ErrNoLocation = errors.New("http: no Location header in response") ErrSchemeMismatch возвращается, когда сервер отправляет ответ HTTP клиенту HTTPS.
var ErrSchemeMismatch = errors.New("http: server gave HTTP response to HTTPS client") ErrServerClosed возвращается методами Server.Serve, ServeTLS, ListenAndServe и ListenAndServeTLS после вызова Server.Shutdown или Server.Close.
var ErrServerClosed = errors.New("http: Server closed") ErrSkipAltProtocol — специальное значение ошибки, определённое методом Transport.RegisterProtocol.
var ErrSkipAltProtocol = internal.ErrSkipAltProtocol
ErrUseLastResponse может возвращаться хуками Client.CheckRedirect для управления обработкой перенаправлений. Если возвращена эта ошибка, следующий запрос не отправляется, а возвращается последний ответ с незакрытым телом.
var ErrUseLastResponse = errors.New("net/http: use last response") NoBody — это io.ReadCloser без байтов. Read всегда возвращает EOF, а Close всегда возвращает nil. Его можно использовать в исходящем клиентском запросе, чтобы явно указать, что запрос не содержит данных. Однако можно просто присвоить nil полю Request.Body.
var NoBody = noBody{} func CanonicalHeaderKey
func CanonicalHeaderKey(s string) string
CanonicalHeaderKey возвращает каноническую форму ключа заголовка s. При канонизации первая буква и буква после каждого дефиса переводятся в верхний регистр, а остальные — в нижний. Например, каноническая форма ключа "accept-encoding" — "Accept-Encoding". Если s содержит пробел или недопустимые байты поля заголовка, оно возвращается без изменений.
func DetectContentType
func DetectContentType(data []byte) string
DetectContentType реализует алгоритм, описанный на https://mimesniff.spec.whatwg.org/, для определения Content-Type заданных данных. Учитываются не более первых 512 байт данных. DetectContentType всегда возвращает допустимый MIME-тип: если определить более конкретный тип невозможно, возвращается "application/octet-stream".
func Error
func Error(w ResponseWriter, error string, code int)
Error отправляет ответ на запрос с указанным сообщением об ошибке и кодом HTTP. При этом обработка запроса не завершается; вызывающий код должен убедиться, что дальнейшая запись в w не выполняется. Сообщение об ошибке должно быть обычным текстом.
Error удаляет заголовок Content-Length, задаёт Content-Type равным “text/plain; charset=utf-8” и задаёт X-Content-Type-Options равным “nosniff”. Это позволяет правильно настроить заголовки для сообщения об ошибке, если вызывающий код настроил их для успешного ответа.
func Handle
func Handle(pattern string, handler Handler)
Handle регистрирует обработчик для заданного шаблона в DefaultServeMux. В документации к ServeMux объясняется сопоставление шаблонов.
Пример
Код:
package http_test
import (
"fmt"
"log"
"net/http"
"sync"
)
type countHandler struct {
mu sync.Mutex // guards n
n int
}
func (h *countHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
h.mu.Lock()
defer h.mu.Unlock()
h.n++
fmt.Fprintf(w, "count is %d\n", h.n)
}
func ExampleHandle() {
http.Handle("/count", new(countHandler))
log.Fatal(http.ListenAndServe(":8080", nil))
}
func HandleFunc
func HandleFunc(pattern string, handler func(ResponseWriter, *Request))
HandleFunc регистрирует функцию-обработчик для заданного шаблона в DefaultServeMux. В документации к ServeMux объясняется сопоставление шаблонов.
Пример
Код:
h1 := func(w http.ResponseWriter, _ *http.Request) {
io.WriteString(w, "Hello from a HandleFunc #1!\n")
}
h2 := func(w http.ResponseWriter, _ *http.Request) {
io.WriteString(w, "Hello from a HandleFunc #2!\n")
}
http.HandleFunc("/", h1)
http.HandleFunc("/endpoint", h2)
log.Fatal(http.ListenAndServe(":8080", nil))
func ListenAndServe
func ListenAndServe(addr string, handler Handler) error
ListenAndServe прослушивает TCP-адрес addr, а затем вызывает Serve с обработчиком handler для обработки запросов по входящим соединениям. Для принятых соединений включаются постоянные TCP-соединения.
Обычно обработчик равен nil; в этом случае используется DefaultServeMux.
ListenAndServe всегда возвращает ненулевую ошибку.
Пример
Код:
// Hello world, the web server
helloHandler := func(w http.ResponseWriter, req *http.Request) {
io.WriteString(w, "Hello, world!\n")
}
http.HandleFunc("/hello", helloHandler)
log.Fatal(http.ListenAndServe(":8080", nil))
func ListenAndServeTLS
func ListenAndServeTLS(addr, certFile, keyFile string, handler Handler) error
ListenAndServeTLS работает так же, как ListenAndServe, но ожидает HTTPS-соединения. Кроме того, необходимо предоставить файлы с сертификатом сервера и соответствующим закрытым ключом. Если сертификат подписан центром сертификации, файл certFile должен содержать последовательно сертификат сервера, все промежуточные сертификаты и сертификат центра сертификации.
Пример
Код:
http.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
io.WriteString(w, "Hello, TLS!\n")
})
// One can use generate_cert.go in crypto/tls to generate cert.pem and key.pem.
log.Printf("About to listen on 8443. Go to https://127.0.0.1:8443/")
err := http.ListenAndServeTLS(":8443", "cert.pem", "key.pem", nil)
log.Fatal(err)
func MaxBytesReader
func MaxBytesReader(w ResponseWriter, r io.ReadCloser, n int64) io.ReadCloser
MaxBytesReader похож на io.LimitReader, но предназначен для ограничения размера входящих тел запросов. В отличие от io.LimitReader, результат MaxBytesReader реализует ReadCloser, при чтении за пределами лимита возвращает ненулевую ошибку типа *MaxBytesError и закрывает нижележащий считыватель при вызове своего метода Close.
MaxBytesReader не позволяет клиентам случайно или намеренно отправлять большие запросы и расходовать ресурсы сервера. Если возможно, он сообщает ResponseWriter, что после достижения лимита следует закрыть соединение.
func NotFound
func NotFound(w ResponseWriter, r *Request)
NotFound отправляет ответ на запрос с ошибкой HTTP 404 «не найдено».
func ParseHTTPVersion
func ParseHTTPVersion(vers string) (major, minor int, ok bool)
ParseHTTPVersion разбирает строку версии HTTP согласно разделу 2.6 RFC 7230. Для "HTTP/1.0" возвращается (1, 0, true). Обратите внимание: строки без номера младшей версии, например "HTTP/2", недопустимы.
func ParseTime 1.1
func ParseTime(text string) (t time.Time, err error)
ParseTime разбирает заголовок времени (например, заголовок Date), проверяя каждый из трёх форматов, разрешённых HTTP/1.1: TimeFormat, time.RFC850 и time.ANSIC.
func ProxyFromEnvironment
func ProxyFromEnvironment(req *Request) (*url.URL, error)
ProxyFromEnvironment возвращает URL прокси для заданного запроса согласно переменным окружения HTTP_PROXY, HTTPS_PROXY и NO_PROXY (или их вариантам в нижнем регистре). Для запросов используется прокси из переменной окружения, соответствующей их схеме, если только прокси не исключён переменной NO_PROXY.
Значения переменных окружения могут быть полным URL или строкой "host[:port]"; во втором случае предполагается схема "http". Если значение имеет другой формат, возвращается ошибка.
Если прокси не задан в окружении или для данного запроса не следует использовать прокси согласно NO_PROXY, возвращаются nil URL и nil ошибка.
В особом случае, если req.URL.Host равен "localhost" (с номером порта или без него), возвращаются nil URL и nil ошибка.
func ProxyURL
func ProxyURL(fixedURL *url.URL) func(*Request) (*url.URL, error)
ProxyURL возвращает функцию прокси (для использования в Transport), которая всегда возвращает один и тот же URL.
func Redirect
func Redirect(w ResponseWriter, r *Request, url string, code int)
Redirect отправляет ответ на запрос с перенаправлением на url, который может быть путём относительно пути запроса. Все символы url, не входящие в ASCII, кодируются в процентах, но существующие процентные кодировки не изменяются.
Указанный код должен находиться в диапазоне 3xx; обычно это StatusMovedPermanently, StatusFound или StatusSeeOther.
Если заголовок Content-Type не задан, Redirect задаёт ему значение "text/html; charset=utf-8" и записывает небольшое HTML-тело. Установка заголовка Content-Type в любое значение, включая nil, отключает такое поведение.
func Serve
func Serve(l net.Listener, handler Handler) error
Serve принимает входящие HTTP-соединения через прослушиватель l, создавая для каждого из них новую служебную горутину. Служебные горутины читают запросы, а затем вызывают handler для отправки ответов.
Обычно обработчик равен nil; в этом случае используется DefaultServeMux.
Поддержка HTTP/2 включена только в том случае, если Listener возвращает соединения *tls.Conn или соединения, реализующие тот же метод ConnectionState, что и *tls.Conn, а состояние соединения указывает, что протокол "h2" был согласован с помощью ALPN.
Serve всегда возвращает ненулевую ошибку.
func ServeContent
func ServeContent(w ResponseWriter, req *Request, name string, modtime time.Time, content io.ReadSeeker)
ServeContent отправляет ответ на запрос, используя содержимое предоставленного ReadSeeker. Основное преимущество ServeContent перед io.Copy заключается в том, что он корректно обрабатывает запросы Range, устанавливает MIME-тип и обрабатывает запросы If-Match, If-Unmodified-Since, If-None-Match, If-Modified-Since и If-Range.
Если заголовок Content-Type ответа не задан, ServeContent сначала пытается определить тип по расширению файла в имени, а если это не удаётся — читает первый блок содержимого и передаёт его функции DetectContentType. В остальных случаях имя не используется; в частности, оно может быть пустым и никогда не передаётся в ответе.
Если modtime не равен нулевому времени или эпохе Unix, ServeContent включает его в заголовок Last-Modified ответа. Если запрос содержит заголовок If-Modified-Since, ServeContent использует modtime, чтобы определить, нужно ли вообще отправлять содержимое.
Метод Seek содержимого должен работать: ServeContent использует перемещение в конец содержимого, чтобы определить его размер. Обратите внимание, что *os.File реализует интерфейс io.ReadSeeker.
Если вызывающий код установил заголовок ETag для w в формате, указанном в разделе 2.3 RFC 7232, ServeContent использует его для обработки запросов с If-Match, If-None-Match или If-Range.
Если при обработке запроса возникает ошибка (например, при обработке некорректного запроса диапазона), ServeContent отправляет сообщение об ошибке. По умолчанию ServeContent удаляет заголовки Cache-Control, Content-Encoding, ETag и Last-Modified из ответов с ошибками. Настройка GODEBUG httpservecontentkeepheaders=1 заставляет ServeContent сохранять эти заголовки.
func ServeFile
func ServeFile(w ResponseWriter, r *Request, name string)
ServeFile отправляет в ответ на запрос содержимое указанного файла или каталога.
Если указанное имя файла или каталога — относительный путь, он интерпретируется относительно текущего каталога и может указывать на родительские каталоги. Если указанное имя сформировано из пользовательского ввода, перед вызовом ServeFile его следует санитизировать.
В качестве меры предосторожности ServeFile отклоняет запросы, в которых r.URL.Path содержит элемент пути ".."; это защищает от вызывающего кода, который может небезопасно применить filepath.Join к r.URL.Path без предварительной санитизации, а затем использовать результат filepath.Join в качестве аргумента name.
В качестве ещё одного особого случая ServeFile перенаправляет любой запрос, в котором r.URL.Path заканчивается на "/index.html", на тот же путь без завершающего "index.html". Чтобы избежать таких перенаправлений, измените путь или используйте ServeContent.
За исключением этих двух особых случаев, ServeFile не использует r.URL.Path для выбора файла или каталога, который нужно обслужить; используется только файл или каталог, указанный в аргументе name.
func ServeFileFS 1.22
func ServeFileFS(w ResponseWriter, r *Request, fsys fs.FS, name string)
ServeFileFS отправляет в ответ на запрос содержимое указанного файла или каталога из файловой системы fsys. Файлы, предоставляемые fsys, должны реализовывать io.Seeker.
Если указанное имя сформировано из пользовательского ввода, перед вызовом ServeFileFS его следует санитизировать.
В качестве меры предосторожности ServeFileFS отклоняет запросы, в которых r.URL.Path содержит элемент пути ".."; это защищает от вызывающего кода, который может небезопасно применить filepath.Join к r.URL.Path без предварительной санитизации, а затем использовать результат filepath.Join в качестве аргумента name.
В качестве ещё одного особого случая ServeFileFS перенаправляет любой запрос, в котором r.URL.Path заканчивается на "/index.html", на тот же путь без завершающего "index.html". Чтобы избежать таких перенаправлений, измените путь или используйте ServeContent.
За исключением этих двух особых случаев, ServeFileFS не использует r.URL.Path для выбора файла или каталога, который нужно обслужить; используется только файл или каталог, указанный в аргументе name.
func ServeTLS 1.9
func ServeTLS(l net.Listener, handler Handler, certFile, keyFile string) error
ServeTLS принимает входящие HTTPS-соединения на прослушивателе l, создавая для каждого из них новую служебную горутину. Служебные горутины читают запросы, а затем вызывают handler для отправки ответов на них.
Обычно handler равен nil; в этом случае используется DefaultServeMux.
Кроме того, необходимо предоставить файлы с сертификатом и соответствующим закрытым ключом сервера. Если сертификат подписан центром сертификации, certFile должен содержать последовательно сертификат сервера, все промежуточные сертификаты и сертификат центра сертификации.
ServeTLS всегда возвращает ненулевую ошибку.
func SetCookie
func SetCookie(w ResponseWriter, cookie *Cookie)
SetCookie добавляет заголовок Set-Cookie в заголовки предоставленного ResponseWriter. У предоставленной cookie должно быть допустимое имя. Недопустимые cookie могут быть молча отброшены.
func StatusText
func StatusText(code int) string
StatusText возвращает текст для кода состояния HTTP. Если код неизвестен, возвращается пустая строка.
type Client
Client — это HTTP-клиент. Его нулевое значение (DefaultClient) является готовым к использованию клиентом, применяющим DefaultTransport.
Client.Transport обычно имеет внутреннее состояние (кэшированные TCP-соединения), поэтому экземпляры Client следует повторно использовать, а не создавать по мере необходимости. Клиенты безопасны для одновременного использования несколькими горутинами.
Client работает на более высоком уровне, чем RoundTripper (например, Transport), и дополнительно обрабатывает такие детали HTTP, как cookie и перенаправления.
При переходе по перенаправлениям Client передаёт все заголовки, заданные в исходном Request, за исключением следующих случаев:
- при передаче конфиденциальных заголовков, таких как "Authorization", "WWW-Authenticate" и "Cookie", недоверенным адресатам. Эти заголовки не передаются при переходе по перенаправлению на домен, который не является поддоменом исходного домена и не совпадает с ним. Например, при перенаправлении с "foo.com" на "foo.com" или "sub.foo.com" конфиденциальные заголовки будут переданы, а при перенаправлении на "bar.com" — нет.
- при передаче заголовка "Cookie", если задано ненулевое хранилище cookie Jar. Поскольку каждое перенаправление может изменить состояние хранилища cookie, оно может изменить cookie, установленную в исходном запросе. При передаче заголовка "Cookie" все изменённые cookie исключаются; предполагается, что Jar добавит эти изменённые cookie с обновлёнными значениями (если источник совпадает). Если Jar равен nil, исходные cookie передаются без изменений.
type Client struct {
// Transport specifies the mechanism by which individual
// HTTP requests are made.
// If nil, DefaultTransport is used.
Transport RoundTripper
// CheckRedirect specifies the policy for handling redirects.
// If CheckRedirect is not nil, the client calls it before
// following an HTTP redirect. The arguments req and via are
// the upcoming request and the requests made already, oldest
// first. If CheckRedirect returns an error, the Client's Get
// method returns both the previous Response (with its Body
// closed) and CheckRedirect's error (wrapped in a url.Error)
// instead of issuing the Request req.
// As a special case, if CheckRedirect returns ErrUseLastResponse,
// then the most recent response is returned with its body
// unclosed, along with a nil error.
//
// If CheckRedirect is nil, the Client uses its default policy,
// which is to stop after 10 consecutive requests.
CheckRedirect func(req *Request, via []*Request) error
// Jar specifies the cookie jar.
//
// The Jar is used to insert relevant cookies into every
// outbound Request and is updated with the cookie values
// of every inbound Response. The Jar is consulted for every
// redirect that the Client follows.
//
// If Jar is nil, cookies are only sent if they are explicitly
// set on the Request.
Jar CookieJar
// Timeout specifies a time limit for requests made by this
// Client. The timeout includes connection time, any
// redirects, and reading the response body. The timer remains
// running after Get, Head, Post, or Do return and will
// interrupt reading of the Response.Body.
//
// A Timeout of zero means no timeout.
//
// The Client cancels requests to the underlying Transport
// as if the Request's Context ended.
//
// For compatibility, the Client will also use the deprecated
// CancelRequest method on Transport if found. New
// RoundTripper implementations should use the Request's Context
// for cancellation instead of implementing CancelRequest.
Timeout time.Duration // Go 1.3
}
func (*Client) CloseIdleConnections 1.12
func (c *Client) CloseIdleConnections()
CloseIdleConnections закрывает все соединения в его Transport, которые ранее использовались в запросах, но теперь находятся в состоянии ожидания "keep-alive". Активно используемые соединения не прерываются.
Если у Client.Transport нет метода Client.CloseIdleConnections, этот метод ничего не делает.
func (*Client) Do
func (c *Client) Do(req *Request) (*Response, error)
Do отправляет HTTP-запрос и возвращает HTTP-ответ, следуя настроенным для клиента правилам (например, обработки перенаправлений, cookie и аутентификации).
Ошибка возвращается, если она вызвана политикой клиента (например, CheckRedirect) или невозможностью обмениваться данными по HTTP (например, из-за проблем с сетевым подключением). Код состояния, отличный от 2xx, не вызывает ошибку.
Если возвращённая ошибка равна nil, Response будет содержать ненулевое поле Body, которое вызывающий код должен закрыть. Если Body не прочитан до EOF и не закрыт, базовый RoundTripper объекта Client (обычно Transport) может оказаться не в состоянии повторно использовать постоянное TCP-соединение с сервером для последующего запроса "keep-alive". Однако обратите внимание, что при закрытии Body Transport автоматически и асинхронно попытается прочитать Response Body до EOF в пределах консервативного лимита.
Body запроса, если он не равен nil, будет закрыт базовым Transport даже при возникновении ошибок. Body может быть закрыт асинхронно после возврата Do.
При ошибке любой Response можно игнорировать. Ненулевой Response вместе с ненулевой ошибкой возникает только в случае сбоя CheckRedirect; даже тогда возвращённый Response.Body уже закрыт.
Как правило, вместо Do используют Get, Post или PostForm.
Если сервер отвечает перенаправлением, Client сначала использует функцию CheckRedirect, чтобы определить, следует ли переходить по перенаправлению. Если переход разрешён, перенаправление 301, 302 или 303 приводит к тому, что в последующих запросах используется метод HTTP GET (или HEAD, если исходный запрос был HEAD), без тела. При перенаправлении 307 или 308 исходные метод HTTP и тело сохраняются, если определена функция Request.GetBody. Функция NewRequest автоматически задаёт GetBody для распространённых типов тела из стандартной библиотеки.
Обратите внимание, что поведение Client при перенаправлениях не соответствует стандарту WHATWG Fetch. Это связано с тем, что оно было реализовано до появления общепринятых стандартов. Поэтому по современным меркам поведение Client довольно либерально. Например, конфиденциальные заголовки сохраняются при перенаправлении на поддомен или на другой протокол того же хоста.
Любая возвращённая ошибка будет иметь тип *url.Error. Метод Timeout значения url.Error сообщит true, если время ожидания запроса истекло.
func (*Client) Get
func (c *Client) Get(url string) (resp *Response, err error)
Get отправляет запрос GET по указанному URL. Если ответ имеет один из следующих кодов перенаправления, Get переходит по перенаправлению после вызова функции Client.CheckRedirect:
301 (Moved Permanently) 302 (Found) 303 (See Other) 307 (Temporary Redirect) 308 (Permanent Redirect)
Ошибка возвращается, если функция Client.CheckRedirect завершается с ошибкой или возникает ошибка протокола HTTP. Ответ с кодом, отличным от 2xx, не вызывает ошибку. Любая возвращённая ошибка будет иметь тип *url.Error. Метод Timeout значения url.Error сообщит true, если время ожидания запроса истекло.
Если err равен nil, resp всегда содержит ненулевой resp.Body. По завершении чтения вызывающий код должен закрыть resp.Body.
Чтобы отправить запрос с пользовательскими заголовками, используйте NewRequest и Client.Do.
Чтобы отправить запрос с указанным context.Context, используйте NewRequestWithContext и Client.Do.
func (*Client) Head
func (c *Client) Head(url string) (resp *Response, err error)
Head отправляет запрос HEAD по указанному URL. Если ответ имеет один из следующих кодов перенаправления, Head переходит по перенаправлению после вызова функции Client.CheckRedirect:
301 (Moved Permanently) 302 (Found) 303 (See Other) 307 (Temporary Redirect) 308 (Permanent Redirect)
Чтобы отправить запрос с указанным context.Context, используйте NewRequestWithContext и Client.Do.
func (*Client) Post
func (c *Client) Post(url, contentType string, body io.Reader) (resp *Response, err error)
Post отправляет запрос POST по указанному URL.
По завершении чтения вызывающий код должен закрыть resp.Body.
Если предоставленное тело реализует io.Closer, оно закрывается после выполнения запроса.
Чтобы задать пользовательские заголовки, используйте NewRequest и Client.Do.
Чтобы отправить запрос с указанным context.Context, используйте NewRequestWithContext и Client.Do.
Подробные сведения об обработке перенаправлений см. в документации метода Client.Do.
func (*Client) PostForm
func (c *Client) PostForm(url string, data url.Values) (resp *Response, err error)
PostForm отправляет запрос POST по указанному URL, передавая ключи и значения data в теле запроса в формате URL-кодирования.
Заголовку Content-Type присваивается значение application/x-www-form-urlencoded. Чтобы задать другие заголовки, используйте NewRequest и Client.Do.
Если err равен nil, resp всегда содержит ненулевой resp.Body. По завершении чтения вызывающий код должен закрыть resp.Body.
Подробные сведения об обработке перенаправлений см. в документации метода Client.Do.
Чтобы отправить запрос с указанным context.Context, используйте NewRequestWithContext и Client.Do.
type ClientConn 1.26
ClientConn — это клиентское соединение с HTTP-сервером.
В отличие от Transport, ClientConn представляет одно соединение. Большинству пользователей следует использовать Transport, а не создавать клиентские соединения напрямую.
type ClientConn struct {
// contains filtered or unexported fields
}
func (*ClientConn) Available 1.26
func (cc *ClientConn) Available() int
Available сообщает количество запросов, которые можно отправить через соединение без блокировки. Если соединение закрыто, возвращается 0.
func (*ClientConn) Close 1.26
func (cc *ClientConn) Close() error
Close закрывает соединение. Выполняющиеся вызовы RoundTrip прерываются.
func (*ClientConn) Err 1.26
func (cc *ClientConn) Err() error
Err сообщает о любых критических ошибках соединения. Если соединение можно использовать, возвращается nil. Если возвращается ненулевое значение, соединение больше нельзя использовать.
func (*ClientConn) InFlight 1.26
func (cc *ClientConn) InFlight() int
InFlight сообщает количество выполняющихся запросов, включая зарезервированные запросы. Если соединение закрыто, возвращается 0.
func (*ClientConn) Release 1.26
func (cc *ClientConn) Release()
Release освобождает неиспользуемый слот параллелизма, зарезервированный методом Reserve. Если зарезервированных слотов параллелизма нет, метод ничего не делает.
func (*ClientConn) Reserve 1.26
func (cc *ClientConn) Reserve() error
Reserve резервирует слот параллелизма в соединении. Если Reserve возвращает nil, можно выполнить ещё один вызов RoundTrip, не дожидаясь завершения существующего запроса.
Зарезервированный слот параллелизма учитывается как выполняющийся запрос. Успешный вызов RoundTrip уменьшит значение Available и увеличит значение InFlight.
За каждым успешным вызовом Reserve должен следовать ровно один вызов RoundTrip или Release, который использует или освобождает резервирование.
Если соединение закрыто или достигнут предел параллелизма, Reserve возвращает ошибку.
func (*ClientConn) RoundTrip 1.26
func (cc *ClientConn) RoundTrip(req *Request) (*Response, error)
RoundTrip реализует интерфейс RoundTripper.
Запрос отправляется по клиентскому соединению независимо от запрашиваемого URL и любых настроек прокси.
Если соединение достигло предела параллелизма, RoundTrip ожидает, пока оно освободится, и только затем отправляет запрос.
func (*ClientConn) SetStateHook 1.26
func (cc *ClientConn) SetStateHook(f func(*ClientConn))
SetStateHook задаёт вызов f при изменении состояния соединения. Одновременно выполняется не более одного вызова f. Если состояние соединения изменилось после его создания, f немедленно вызывается в отдельной горутине. f может вызываться синхронно из RoundTrip или Response.Body.Close.
Если SetStateHook вызывается несколько раз, новый хук заменяет старый. Если f равен nil, после возврата SetStateHook дальнейшие вызовы f выполняться не будут.
f вызывается при увеличении Available (когда по соединению можно отправить больше запросов), уменьшении InFlight (когда завершаются существующие запросы) или при начале возврата ненулевого значения Err (когда соединение становится непригодным для использования).
type CloseNotifier 1.1
Интерфейс CloseNotifier реализуется объектами ResponseWriter, позволяющими обнаружить разрыв базового соединения.
Этот механизм можно использовать, чтобы отменять длительные операции на сервере, если клиент отключился до подготовки ответа.
Устарело: интерфейс CloseNotifier появился до пакета context в Go. В новом коде вместо него следует использовать Request.Context.
type CloseNotifier interface {
// CloseNotify returns a channel that receives at most a
// single value (true) when the client connection has gone
// away.
//
// CloseNotify may wait to notify until Request.Body has been
// fully read.
//
// After the Handler has returned, there is no guarantee
// that the channel receives a value.
//
// If the protocol is HTTP/1.1 and CloseNotify is called while
// processing an idempotent request (such as GET) while
// HTTP/1.1 pipelining is in use, the arrival of a subsequent
// pipelined request may cause a value to be sent on the
// returned channel. In practice HTTP/1.1 pipelining is not
// enabled in browsers and not seen often in the wild. If this
// is a problem, use HTTP/2 or only use CloseNotify on methods
// such as POST.
CloseNotify() <-chan bool
} type ConnState 1.3
ConnState представляет состояние клиентского соединения с сервером. Он используется необязательным хуком Server.ConnState.
type ConnState int
const (
// StateNew represents a new connection that is expected to
// send a request immediately. Connections begin at this
// state and then transition to either StateActive or
// StateClosed.
StateNew ConnState = iota
// StateActive represents a connection that has read 1 or more
// bytes of a request. The Server.ConnState hook for
// StateActive fires before the request has entered a handler
// and doesn't fire again until the request has been
// handled. After the request is handled, the state
// transitions to StateClosed, StateHijacked, or StateIdle.
// For HTTP/2, StateActive fires on the transition from zero
// to one active request, and only transitions away once all
// active requests are complete. That means that ConnState
// cannot be used to do per-request work; ConnState only notes
// the overall state of the connection.
StateActive
// StateIdle represents a connection that has finished
// handling a request and is in the keep-alive state, waiting
// for a new request. Connections transition from StateIdle
// to either StateActive or StateClosed.
StateIdle
// StateHijacked represents a hijacked connection.
// This is a terminal state. It does not transition to StateClosed.
StateHijacked
// StateClosed represents a closed connection.
// This is a terminal state. Hijacked connections do not
// transition to StateClosed.
StateClosed
) func (ConnState) String 1.3
func (c ConnState) String() string
type Cookie
Cookie представляет HTTP-cookie, передаваемую в заголовке Set-Cookie HTTP-ответа или в заголовке Cookie HTTP-запроса.
Подробные сведения см. на странице https://tools.ietf.org/html/rfc6265.
type Cookie struct {
Name string
Value string
Quoted bool // indicates whether the Value was originally quoted; added in Go 1.23
Path string // optional
Domain string // optional
Expires time.Time // optional
RawExpires string // for reading cookies only
// MaxAge=0 means no 'Max-Age' attribute specified.
// MaxAge<0 means delete cookie now, equivalently 'Max-Age: 0'
// MaxAge>0 means Max-Age attribute present and given in seconds
MaxAge int
Secure bool
HttpOnly bool
SameSite SameSite // Go 1.11
Partitioned bool // Go 1.23
Raw string
Unparsed []string // Raw text of unparsed attribute-value pairs
}
func ParseCookie 1.23
func ParseCookie(line string) ([]*Cookie, error)
ParseCookie разбирает значение заголовка Cookie и возвращает все содержащиеся в нём cookie. Поскольку имя одной и той же cookie может встречаться несколько раз, возвращённый Values может содержать несколько значений для одного ключа.
func ParseSetCookie 1.23
func ParseSetCookie(line string) (*Cookie, error)
ParseSetCookie разбирает значение заголовка Set-Cookie и возвращает cookie. При синтаксической ошибке возвращается ошибка.
func (*Cookie) String
func (c *Cookie) String() string
String возвращает сериализованное представление cookie для использования в заголовке Cookie (если заданы только Name и Value) или в заголовке Set-Cookie ответа (если заданы другие поля). Если c равен nil или c.Name недопустимо, возвращается пустая строка.
func (*Cookie) Valid 1.18
func (c *Cookie) Valid() error
Valid сообщает, допустима ли cookie.
type CookieJar
CookieJar управляет хранением и использованием cookie в HTTP-запросах.
Реализации CookieJar должны быть безопасны для одновременного использования несколькими горутинами.
Пакет net/http/cookiejar предоставляет реализацию CookieJar.
type CookieJar interface {
// SetCookies handles the receipt of the cookies in a reply for the
// given URL. It may or may not choose to save the cookies, depending
// on the jar's policy and implementation.
SetCookies(u *url.URL, cookies []*Cookie)
// Cookies returns the cookies to send in a request for the given URL.
// It is up to the implementation to honor the standard cookie use
// restrictions such as in RFC 6265.
Cookies(u *url.URL) []*Cookie
} type CrossOriginProtection 1.25
CrossOriginProtection обеспечивает защиту от межсайтовой подделки запроса (CSRF), отклоняя небезопасные междоменные запросы браузера.
В настоящее время междоменные запросы обнаруживаются с помощью заголовка Sec-Fetch-Site, доступного во всех браузерах с 2023 года, или путём сравнения имени хоста заголовка Origin со значением заголовка Host.
Методы GET, HEAD и OPTIONS считаются безопасными методами и всегда разрешены. Важно, чтобы приложения не выполняли никаких действий, изменяющих состояние, в ответ на запросы с безопасными методами.
В настоящее время запросы без заголовков Sec-Fetch-Site или Origin считаются либо запросами того же источника, либо запросами не из браузера и разрешаются.
Нулевое значение CrossOriginProtection допустимо и не содержит доверенных источников или шаблонов обхода защиты.
type CrossOriginProtection struct {
// contains filtered or unexported fields
}
Пример
Код:
mux := http.NewServeMux()
mux.HandleFunc("/hello", func(w http.ResponseWriter, req *http.Request) {
io.WriteString(w, "request allowed\n")
})
srv := http.Server{
Addr: ":8080",
ReadTimeout: 15 * time.Second,
WriteTimeout: 15 * time.Second,
// Use CrossOriginProtection.Handler to block all non-safe cross-origin
// browser requests to mux.
Handler: http.NewCrossOriginProtection().Handler(mux),
}
log.Fatal(srv.ListenAndServe())
func NewCrossOriginProtection 1.25
func NewCrossOriginProtection() *CrossOriginProtection
NewCrossOriginProtection возвращает новое значение CrossOriginProtection.
func (*CrossOriginProtection) AddInsecureBypassPattern 1.25
func (c *CrossOriginProtection) AddInsecureBypassPattern(pattern string)
AddInsecureBypassPattern разрешает все запросы, соответствующие заданному шаблону.
Синтаксис шаблонов и правила приоритета совпадают с правилами для ServeMux. Разрешаются только запросы, непосредственно соответствующие шаблону. Запросы, которые ServeMux перенаправил бы на шаблон (например, после очистки пути или добавления завершающего слеша), не разрешаются.
AddInsecureBypassPattern вызывает панику, если шаблон конфликтует с уже зарегистрированным или синтаксически недопустим (например, если шаблон с подстановочными знаками сформирован неправильно).
AddInsecureBypassPattern можно вызывать одновременно с другими методами или обработкой запросов; он применяется к будущим запросам.
func (*CrossOriginProtection) AddTrustedOrigin 1.25
func (c *CrossOriginProtection) AddTrustedOrigin(origin string) error
AddTrustedOrigin разрешает все запросы, заголовок Origin которых в точности совпадает с заданным значением.
Значения заголовка Origin имеют вид "scheme://host[:port]".
AddTrustedOrigin можно вызывать одновременно с другими методами или обработкой запросов; он применяется к будущим запросам.
func (*CrossOriginProtection) Check 1.25
func (c *CrossOriginProtection) Check(req *Request) error
Check выполняет для запроса проверки на принадлежность к другому источнику. Если запрос следует отклонить, возвращается ошибка.
func (*CrossOriginProtection) Handler 1.25
func (c *CrossOriginProtection) Handler(h Handler) Handler
Handler возвращает обработчик, который выполняет проверки на принадлежность к другому источнику перед вызовом обработчика h.
Если запрос не проходит эти проверки, он отклоняется со статусом 403 Forbidden или передаётся обработчику, заданному с помощью CrossOriginProtection.SetDenyHandler.
func (*CrossOriginProtection) SetDenyHandler 1.25
func (c *CrossOriginProtection) SetDenyHandler(h Handler)
SetDenyHandler задаёт обработчик, вызываемый при отклонении запроса. Обработчик ошибок по умолчанию отвечает статусом 403 Forbidden.
SetDenyHandler можно вызывать одновременно с другими методами или обработкой запросов; он применяется к будущим запросам.
Check не вызывает обработчик ошибок.
type Dir
Dir реализует FileSystem с помощью собственной файловой системы, ограниченной указанным деревом каталогов.
Метод FileSystem.Open принимает пути, разделённые символом '/', а строковое значение Dir — это путь к каталогу в собственной файловой системе, а не URL, поэтому он разделяется символом filepath.Separator, который не обязательно равен '/'.
Обратите внимание, что Dir может предоставлять доступ к конфиденциальным файлам и каталогам. Dir следует по символическим ссылкам, ведущим за пределы дерева каталогов; это особенно опасно, если сервер обслуживает каталог, в котором пользователи могут создавать произвольные символические ссылки. Dir также разрешает доступ к файлам и каталогам, имена которых начинаются с точки, что может открыть доступ к конфиденциальным каталогам, таким как .git, или файлам, таким как .htpasswd. Чтобы исключить файлы, имена которых начинаются с точки, удалите файлы/каталоги с сервера или создайте собственную реализацию FileSystem.
Пустое значение Dir трактуется как ".".
type Dir string
func (Dir) Open
func (d Dir) Open(name string) (File, error)
Open реализует FileSystem с помощью os.Open, открывая файлы для чтения в каталоге d и относительно него.
type File
File возвращается методом Open объекта FileSystem и может обслуживаться реализацией FileServer.
Методы должны вести себя так же, как методы у *os.File.
type File interface {
io.Closer
io.Reader
io.Seeker
Readdir(count int) ([]fs.FileInfo, error)
Stat() (fs.FileInfo, error)
} type FileSystem
FileSystem обеспечивает доступ к набору файлов с именами. Элементы пути к файлу разделяются символами косой черты ('/', U+002F) независимо от принятого в операционной системе формата. Чтобы преобразовать FileSystem в Handler, см. функцию FileServer.
Этот интерфейс появился до интерфейса fs.FS, который можно использовать вместо него: функция-адаптер FS преобразует fs.FS в FileSystem.
type FileSystem interface {
Open(name string) (File, error)
} func FS 1.16
func FS(fsys fs.FS) FileSystem
FS преобразует fsys в реализацию FileSystem для использования с FileServer и NewFileTransport. Файлы, предоставляемые fsys, должны реализовывать io.Seeker.
type Flusher
Интерфейс Flusher реализуется объектами ResponseWriter, позволяющими HTTP-обработчику отправлять буферизованные данные клиенту.
Стандартные реализации ResponseWriter для HTTP/1.x и HTTP/2 поддерживают Flusher, но обёртки ResponseWriter могут его не поддерживать. Обработчики всегда должны проверять эту возможность во время выполнения.
Обратите внимание, что даже для ResponseWriter с поддержкой Flush буферизованные данные могут не дойти до клиента до завершения ответа, если клиент подключён через HTTP-прокси.
type Flusher interface {
// Flush sends any buffered data to the client.
Flush()
} type HTTP2Config 1.24
HTTP2Config задаёт параметры конфигурации HTTP/2, общие для Transport и Server.
type HTTP2Config struct {
// MaxConcurrentStreams optionally specifies the number of
// concurrent streams that a client may have open at a time.
// If zero, MaxConcurrentStreams defaults to at least 100.
//
// This parameter only applies to Servers.
MaxConcurrentStreams int
// StrictMaxConcurrentRequests controls whether an HTTP/2 server's
// concurrency limit should be respected across all connections
// to that server.
// If true, new requests sent when a connection's concurrency limit
// has been exceeded will block until an existing request completes.
// If false, an additional connection will be opened if all
// existing connections are at their limit.
//
// This parameter only applies to Transports.
StrictMaxConcurrentRequests bool // Go 1.26
// MaxDecoderHeaderTableSize optionally specifies an upper limit for the
// size of the header compression table used for decoding headers sent
// by the peer.
// A valid value is less than 4MiB.
// If zero or invalid, a default value is used.
MaxDecoderHeaderTableSize int
// MaxEncoderHeaderTableSize optionally specifies an upper limit for the
// header compression table used for sending headers to the peer.
// A valid value is less than 4MiB.
// If zero or invalid, a default value is used.
MaxEncoderHeaderTableSize int
// MaxReadFrameSize optionally specifies the largest frame
// this endpoint is willing to read.
// A valid value is between 16KiB and 16MiB, inclusive.
// If zero or invalid, a default value is used.
MaxReadFrameSize int
// MaxReceiveBufferPerConnection is the maximum size of the
// flow control window for data received on a connection.
// A valid value is at least 64KiB and less than 4MiB.
// If invalid, a default value is used.
MaxReceiveBufferPerConnection int
// MaxReceiveBufferPerStream is the maximum size of
// the flow control window for data received on a stream (request).
// A valid value is less than 4MiB.
// If zero or invalid, a default value is used.
MaxReceiveBufferPerStream int
// SendPingTimeout is the timeout after which a health check using a ping
// frame will be carried out if no frame is received on a connection.
// If zero, no health check is performed.
SendPingTimeout time.Duration
// PingTimeout is the timeout after which a connection will be closed
// if a response to a ping is not received.
// If zero, a default of 15 seconds is used.
PingTimeout time.Duration
// WriteByteTimeout is the timeout after which a connection will be
// closed if no data can be written to it. The timeout begins when data is
// available to write, and is extended whenever any bytes are written.
WriteByteTimeout time.Duration
// PermitProhibitedCipherSuites, if true, permits the use of
// cipher suites prohibited by the HTTP/2 spec.
PermitProhibitedCipherSuites bool
// CountError, if non-nil, is called on HTTP/2 errors.
// It is intended to increment a metric for monitoring.
// The errType contains only lowercase letters, digits, and underscores
// (a-z, 0-9, _).
CountError func(errType string)
}
type Handler
Handler обрабатывает HTTP-запрос.
Handler.ServeHTTP должен записать заголовки ответа и данные в ResponseWriter, а затем вернуться. Возврат означает завершение запроса; использовать ResponseWriter или читать Request.Body после завершения вызова ServeHTTP или одновременно с ним нельзя.
В зависимости от программного обеспечения HTTP-клиента, версии протокола HTTP и любых посредников между клиентом и сервером Go может оказаться невозможным читать Request.Body после записи в ResponseWriter. Предусмотрительные обработчики должны сначала прочитать Request.Body, а затем отправить ответ.
За исключением чтения тела, обработчики не должны изменять предоставленный Request.
Если ServeHTTP вызывает панику, сервер (вызывающий ServeHTTP) предполагает, что её действие ограничено текущим запросом. Он перехватывает панику, записывает трассировку стека в журнал ошибок сервера и либо закрывает сетевое соединение, либо отправляет HTTP/2 RST_STREAM — в зависимости от протокола HTTP. Чтобы прервать обработчик так, чтобы клиент получил прерванный ответ, но сервер не записал ошибку в журнал, вызовите панику со значением ErrAbortHandler.
type Handler interface {
ServeHTTP(ResponseWriter, *Request)
} func AllowQuerySemicolons 1.17
func AllowQuerySemicolons(h Handler) Handler
AllowQuerySemicolons возвращает обработчик, который обслуживает запросы, заменяя все неэкранированные точки с запятой в URL-запросе на амперсанды и вызывая обработчик h.
Это восстанавливает поведение до Go 1.17, при котором параметры запроса разделялись как точками с запятой, так и амперсандами. (См. golang.org/issue/25192). Обратите внимание, что такое поведение отличается от поведения многих прокси, и это несоответствие может привести к проблемам безопасности.
AllowQuerySemicolons следует вызывать до вызова Request.ParseForm.
func FileServer
func FileServer(root FileSystem) Handler
FileServer возвращает обработчик, который обслуживает HTTP-запросы содержимым файловой системы, корнем которой является root.
В особом случае возвращённый файловый сервер перенаправляет любой запрос, заканчивающийся на "/index.html", на тот же путь без завершающего "index.html".
Чтобы использовать реализацию файловой системы операционной системы, используйте http.Dir:
http.Handle("/", http.FileServer(http.Dir("/tmp")))
Чтобы использовать реализацию fs.FS, воспользуйтесь вместо этого http.FileServerFS.
Пример
Код:
// Simple static webserver:
log.Fatal(http.ListenAndServe(":8080", http.FileServer(http.Dir("/usr/share/doc"))))
Пример (скрытие файлов, имена которых начинаются с точки)
Код:
package http_test
import (
"io"
"io/fs"
"log"
"net/http"
"strings"
)
// containsDotFile reports whether name contains a path element starting with a period.
// The name is assumed to be a delimited by forward slashes, as guaranteed
// by the http.FileSystem interface.
func containsDotFile(name string) bool {
parts := strings.Split(name, "/")
for _, part := range parts {
if strings.HasPrefix(part, ".") {
return true
}
}
return false
}
// dotFileHidingFile is the http.File use in dotFileHidingFileSystem.
// It is used to wrap the Readdir method of http.File so that we can
// remove files and directories that start with a period from its output.
type dotFileHidingFile struct {
http.File
}
// Readdir is a wrapper around the Readdir method of the embedded File
// that filters out all files that start with a period in their name.
func (f dotFileHidingFile) Readdir(n int) (fis []fs.FileInfo, err error) {
files, err := f.File.Readdir(n)
for _, file := range files { // Filters out the dot files
if !strings.HasPrefix(file.Name(), ".") {
fis = append(fis, file)
}
}
if err == nil && n > 0 && len(fis) == 0 {
err = io.EOF
}
return
}
// dotFileHidingFileSystem is an http.FileSystem that hides
// hidden "dot files" from being served.
type dotFileHidingFileSystem struct {
http.FileSystem
}
// Open is a wrapper around the Open method of the embedded FileSystem
// that serves a 403 permission error when name has a file or directory
// with whose name starts with a period in its path.
func (fsys dotFileHidingFileSystem) Open(name string) (http.File, error) {
if containsDotFile(name) { // If dot file, return 403 response
return nil, fs.ErrPermission
}
file, err := fsys.FileSystem.Open(name)
if err != nil {
return nil, err
}
return dotFileHidingFile{file}, nil
}
func ExampleFileServer_dotFileHiding() {
fsys := dotFileHidingFileSystem{http.Dir(".")}
http.Handle("/", http.FileServer(fsys))
log.Fatal(http.ListenAndServe(":8080", nil))
}
Пример (StripPrefix)
Код:
// To serve a directory on disk (/tmp) under an alternate URL
// path (/tmpfiles/), use StripPrefix to modify the request
// URL's path before the FileServer sees it:
http.Handle("/tmpfiles/", http.StripPrefix("/tmpfiles/", http.FileServer(http.Dir("/tmp"))))
func FileServerFS 1.22
func FileServerFS(root fs.FS) Handler
FileServerFS возвращает обработчик, который обслуживает HTTP-запросы содержимым файловой системы fsys. Файлы, предоставляемые fsys, должны реализовывать io.Seeker.
В особом случае возвращённый файловый сервер перенаправляет любой запрос, заканчивающийся на "/index.html", на тот же путь без завершающего "index.html".
http.Handle("/", http.FileServerFS(fsys))
func MaxBytesHandler 1.18
func MaxBytesHandler(h Handler, n int64) Handler
MaxBytesHandler возвращает Handler, который запускает h с обёрнутыми в MaxBytesReader объектами ResponseWriter и Request.Body.
func NotFoundHandler
func NotFoundHandler() Handler
NotFoundHandler возвращает простой обработчик запросов, который отвечает на каждый запрос сообщением «404 page not found».
Пример
Код:
mux := http.NewServeMux()
// Create sample handler to returns 404
mux.Handle("/resources", http.NotFoundHandler())
// Create sample handler that returns 200
mux.Handle("/resources/people/", newPeopleHandler())
log.Fatal(http.ListenAndServe(":8080", mux))
func RedirectHandler
func RedirectHandler(url string, code int) Handler
RedirectHandler возвращает обработчик запросов, перенаправляющий каждый полученный запрос на указанный URL с заданным кодом состояния.
Указанный код должен находиться в диапазоне 3xx; обычно это StatusMovedPermanently, StatusFound или StatusSeeOther.
func StripPrefix
func StripPrefix(prefix string, h Handler) Handler
StripPrefix возвращает обработчик, который обслуживает HTTP-запросы, удаляя заданный префикс из поля Path URL запроса (а также из RawPath, если он задан) и вызывая обработчик h. Если путь запроса не начинается с префикса, StripPrefix отвечает ошибкой HTTP 404 «не найдено». Префикс должен совпадать точно: если префикс в запросе содержит экранированные символы, ответом также будет ошибка HTTP 404 «не найдено».
Пример
Код:
// To serve a directory on disk (/tmp) under an alternate URL
// path (/tmpfiles/), use StripPrefix to modify the request
// URL's path before the FileServer sees it:
http.Handle("/tmpfiles/", http.StripPrefix("/tmpfiles/", http.FileServer(http.Dir("/tmp"))))
func TimeoutHandler
func TimeoutHandler(h Handler, dt time.Duration, msg string) Handler
TimeoutHandler возвращает Handler, который запускает h с заданным ограничением по времени.
Новый Handler вызывает h.ServeHTTP для обработки каждого запроса, но если вызов длится дольше установленного ограничения, обработчик отвечает ошибкой 503 Service Unavailable и помещает в тело ответа указанное сообщение. (Если msg пусто, будет отправлено подходящее сообщение по умолчанию.) После такого тайм-аута запись в ResponseWriter из h будет возвращать ErrHandlerTimeout.
TimeoutHandler поддерживает интерфейс Pusher, но не поддерживает интерфейсы Hijacker или Flusher.
type HandlerFunc
Тип HandlerFunc служит адаптером, позволяющим использовать обычные функции в качестве HTTP-обработчиков. Если f — функция с подходящей сигнатурой, то HandlerFunc(f) — это Handler, вызывающий f.
type HandlerFunc func(ResponseWriter, *Request)
func (HandlerFunc) ServeHTTP
func (f HandlerFunc) ServeHTTP(w ResponseWriter, r *Request)
ServeHTTP вызывает f(w, r).
type Header
Header представляет пары ключ-значение в HTTP-заголовке.
Ключи должны быть в канонической форме, возвращаемой функцией CanonicalHeaderKey.
type Header map[string][]string
func (Header) Add
func (h Header) Add(key, value string)
Add добавляет в заголовок пару ключ-значение. Она дополняет все уже существующие значения, связанные с ключом. Регистр ключа не учитывается; ключ приводится к канонической форме с помощью CanonicalHeaderKey.
func (Header) Clone 1.13
func (h Header) Clone() Header
Clone возвращает копию h или nil, если h равен nil.
func (Header) Del
func (h Header) Del(key string)
Del удаляет значения, связанные с ключом. Регистр ключа не учитывается; ключ приводится к канонической форме с помощью CanonicalHeaderKey.
func (Header) Get
func (h Header) Get(key string) string
Get возвращает первое значение, связанное с указанным ключом. Если с ключом не связано ни одного значения, Get возвращает "". Регистр ключа не учитывается; для приведения указанного ключа к канонической форме используется textproto.CanonicalMIMEHeaderKey. Get предполагает, что все ключи хранятся в канонической форме. Чтобы использовать неканонические ключи, обращайтесь напрямую к карте.
func (Header) Set
func (h Header) Set(key, value string)
Set задаёт для записей заголовка, связанных с ключом, единственное значение. Функция заменяет все существующие значения, связанные с ключом. Регистр ключа не учитывается; ключ приводится к канонической форме с помощью textproto.CanonicalMIMEHeaderKey. Чтобы использовать неканонические ключи, присваивайте значения непосредственно в карте.
func (Header) Values 1.14
func (h Header) Values(key string) []string
Values возвращает все значения, связанные с указанным ключом. Регистр ключа не учитывается; для приведения указанного ключа к канонической форме используется textproto.CanonicalMIMEHeaderKey. Чтобы использовать неканонические ключи, обращайтесь напрямую к карте. Возвращённый срез не является копией.
func (Header) Write
func (h Header) Write(w io.Writer) error
Write записывает заголовок в формате передачи.
func (Header) WriteSubset
func (h Header) WriteSubset(w io.Writer, exclude map[string]bool) error
WriteSubset записывает заголовок в формате передачи. Если exclude не равен nil, ключи, для которых exclude[key] == true, не записываются. Перед проверкой карты exclude ключи не приводятся к канонической форме.
type Hijacker
Интерфейс Hijacker реализуется объектами ResponseWriter, которые позволяют HTTP-обработчику перехватить соединение.
Стандартный ResponseWriter для соединений HTTP/1.x поддерживает Hijacker, а соединения HTTP/2 намеренно его не поддерживают. Обёртки ResponseWriter также могут не поддерживать Hijacker. Обработчики всегда должны проверять эту возможность во время выполнения.
type Hijacker interface {
// Hijack lets the caller take over the connection.
// After a call to Hijack the HTTP server library
// will not do anything else with the connection.
//
// It becomes the caller's responsibility to manage
// and close the connection.
//
// The returned net.Conn may have read or write deadlines
// already set, depending on the configuration of the
// Server. It is the caller's responsibility to set
// or clear those deadlines as needed.
//
// The returned bufio.Reader may contain unprocessed buffered
// data from the client.
//
// After a call to Hijack, the original Request.Body must not
// be used. The original Request's Context remains valid and
// is not canceled until the Request's ServeHTTP method
// returns.
Hijack() (net.Conn, *bufio.ReadWriter, error)
} Пример
Код:
http.HandleFunc("/hijack", func(w http.ResponseWriter, r *http.Request) {
hj, ok := w.(http.Hijacker)
if !ok {
http.Error(w, "webserver doesn't support hijacking", http.StatusInternalServerError)
return
}
conn, bufrw, err := hj.Hijack()
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
// Don't forget to close the connection:
defer conn.Close()
bufrw.WriteString("Now we're speaking raw TCP. Say hi: ")
bufrw.Flush()
s, err := bufrw.ReadString('\n')
if err != nil {
log.Printf("error reading string: %v", err)
return
}
fmt.Fprintf(bufrw, "You said: %q\nBye.\n", s)
bufrw.Flush()
})
type MaxBytesError 1.19
MaxBytesError возвращается функцией MaxBytesReader, когда превышен лимит чтения.
type MaxBytesError struct {
Limit int64
}
func (*MaxBytesError) Error 1.19
func (e *MaxBytesError) Error() string
type ProtocolError
ProtocolError представляет ошибку протокола HTTP.
Устарело: не все ошибки в пакете http, связанные с ошибками протокола, имеют тип ProtocolError.
type ProtocolError struct {
ErrorString string
}
func (*ProtocolError) Error
func (pe *ProtocolError) Error() string
func (*ProtocolError) Is 1.21
func (pe *ProtocolError) Is(err error) bool
Is позволяет http.ErrNotSupported соответствовать errors.ErrUnsupported.
type Protocols 1.24
Protocols — это набор протоколов HTTP. Нулевое значение представляет пустой набор протоколов.
Поддерживаются следующие протоколы:
HTTP1 — протоколы HTTP/1.0 и HTTP/1.1. HTTP1 поддерживается как для незащищённых TCP-соединений, так и для защищённых TLS-соединений.
HTTP2 — протокол HTTP/2 поверх TLS-соединения.
UnencryptedHTTP2 — протокол HTTP/2 поверх незащищённого TCP-соединения.
type Protocols struct {
// contains filtered or unexported fields
}
Пример (Http1)
Код:
srv := http.Server{
Addr: ":8443",
}
// Serve only HTTP/1.
srv.Protocols = new(http.Protocols)
srv.Protocols.SetHTTP1(true)
log.Fatal(srv.ListenAndServeTLS("cert.pem", "key.pem"))
Пример (Http1or2)
Код:
t := http.DefaultTransport.(*http.Transport).Clone()
// Use either HTTP/1 and HTTP/2.
t.Protocols = new(http.Protocols)
t.Protocols.SetHTTP1(true)
t.Protocols.SetHTTP2(true)
cli := &http.Client{Transport: t}
res, err := cli.Get("http://www.google.com/robots.txt")
if err != nil {
log.Fatal(err)
}
res.Body.Close()
func (Protocols) HTTP1 1.24
func (p Protocols) HTTP1() bool
HTTP1 сообщает, содержит ли p HTTP/1.
func (Protocols) HTTP2 1.24
func (p Protocols) HTTP2() bool
HTTP2 сообщает, содержит ли p HTTP/2.
func (*Protocols) SetHTTP1 1.24
func (p *Protocols) SetHTTP1(ok bool)
SetHTTP1 добавляет HTTP/1 в p или удаляет его из p.
func (*Protocols) SetHTTP2 1.24
func (p *Protocols) SetHTTP2(ok bool)
SetHTTP2 добавляет HTTP/2 в p или удаляет его из p.
func (*Protocols) SetUnencryptedHTTP2 1.24
func (p *Protocols) SetUnencryptedHTTP2(ok bool)
SetUnencryptedHTTP2 добавляет нешифрованный HTTP/2 в p или удаляет его из p.
func (Protocols) String 1.24
func (p Protocols) String() string
func (Protocols) UnencryptedHTTP2 1.24
func (p Protocols) UnencryptedHTTP2() bool
UnencryptedHTTP2 сообщает, содержит ли p нешифрованный HTTP/2.
type PushOptions 1.8
PushOptions описывает параметры для Pusher.Push.
type PushOptions struct {
// Method specifies the HTTP method for the promised request.
// If set, it must be "GET" or "HEAD". Empty means "GET".
Method string
// Header specifies additional promised request headers. This cannot
// include HTTP/2 pseudo header fields like ":path" and ":scheme",
// which will be added automatically.
Header Header
}
type Pusher 1.8
Pusher — это интерфейс, реализуемый объектами ResponseWriter, поддерживающими серверную отправку данных HTTP/2. Дополнительные сведения см. в разделе https://tools.ietf.org/html/rfc7540#section-8.2.
type Pusher interface {
// Push initiates an HTTP/2 server push. This constructs a synthetic
// request using the given target and options, serializes that request
// into a PUSH_PROMISE frame, then dispatches that request using the
// server's request handler. If opts is nil, default options are used.
//
// The target must either be an absolute path (like "/path") or an absolute
// URL that contains a valid host and the same scheme as the parent request.
// If the target is a path, it will inherit the scheme and host of the
// parent request.
//
// The HTTP/2 spec disallows recursive pushes and cross-authority pushes.
// Push may or may not detect these invalid pushes; however, invalid
// pushes will be detected and canceled by conforming clients.
//
// Handlers that wish to push URL X should call Push before sending any
// data that may trigger a request for URL X. This avoids a race where the
// client issues requests for X before receiving the PUSH_PROMISE for X.
//
// Push will run in a separate goroutine making the order of arrival
// non-deterministic. Any required synchronization needs to be implemented
// by the caller.
//
// Push returns ErrNotSupported if the client has disabled push or if push
// is not supported on the underlying connection.
Push(target string, opts *PushOptions) error
} type Request
Request представляет HTTP-запрос, полученный сервером или предназначенный для отправки клиентом.
Семантика полей немного различается для клиентского и серверного использования. Помимо примечаний к полям ниже, см. документацию к Request.Write и RoundTripper.
type Request struct {
// Method specifies the HTTP method (GET, POST, PUT, etc.).
// For client requests, an empty string means GET.
Method string
// URL specifies either the URI being requested (for server
// requests) or the URL to access (for client requests).
//
// For server requests, the URL is parsed from the URI
// supplied on the Request-Line as stored in RequestURI. For
// most requests, fields other than Path and RawQuery will be
// empty. (See RFC 7230, Section 5.3)
//
// For client requests, the URL's Host specifies the server to
// connect to, while the Request's Host field optionally
// specifies the Host header value to send in the HTTP
// request.
URL *url.URL
// The protocol version for incoming server requests.
//
// For client requests, these fields are ignored. The HTTP
// client code always uses either HTTP/1.1 or HTTP/2.
// See the docs on Transport for details.
Proto string // "HTTP/1.0"
ProtoMajor int // 1
ProtoMinor int // 0
// Header contains the request header fields either received
// by the server or to be sent by the client.
//
// If a server received a request with header lines,
//
// Host: example.com
// accept-encoding: gzip, deflate
// Accept-Language: en-us
// fOO: Bar
// foo: two
//
// then
//
// Header = map[string][]string{
// "Accept-Encoding": {"gzip, deflate"},
// "Accept-Language": {"en-us"},
// "Foo": {"Bar", "two"},
// }
//
// For incoming requests, the Host header is promoted to the
// Request.Host field and removed from the Header map.
//
// HTTP defines that header names are case-insensitive. The
// request parser implements this by using CanonicalHeaderKey,
// making the first character and any characters following a
// hyphen uppercase and the rest lowercase.
//
// For client requests, certain headers such as Content-Length
// and Connection are automatically written when needed and
// values in Header may be ignored. See the documentation
// for the Request.Write method.
Header Header
// Body is the request's body.
//
// For client requests, a nil body means the request has no
// body, such as a GET request. The HTTP Client's Transport
// is responsible for calling the Close method.
//
// For server requests, the Request Body is always non-nil
// but will return EOF immediately when no body is present.
// The Server will close the request body. The ServeHTTP
// Handler does not need to.
//
// Body must allow Read to be called concurrently with Close.
// In particular, calling Close should unblock a Read waiting
// for input.
Body io.ReadCloser
// GetBody defines an optional func to return a new copy of
// Body. It is used for client requests when a redirect requires
// reading the body more than once. Use of GetBody still
// requires setting Body.
//
// For server requests, it is unused.
GetBody func() (io.ReadCloser, error) // Go 1.8
// ContentLength records the length of the associated content.
// The value -1 indicates that the length is unknown.
// Values >= 0 indicate that the given number of bytes may
// be read from Body.
//
// For client requests, a value of 0 with a non-nil Body is
// also treated as unknown.
ContentLength int64
// TransferEncoding lists the transfer encodings from outermost to
// innermost. An empty list denotes the "identity" encoding.
// TransferEncoding can usually be ignored; chunked encoding is
// automatically added and removed as necessary when sending and
// receiving requests.
TransferEncoding []string
// Close indicates whether to close the connection after
// replying to this request (for servers) or after sending this
// request and reading its response (for clients).
//
// For server requests, the HTTP server handles this automatically
// and this field is not needed by Handlers.
//
// For client requests, setting this field prevents re-use of
// TCP connections between requests to the same hosts, as if
// Transport.DisableKeepAlives were set.
Close bool
// For server requests, Host specifies the host on which the
// URL is sought. For HTTP/1 (per RFC 7230, section 5.4), this
// is either the value of the "Host" header or the host name
// given in the URL itself. For HTTP/2, it is the value of the
// ":authority" pseudo-header field.
// It may be of the form "host:port". For international domain
// names, Host may be in Punycode or Unicode form. Use
// golang.org/x/net/idna to convert it to either format if
// needed.
// To prevent DNS rebinding attacks, server Handlers should
// validate that the Host header has a value for which the
// Handler considers itself authoritative. The included
// ServeMux supports patterns registered to particular host
// names and thus protects its registered Handlers.
//
// For client requests, Host optionally overrides the Host
// header to send. If empty, the Request.Write method uses
// the value of URL.Host. Host may contain an international
// domain name.
Host string
// Form contains the parsed form data, including both the URL
// field's query parameters and the PATCH, POST, or PUT form data.
// This field is only available after ParseForm is called.
// The HTTP client ignores Form and uses Body instead.
Form url.Values
// PostForm contains the parsed form data from PATCH, POST
// or PUT body parameters.
//
// This field is only available after ParseForm is called.
// The HTTP client ignores PostForm and uses Body instead.
PostForm url.Values // Go 1.1
// MultipartForm is the parsed multipart form, including file uploads.
// This field is only available after ParseMultipartForm is called.
// The HTTP client ignores MultipartForm and uses Body instead.
MultipartForm *multipart.Form
// Trailer specifies additional headers that are sent after the request
// body.
//
// For server requests, the Trailer map initially contains only the
// trailer keys, with nil values. (The client declares which trailers it
// will later send.) While the handler is reading from Body, it must
// not reference Trailer. After reading from Body returns EOF, Trailer
// can be read again and will contain non-nil values, if they were sent
// by the client.
//
// For client requests, Trailer must be initialized to a map containing
// the trailer keys to later send. The values may be nil or their final
// values. The ContentLength must be 0 or -1, to send a chunked request.
// After the HTTP request is sent the map values can be updated while
// the request body is read. Once the body returns EOF, the caller must
// not mutate Trailer.
//
// Writing a request whose Trailer contains a key with invalid bytes
// (such as CR or LF), or such a value present when Write begins,
// returns an error.
//
// Few HTTP clients, servers, or proxies support HTTP trailers.
Trailer Header
// RemoteAddr allows HTTP servers and other software to record
// the network address that sent the request, usually for
// logging. This field is not filled in by ReadRequest and
// has no defined format. The HTTP server in this package
// sets RemoteAddr to an "IP:port" address before invoking a
// handler.
// This field is ignored by the HTTP client.
RemoteAddr string
// RequestURI is the unmodified request-target of the
// Request-Line (RFC 7230, Section 3.1.1) as sent by the client
// to a server. Usually the URL field should be used instead.
// It is an error to set this field in an HTTP client request.
RequestURI string
// TLS allows HTTP servers and other software to record
// information about the TLS connection on which the request
// was received. This field is not filled in by ReadRequest.
// The HTTP server in this package sets the field for
// TLS-enabled connections before invoking a handler;
// otherwise it leaves the field nil.
// This field is ignored by the HTTP client.
TLS *tls.ConnectionState
// Cancel is an optional channel whose closure indicates that the client
// request should be regarded as canceled. Not all implementations of
// RoundTripper may support Cancel.
//
// For server requests, this field is not applicable.
//
// Deprecated: Set the Request's context with NewRequestWithContext
// instead. If a Request's Cancel field and context are both
// set, it is undefined whether Cancel is respected.
Cancel <-chan struct{} // Go 1.5
// Response is the redirect response which caused this request
// to be created. This field is only populated during client
// redirects.
Response *Response // Go 1.7
// Pattern is the [ServeMux] pattern that matched the request.
// It is empty if the request was not matched against a pattern.
Pattern string // Go 1.23
// contains filtered or unexported fields
}
func NewRequest
func NewRequest(method, url string, body io.Reader) (*Request, error)
NewRequest оборачивает NewRequestWithContext, используя context.Background.
func NewRequestWithContext 1.13
func NewRequestWithContext(ctx context.Context, method, url string, body io.Reader) (*Request, error)
NewRequestWithContext возвращает новый Request для заданных метода, URL и необязательного тела запроса.
Если указанное тело также реализует io.Closer, возвращаемое поле Request.Body устанавливается в body и будет закрыто (возможно, асинхронно) методами Client Do, Post и PostForm, а также методом Transport.RoundTrip.
NewRequestWithContext возвращает Request, пригодный для использования с Client.Do или Transport.RoundTrip. Чтобы создать запрос для тестирования обработчика Server, используйте функцию net/http/httptest.NewRequest, функцию ReadRequest или вручную измените поля Request. Для исходящего клиентского запроса контекст управляет всем временем жизни запроса и ответа на него: получением соединения, отправкой запроса, чтением заголовков ответа и его тела. О различиях между полями входящих и исходящих запросов см. документацию к типу Request.
Если body имеет тип *bytes.Buffer, *bytes.Reader или *strings.Reader, ContentLength возвращаемого запроса устанавливается в точное значение (вместо -1), заполняется GetBody (чтобы при перенаправлениях 307 и 308 можно было повторно отправить тело), а Body устанавливается в NoBody, если ContentLength равен 0.
func ReadRequest
func ReadRequest(b *bufio.Reader) (*Request, error)
ReadRequest считывает и разбирает входящий запрос из b.
ReadRequest — функция низкого уровня, предназначенная только для специализированных приложений; в большинстве случаев для чтения запросов и их обработки через интерфейс Handler следует использовать Server. ReadRequest поддерживает только запросы HTTP/1.x. Для HTTP/2 используйте golang.org/x/net/http2.
func (*Request) AddCookie
func (r *Request) AddCookie(c *Cookie)
AddCookie добавляет cookie в запрос. Согласно разделу 5.4 RFC 6265, AddCookie не добавляет более одного поля заголовка Cookie. Это означает, что все cookie, если они есть, записываются в одну строку через точку с запятой. AddCookie очищает только имя и значение c и не очищает уже имеющийся в запросе заголовок Cookie.
func (*Request) BasicAuth 1.4
func (r *Request) BasicAuth() (username, password string, ok bool)
BasicAuth возвращает имя пользователя и пароль, указанные в заголовке Authorization запроса, если в запросе используется базовая HTTP-аутентификация. См. раздел 2 RFC 2617.
func (*Request) Clone 1.13
func (r *Request) Clone(ctx context.Context) *Request
Clone возвращает глубокую копию r с контекстом, заменённым на ctx. Указанный ctx не должен быть nil.
Clone создаёт только поверхностную копию поля Body.
Для исходящего клиентского запроса контекст управляет всем временем жизни запроса и ответа на него: получением соединения, отправкой запроса, чтением заголовков ответа и его тела.
func (*Request) Context 1.7
func (r *Request) Context() context.Context
Context возвращает контекст запроса. Чтобы изменить контекст, используйте Request.Clone или Request.WithContext.
Возвращаемый контекст всегда не равен nil; по умолчанию используется фоновый контекст.
Для исходящих клиентских запросов контекст управляет отменой.
Для входящих запросов на сервер контекст отменяется при закрытии соединения клиента, отмене запроса (в HTTP/2) или возврате метода ServeHTTP.
func (*Request) Cookie
func (r *Request) Cookie(name string) (*Cookie, error)
Cookie возвращает cookie с указанным именем из запроса или ErrNoCookie, если cookie не найдена. Если указанному имени соответствуют несколько cookie, будет возвращена только одна из них.
func (*Request) Cookies
func (r *Request) Cookies() []*Cookie
Cookies разбирает и возвращает HTTP-cookie, отправленные вместе с запросом.
func (*Request) CookiesNamed 1.23
func (r *Request) CookiesNamed(name string) []*Cookie
CookiesNamed разбирает и возвращает HTTP-cookie с указанным именем, отправленные вместе с запросом, или пустой срез, если совпадений нет.
func (*Request) FormFile
func (r *Request) FormFile(key string) (multipart.File, *multipart.FileHeader, error)
FormFile возвращает первый файл для указанного ключа формы. При необходимости FormFile вызывает Request.ParseMultipartForm и Request.ParseForm.
func (*Request) FormValue
func (r *Request) FormValue(key string) string
FormValue возвращает первое значение указанного компонента запроса. Приоритет задаётся в следующем порядке:
- тело формы application/x-www-form-urlencoded (только для POST, PUT, PATCH)
- параметры запроса (всегда)
- тело формы multipart/form-data (всегда)
При необходимости FormValue вызывает Request.ParseMultipartForm и Request.ParseForm и игнорирует ошибки, возвращаемые этими функциями. Если ключ отсутствует, FormValue возвращает пустую строку. Чтобы получить несколько значений одного ключа, вызовите ParseForm, а затем обратитесь непосредственно к Request.Form.
func (*Request) MultipartReader
func (r *Request) MultipartReader() (*multipart.Reader, error)
MultipartReader возвращает MIME-ридер multipart, если это запрос POST типа multipart/form-data или multipart/mixed; в противном случае возвращаются nil и ошибка. Используйте эту функцию вместо Request.ParseMultipartForm, чтобы обрабатывать тело запроса как поток.
func (*Request) ParseForm
func (r *Request) ParseForm() error
ParseForm заполняет r.Form и r.PostForm.
Для всех запросов ParseForm разбирает необработанную строку запроса из URL и обновляет r.Form.
Для запросов POST, PUT и PATCH функция также считывает тело запроса, разбирает его как форму и помещает результаты в r.PostForm и r.Form. Параметры тела запроса имеют приоритет над значениями строки запроса URL в r.Form.
Если размер тела запроса ещё не был ограничен функцией MaxBytesReader, он ограничивается 10 МБ.
Для других методов HTTP или если Content-Type не равен application/x-www-form-urlencoded тело запроса не считывается, а r.PostForm инициализируется ненулевым пустым значением.
Request.ParseMultipartForm автоматически вызывает ParseForm. ParseForm идемпотентна.
func (*Request) ParseMultipartForm
func (r *Request) ParseMultipartForm(maxMemory int64) error
ParseMultipartForm разбирает тело запроса как multipart/form-data. Разбирается всё тело запроса; файловые части общим размером до maxMemory байт сохраняются в памяти, а остальные — на диске во временных файлах. При необходимости ParseMultipartForm вызывает Request.ParseForm. Если ParseForm возвращает ошибку, ParseMultipartForm возвращает её, но продолжает разбор тела запроса. После первого вызова ParseMultipartForm последующие вызовы ничего не делают.
func (*Request) PathValue 1.22
func (r *Request) PathValue(name string) string
PathValue возвращает значение именованного подстановочного элемента пути в шаблоне ServeMux, которому соответствует запрос. Если запрос не сопоставлен ни с одним шаблоном или шаблон не содержит такого подстановочного элемента, возвращается пустая строка.
Значение не экранировано. Например, если шаблону "/b/{bucket}" соответствует путь "/b/a%2fb", PathValue("bucket") возвращает "a/b".
func (*Request) PostFormValue 1.1
func (r *Request) PostFormValue(key string) string
PostFormValue возвращает первое значение указанного компонента тела запроса POST, PUT или PATCH. Параметры строки запроса URL игнорируются. При необходимости PostFormValue вызывает Request.ParseMultipartForm и Request.ParseForm и игнорирует ошибки, возвращаемые этими функциями. Если ключ отсутствует, PostFormValue возвращает пустую строку.
func (*Request) ProtoAtLeast
func (r *Request) ProtoAtLeast(major, minor int) bool
ProtoAtLeast сообщает, является ли версия протокола HTTP, используемого в запросе, не ниже major.minor.
func (*Request) Referer
func (r *Request) Referer() string
Referer возвращает URL страницы-источника, если он был передан в запросе.
Referer написано с ошибкой, как и в самом запросе; это ошибка, сохранившаяся с первых дней HTTP. Это значение также можно получить из карты Header как Header["Referer"]; преимущество метода в том, что компилятор может обнаружить программы, использующие альтернативное (правильное с точки зрения английского языка) написание req.Referrer(), но не может обнаружить программы, использующие Header["Referrer"].
func (*Request) SetBasicAuth
func (r *Request) SetBasicAuth(username, password string)
SetBasicAuth задаёт заголовок Authorization запроса для использования базовой HTTP-аутентификации с указанными именем пользователя и паролем.
При базовой HTTP-аутентификации указанные имя пользователя и пароль не шифруются. Как правило, её следует использовать только в HTTPS-запросах.
Имя пользователя не должно содержать двоеточие. Некоторые протоколы могут предъявлять дополнительные требования к предварительному экранированию имени пользователя и пароля. Например, при использовании OAuth2 оба аргумента сначала необходимо закодировать для URL с помощью url.QueryEscape.
func (*Request) SetPathValue 1.22
func (r *Request) SetPathValue(name, value string)
SetPathValue присваивает name значение value, чтобы последующие вызовы r.PathValue(name) возвращали value. Функция не снимает экранирование с value.
func (*Request) UserAgent
func (r *Request) UserAgent() string
UserAgent возвращает User-Agent клиента, если он был передан в запросе.
func (*Request) WithContext 1.7
func (r *Request) WithContext(ctx context.Context) *Request
WithContext возвращает поверхностную копию r с контекстом, заменённым на ctx. Указанный ctx не должен быть nil.
Для исходящего клиентского запроса контекст управляет всем временем жизни запроса и ответа на него: получением соединения, отправкой запроса, чтением заголовков ответа и его тела.
Чтобы создать новый запрос с контекстом, используйте NewRequestWithContext. Чтобы создать глубокую копию запроса с новым контекстом, используйте Request.Clone.
func (*Request) Write
func (r *Request) Write(w io.Writer) error
Write записывает запрос HTTP/1.1 — заголовок и тело — в формате передачи. Метод использует следующие поля запроса:
Host URL Method (defaults to "GET") Header ContentLength TransferEncoding Body
Если Body задано, Content-Length меньше или равен 0, а Request.TransferEncoding не установлено в "identity", Write добавляет в заголовок "Transfer-Encoding: chunked". После отправки Body закрывается.
Значения заголовков Host, Content-Length, Transfer-Encoding и Trailer не используются; они определяются на основе других полей Request. Если в Header нет значения User-Agent, Write использует "Go-http-client/1.1".
func (*Request) WriteProxy
func (r *Request) WriteProxy(w io.Writer) error
WriteProxy похож на Request.Write, но записывает запрос в форме, ожидаемой HTTP-прокси. В частности, Request.WriteProxy записывает начальную строку Request-URI запроса с абсолютным URI, согласно разделу 5.3 RFC 7230, включая схему и узел. В обоих случаях WriteProxy также записывает заголовок Host, используя r.Host или r.URL.Host.
type Response
Response представляет ответ на HTTP-запрос.
Client и Transport возвращают Responses от серверов после получения заголовков ответа. Тело ответа передаётся по мере чтения поля Body.
type Response struct {
Status string // e.g. "200 OK"
StatusCode int // e.g. 200
Proto string // e.g. "HTTP/1.0"
ProtoMajor int // e.g. 1
ProtoMinor int // e.g. 0
// Header maps header keys to values. If the response had multiple
// headers with the same key, they may be concatenated, with comma
// delimiters. (RFC 7230, section 3.2.2 requires that multiple headers
// be semantically equivalent to a comma-delimited sequence.) When
// Header values are duplicated by other fields in this struct (e.g.,
// ContentLength, TransferEncoding, Trailer), the field values are
// authoritative.
//
// Keys in the map are canonicalized (see CanonicalHeaderKey).
Header Header
// Body represents the response body.
//
// The response body is streamed on demand as the Body field
// is read. If the network connection fails or the server
// terminates the response, Body.Read calls return an error.
//
// The http Client and Transport guarantee that Body is always
// non-nil, even on responses without a body or responses with
// a zero-length body. It is the caller's responsibility to
// close Body. The default HTTP client's Transport may not
// reuse HTTP/1.x "keep-alive" TCP connections if the Body is
// not read to completion and closed; however, manually reading
// the body to completion should not be needed in most cases,
// as closing the body will also cause the body to be read to
// completion asynchronously, up to a conservative limit.
//
// The Body is automatically dechunked if the server replied
// with a "chunked" Transfer-Encoding.
//
// As of Go 1.12, the Body will also implement io.Writer
// on a successful "101 Switching Protocols" response,
// as used by WebSockets and HTTP/2's "h2c" mode.
Body io.ReadCloser
// ContentLength records the length of the associated content. The
// value -1 indicates that the length is unknown. Unless Request.Method
// is "HEAD", values >= 0 indicate that the given number of bytes may
// be read from Body.
ContentLength int64
// Contains transfer encodings from outer-most to inner-most. Value is
// nil, means that "identity" encoding is used.
TransferEncoding []string
// Close records whether the header directed that the connection be
// closed after reading Body. The value is advice for clients: neither
// ReadResponse nor Response.Write ever closes a connection.
Close bool
// Uncompressed reports whether the response was sent compressed but
// was decompressed by the http package. When true, reading from
// Body yields the uncompressed content instead of the compressed
// content actually set from the server, ContentLength is set to -1,
// and the "Content-Length" and "Content-Encoding" fields are deleted
// from the responseHeader. To get the original response from
// the server, set Transport.DisableCompression to true.
Uncompressed bool // Go 1.7
// Trailer maps trailer keys to values in the same
// format as Header.
//
// The Trailer initially contains only nil values, one for
// each key specified in the server's "Trailer" header
// value. Those values are not added to Header.
//
// Trailer must not be accessed concurrently with Read calls
// on the Body.
//
// After Body.Read has returned io.EOF, Trailer will contain
// any trailer values sent by the server.
Trailer Header
// Request is the request that was sent to obtain this Response.
// Request's Body is nil (having already been consumed).
// This is only populated for Client requests.
Request *Request
// TLS contains information about the TLS connection on which the
// response was received. It is nil for unencrypted responses.
// The pointer is shared between responses and should not be
// modified.
TLS *tls.ConnectionState // Go 1.3
}
func Get
func Get(url string) (resp *Response, err error)
Get отправляет GET-запрос на указанный URL. Если ответ имеет один из следующих кодов перенаправления, Get следует перенаправлению, но не более 10 раз:
301 (Moved Permanently) 302 (Found) 303 (See Other) 307 (Temporary Redirect) 308 (Permanent Redirect)
Ошибка возвращается, если перенаправлений было слишком много или произошла ошибка протокола HTTP. Ответ с кодом вне диапазона 2xx не вызывает ошибку. Любая возвращённая ошибка будет иметь тип *url.Error. Метод Timeout значения url.Error сообщит true, если время ожидания запроса истекло.
Если err равен nil, resp всегда содержит ненулевое значение resp.Body. По завершении чтения вызывающий код должен закрыть resp.Body.
Get — это обёртка над DefaultClient.Get.
Чтобы отправить запрос с пользовательскими заголовками, используйте NewRequest и DefaultClient.Do.
Чтобы отправить запрос с заданным context.Context, используйте NewRequestWithContext и DefaultClient.Do.
Пример
Код:
res, err := http.Get("http://www.google.com/robots.txt")
if err != nil {
log.Fatal(err)
}
body, err := io.ReadAll(res.Body)
res.Body.Close()
if res.StatusCode > 299 {
log.Fatalf("Response failed with status code: %d and\nbody: %s\n", res.StatusCode, body)
}
if err != nil {
log.Fatal(err)
}
fmt.Printf("%s", body)
func Head
func Head(url string) (resp *Response, err error)
Head отправляет HEAD-запрос на указанный URL. Если ответ имеет один из следующих кодов перенаправления, Head следует перенаправлению, но не более 10 раз:
301 (Moved Permanently) 302 (Found) 303 (See Other) 307 (Temporary Redirect) 308 (Permanent Redirect)
Head — это обёртка над DefaultClient.Head.
Чтобы отправить запрос с заданным context.Context, используйте NewRequestWithContext и DefaultClient.Do.
func Post
func Post(url, contentType string, body io.Reader) (resp *Response, err error)
Post отправляет POST-запрос на указанный URL.
По завершении чтения вызывающий код должен закрыть resp.Body.
Если указанное тело реализует io.Closer, оно закрывается после запроса.
Post — это обёртка над DefaultClient.Post.
Чтобы задать пользовательские заголовки, используйте NewRequest и DefaultClient.Do.
Подробности обработки перенаправлений см. в документации к методу Client.Do.
Чтобы отправить запрос с заданным context.Context, используйте NewRequestWithContext и DefaultClient.Do.
func PostForm
func PostForm(url string, data url.Values) (resp *Response, err error)
PostForm отправляет POST-запрос на указанный URL, кодируя ключи и значения data в формате URL и помещая их в тело запроса.
Заголовок Content-Type устанавливается в application/x-www-form-urlencoded. Чтобы задать другие заголовки, используйте NewRequest и DefaultClient.Do.
Если err равен nil, resp всегда содержит ненулевое значение resp.Body. По завершении чтения вызывающий код должен закрыть resp.Body.
PostForm — это обёртка над DefaultClient.PostForm.
Подробности обработки перенаправлений см. в документации к методу Client.Do.
Чтобы отправить запрос с заданным context.Context, используйте NewRequestWithContext и DefaultClient.Do.
func ReadResponse
func ReadResponse(r *bufio.Reader, req *Request) (*Response, error)
ReadResponse считывает и возвращает HTTP-ответ из r. Параметр req необязателен и указывает соответствующий этому Response объект Request. Если он равен nil, предполагается GET-запрос. По завершении чтения resp.Body клиент должен вызвать resp.Body.Close. После этого вызова клиент может проверить resp.Trailer и получить пары ключ-значение, включённые в завершающую часть ответа.
func (*Response) Cookies
func (r *Response) Cookies() []*Cookie
Cookies разбирает и возвращает cookie, заданные в заголовках Set-Cookie.
func (*Response) Location
func (r *Response) Location() (*url.URL, error)
Location возвращает URL из заголовка ответа "Location", если он присутствует. Относительные перенаправления разрешаются относительно Response.Request. Если заголовок Location отсутствует, возвращается ErrNoLocation.
func (*Response) ProtoAtLeast
func (r *Response) ProtoAtLeast(major, minor int) bool
ProtoAtLeast сообщает, является ли версия протокола HTTP, используемого в ответе, не ниже major.minor.
func (*Response) Write
func (r *Response) Write(w io.Writer) error
Write записывает r в w в формате ответа сервера HTTP/1.x, включая строку состояния, заголовки, тело и необязательную завершающую часть.
Метод использует следующие поля ответа r:
StatusCode ProtoMajor ProtoMinor Request.Method TransferEncoding Trailer Body ContentLength Header, values for non-canonical keys will have unpredictable behavior
После отправки тело Response закрывается.
type ResponseController 1.20
ResponseController используется HTTP-обработчиком для управления ответом.
ResponseController нельзя использовать после возврата метода Handler.ServeHTTP.
type ResponseController struct {
// contains filtered or unexported fields
}
func NewResponseController 1.20
func NewResponseController(rw ResponseWriter) *ResponseController
NewResponseController создаёт ResponseController для запроса.
ResponseWriter должен быть исходным значением, переданным методу Handler.ServeHTTP, или иметь метод Unwrap, возвращающий исходный ResponseWriter.
Если ResponseWriter реализует любой из следующих методов, ResponseController будет вызывать их при необходимости:
Flush() FlushError() error // alternative Flush returning an error Hijack() (net.Conn, *bufio.ReadWriter, error) SetReadDeadline(deadline time.Time) error SetWriteDeadline(deadline time.Time) error EnableFullDuplex() error
Если ResponseWriter не поддерживает метод, ResponseController возвращает ошибку, соответствующую ErrNotSupported.
func (*ResponseController) EnableFullDuplex 1.21
func (c *ResponseController) EnableFullDuplex() error
EnableFullDuplex указывает, что обработчик запроса будет чередовать чтение из Request.Body и запись в ResponseWriter.
Для запросов HTTP/1 сервер Go по умолчанию считывает всю непрочитанную часть тела запроса перед началом записи ответа, не позволяя обработчикам одновременно читать запрос и записывать ответ. Вызов EnableFullDuplex отключает такое поведение и позволяет обработчикам продолжать чтение запроса одновременно с записью ответа.
Для запросов HTTP/2 сервер Go всегда разрешает одновременное чтение и отправку ответов.
func (*ResponseController) Flush 1.20
func (c *ResponseController) Flush() error
Flush отправляет клиенту данные из буфера.
func (*ResponseController) Hijack 1.20
func (c *ResponseController) Hijack() (net.Conn, *bufio.ReadWriter, error)
Hijack позволяет вызывающему коду перехватить соединение. Подробности см. в описании интерфейса Hijacker.
func (*ResponseController) SetReadDeadline 1.20
func (c *ResponseController) SetReadDeadline(deadline time.Time) error
SetReadDeadline задаёт срок чтения всего запроса, включая тело. Чтение тела запроса после истечения срока завершится ошибкой. Нулевое значение означает отсутствие срока.
Установка срока чтения после его истечения не продлит его.
func (*ResponseController) SetWriteDeadline 1.20
func (c *ResponseController) SetWriteDeadline(deadline time.Time) error
SetWriteDeadline задаёт срок записи ответа. Запись в тело ответа после истечения срока не будет блокироваться, но может завершиться успешно, если данные были помещены в буфер. Нулевое значение означает отсутствие срока.
Установка срока записи после его истечения не продлит его.
type ResponseWriter
Интерфейс ResponseWriter используется HTTP-обработчиком для формирования HTTP-ответа.
ResponseWriter нельзя использовать после возврата метода Handler.ServeHTTP.
type ResponseWriter interface {
// Header returns the header map that will be sent by
// [ResponseWriter.WriteHeader]. The [Header] map also is the mechanism with which
// [Handler] implementations can set HTTP trailers.
//
// Changing the header map after a call to [ResponseWriter.WriteHeader] (or
// [ResponseWriter.Write]) has no effect unless the HTTP status code was of the
// 1xx class or the modified headers are trailers.
//
// There are two ways to set Trailers. The preferred way is to
// predeclare in the headers which trailers you will later
// send by setting the "Trailer" header to the names of the
// trailer keys which will come later. In this case, those
// keys of the Header map are treated as if they were
// trailers. See the example. The second way, for trailer
// keys not known to the [Handler] until after the first [ResponseWriter.Write],
// is to prefix the [Header] map keys with the [TrailerPrefix]
// constant value.
//
// To suppress automatic response headers (such as "Date"), set
// their value to nil.
Header() Header
// Write writes the data to the connection as part of an HTTP reply.
//
// If [ResponseWriter.WriteHeader] has not yet been called, Write calls
// WriteHeader(http.StatusOK) before writing the data. If the Header
// does not contain a Content-Type line, Write adds a Content-Type set
// to the result of passing the initial 512 bytes of written data to
// [DetectContentType]. Additionally, if the total size of all written
// data is under a few KB and there are no Flush calls, the
// Content-Length header is added automatically.
//
// Depending on the HTTP protocol version and the client, calling
// Write or WriteHeader may prevent future reads on the
// Request.Body. For HTTP/1.x requests, handlers should read any
// needed request body data before writing the response. Once the
// headers have been flushed (due to either an explicit Flusher.Flush
// call or writing enough data to trigger a flush), the request body
// may be unavailable. For HTTP/2 requests, the Go HTTP server permits
// handlers to continue to read the request body while concurrently
// writing the response. However, such behavior may not be supported
// by all HTTP/2 clients. Handlers should read before writing if
// possible to maximize compatibility.
Write([]byte) (int, error)
// WriteHeader sends an HTTP response header with the provided
// status code.
//
// If WriteHeader is not called explicitly, the first call to Write
// will trigger an implicit WriteHeader(http.StatusOK).
// Thus explicit calls to WriteHeader are mainly used to
// send error codes or 1xx informational responses.
//
// The provided code must be a valid HTTP 1xx-5xx status code.
// Any number of 1xx headers may be written, followed by at most
// one 2xx-5xx header. 1xx headers are sent immediately, but 2xx-5xx
// headers may be buffered. Use the Flusher interface to send
// buffered data. The header map is cleared when 2xx-5xx headers are
// sent, but not with 1xx headers.
//
// The server will automatically send a 100 (Continue) header
// on the first read from the request body if the request has
// an "Expect: 100-continue" header.
WriteHeader(statusCode int)
} Пример (завершающие заголовки)
Завершающие заголовки HTTP — это набор пар ключ-значение, подобных обычным заголовкам, которые передаются после HTTP-ответа, а не перед ним.
Код:
mux := http.NewServeMux()
mux.HandleFunc("/sendstrailers", func(w http.ResponseWriter, req *http.Request) {
// Before any call to WriteHeader or Write, declare
// the trailers you will set during the HTTP
// response. These three headers are actually sent in
// the trailer.
w.Header().Set("Trailer", "AtEnd1, AtEnd2")
w.Header().Add("Trailer", "AtEnd3")
w.Header().Set("Content-Type", "text/plain; charset=utf-8") // normal header
w.WriteHeader(http.StatusOK)
w.Header().Set("AtEnd1", "value 1")
io.WriteString(w, "This HTTP response has both headers before this text and trailers at the end.\n")
w.Header().Set("AtEnd2", "value 2")
w.Header().Set("AtEnd3", "value 3") // These will appear as trailers.
})
type RoundTripper
RoundTripper — это интерфейс, представляющий возможность выполнить одну HTTP-транзакцию и получить Response для заданного Request.
RoundTripper должен быть безопасен для одновременного использования несколькими горутинами.
type RoundTripper interface {
// RoundTrip executes a single HTTP transaction, returning
// a Response for the provided Request.
//
// RoundTrip should not attempt to interpret the response. In
// particular, RoundTrip must return err == nil if it obtained
// a response, regardless of the response's HTTP status code.
// A non-nil err should be reserved for failure to obtain a
// response. Similarly, RoundTrip should not attempt to
// handle higher-level protocol details such as redirects,
// authentication, or cookies.
//
// RoundTrip should not modify the request, except for
// consuming and closing the Request's Body. RoundTrip may
// read fields of the request in a separate goroutine. Callers
// should not mutate or reuse the request until the Response's
// Body has been closed.
//
// RoundTrip must always close the body, including on errors,
// but depending on the implementation may do so in a separate
// goroutine even after RoundTrip returns. This means that
// callers wanting to reuse the body for subsequent requests
// must arrange to wait for the Close call before doing so.
//
// The Request's URL and Header fields must be initialized.
RoundTrip(*Request) (*Response, error)
} DefaultTransport — стандартная реализация Transport, используемая DefaultClient. Она устанавливает сетевые соединения по мере необходимости и кэширует их для повторного использования при последующих вызовах. Она использует HTTP-прокси, заданные переменными среды HTTP_PROXY, HTTPS_PROXY и NO_PROXY (или их вариантами в нижнем регистре).
var DefaultTransport RoundTripper = &Transport{
Proxy: ProxyFromEnvironment,
DialContext: defaultTransportDialContext(&net.Dialer{
Timeout: 30 * time.Second,
KeepAlive: 30 * time.Second,
}),
ForceAttemptHTTP2: true,
MaxIdleConns: 100,
IdleConnTimeout: 90 * time.Second,
TLSHandshakeTimeout: 10 * time.Second,
ExpectContinueTimeout: 1 * time.Second,
} func NewFileTransport
func NewFileTransport(fs FileSystem) RoundTripper
NewFileTransport возвращает новый RoundTripper, обслуживающий предоставленную FileSystem. Возвращённый RoundTripper игнорирует хост URL во входящих запросах, а также большинство других свойств запроса.
Типичный вариант использования NewFileTransport — регистрация протокола "file" в Transport, как показано ниже:
t := &http.Transport{}
t.RegisterProtocol("file", http.NewFileTransport(http.Dir("/")))
c := &http.Client{Transport: t}
res, err := c.Get("file:///etc/passwd")
...
func NewFileTransportFS 1.22
func NewFileTransportFS(fsys fs.FS) RoundTripper
NewFileTransportFS возвращает новый RoundTripper, обслуживающий предоставленную файловую систему fsys. Возвращённый RoundTripper игнорирует хост URL во входящих запросах, а также большинство других свойств запроса. Файлы, предоставленные fsys, должны реализовывать io.Seeker.
Типичный вариант использования NewFileTransportFS — регистрация протокола "file" в Transport, как показано ниже:
fsys := os.DirFS("/")
t := &http.Transport{}
t.RegisterProtocol("file", http.NewFileTransportFS(fsys))
c := &http.Client{Transport: t}
res, err := c.Get("file:///etc/passwd")
...
type SameSite 1.11
SameSite позволяет серверу задать атрибут cookie, запрещающий браузеру отправлять эту cookie вместе с межсайтовыми запросами. Основная цель — снизить риск утечки информации между источниками и обеспечить некоторую защиту от атак с подделкой межсайтовых запросов.
Подробности см. на странице https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00.
type SameSite int
const (
SameSiteDefaultMode SameSite = iota + 1
SameSiteLaxMode
SameSiteStrictMode
SameSiteNoneMode
) type ServeMux
ServeMux — мультиплексор HTTP-запросов. Он сопоставляет URL каждого входящего запроса со списком зарегистрированных шаблонов и вызывает обработчик шаблона, который наиболее точно соответствует URL.
Шаблоны
Шаблоны могут соответствовать методу, хосту и пути запроса. Несколько примеров:
- "/index.html" соответствует пути "/index.html" для любого хоста и метода.
- "GET /static/" соответствует запросу GET, путь которого начинается с "/static/".
- "example.com/" соответствует любому запросу к хосту "example.com".
- "example.com/{$}" соответствует запросам с хостом "example.com" и путём "/".
- "/b/{bucket}/o/{objectname...}" соответствует путям, первый сегмент которых — "b", а третий — "o". Имя "bucket" обозначает второй сегмент, а "objectname" — остаток пути.
В общем случае шаблон выглядит так:
[METHOD ][HOST]/[PATH]
Все три части необязательны; "/" — допустимый шаблон. Если указан METHOD, за ним должен следовать как минимум один пробел или знак табуляции.
Литеральные (то есть не являющиеся подстановочными символами) части шаблона сопоставляются с соответствующими частями запроса с учётом регистра.
Шаблон без метода соответствует любому методу. Шаблон с методом GET соответствует запросам GET и HEAD. В остальных случаях метод должен совпадать точно.
Шаблон без хоста соответствует любому хосту. Шаблон с хостом соответствует только URL на этом хосте.
Путь может содержать сегменты-подстановки вида {NAME} или {NAME...}. Например, "/b/{bucket}/o/{objectname...}". Имя подстановки должно быть допустимым идентификатором Go. Подстановки должны занимать целые сегменты пути: перед ними должна стоять косая черта, а после них — косая черта или конец строки. Например, "/b_{bucket}" — недопустимый шаблон.
Обычно подстановка соответствует только одному сегменту пути, заканчивающемуся на следующей буквальной косой черте (а не %2F) в URL запроса. Если же указано "...", подстановка соответствует оставшейся части пути URL, включая косые черты. (Поэтому подстановка "..." может находиться только в конце шаблона.) Значение подстановки можно получить, вызвав Request.PathValue с именем подстановки. Косая черта в конце пути действует как анонимная подстановка "...".
Специальная подстановка {$} соответствует только концу URL. Например, шаблон "/{$}" соответствует только пути "/", а шаблон "/" — любому пути.
При сопоставлении пути шаблонов и пути входящих запросов отмена экранирования выполняется для каждого сегмента отдельно. Так, например, путь "/a%2Fb/100%25" рассматривается как состоящий из двух сегментов: "a/b" и "100%". Шаблон "/a%2fb/" ему соответствует, а шаблон "/a/b/" — нет.
Приоритет
Если запросу соответствуют два или более шаблона, приоритет имеет наиболее конкретный шаблон. Шаблон P1 конкретнее P2, если P1 соответствует строгому подмножеству запросов, которым соответствует P2; то есть если P2 соответствует всем запросам P1 и некоторым дополнительным. Если ни один шаблон не конкретнее другого, шаблоны конфликтуют. Из этого правила есть одно исключение для обратной совместимости: если два шаблона иначе конфликтовали бы, но один из них содержит хост, а другой нет, приоритет имеет шаблон с хостом. Если шаблон, переданный в ServeMux.Handle или ServeMux.HandleFunc, конфликтует с уже зарегистрированным шаблоном, эти функции вызывают панику.
Например, согласно общему правилу, "/images/thumbnails/" конкретнее, чем "/images/", поэтому можно зарегистрировать оба шаблона. Первый соответствует путям, начинающимся с "/images/thumbnails/", а второй будет соответствовать любому другому пути в поддереве "/images/".
В качестве ещё одного примера рассмотрим шаблоны "GET /" и "/index.html": оба соответствуют запросу GET для "/index.html", но первый шаблон соответствует всем остальным запросам GET и HEAD, а второй — любому запросу для "/index.html" с другим методом. Эти шаблоны конфликтуют.
Перенаправление при отсутствии завершающей косой черты
Рассмотрим ServeMux с обработчиком поддерева, зарегистрированным с завершающей косой чертой или подстановкой "...". Если ServeMux получает запрос к корню поддерева без завершающей косой черты, он перенаправляет запрос, добавляя завершающую косую черту. Это поведение можно переопределить, зарегистрировав отдельно путь без завершающей косой черты или подстановки "...". Например, регистрация "/images/" заставляет ServeMux перенаправлять запрос для "/images" на "/images/", если только "/images" не зарегистрирован отдельно.
Очистка запросов
ServeMux также очищает путь URL запроса и заголовок Host, удаляя номер порта и перенаправляя запросы с сегментами . или .. либо повторяющимися косыми чертами на эквивалентный, более чистый URL. Экранированные элементы пути, например "%2e" для "." и "%2f" для "/", сохраняются и не считаются разделителями при маршрутизации запросов.
Совместимость
Синтаксис шаблонов ServeMux и поведение сопоставления существенно изменились в Go 1.22. Чтобы восстановить прежнее поведение, задайте переменной среды GODEBUG значение "httpmuxgo121=1". Это значение считывается один раз при запуске программы; изменения во время выполнения игнорируются.
К обратно несовместимым изменениям относятся:
- В версии 1.21 подстановки — это обычные буквальные сегменты пути. Например, шаблон "/{x}" в версии 1.21 будет соответствовать только этому пути, а в версии 1.22 — любому пути с одним сегментом.
- В версии 1.21 ни один шаблон не отклонялся, кроме пустых шаблонов и шаблонов, конфликтующих с уже существующими. В версии 1.22 синтаксически недопустимые шаблоны вызывают панику в ServeMux.Handle и ServeMux.HandleFunc. Например, в версии 1.21 шаблоны "/{" и "/a{x}" соответствуют сами себе, а в версии 1.22 они недопустимы и вызывают панику при регистрации.
- В версии 1.22 для каждого сегмента шаблона выполняется отмена экранирования; в версии 1.21 этого не делалось. Например, в версии 1.22 шаблон "/%61" соответствует пути "/a" ("%61" — это URL-последовательность экранирования для "a"), а в версии 1.21 он соответствовал бы только пути "/%2561" (где "%25" — это последовательность экранирования для знака процента).
- При сопоставлении шаблонов с путями в версии 1.22 для каждого сегмента пути выполняется отмена экранирования; в версии 1.21 отмена экранирования выполнялась для всего пути целиком. Это изменение в основном влияет на обработку путей с последовательностями экранирования %2F рядом с косыми чертами. Подробности см. на странице https://go.dev/issue/21955.
type ServeMux struct {
// contains filtered or unexported fields
}
func NewServeMux
func NewServeMux() *ServeMux
NewServeMux выделяет память и возвращает новый ServeMux.
func (*ServeMux) Handle
func (mux *ServeMux) Handle(pattern string, handler Handler)
Handle регистрирует обработчик для заданного шаблона. Если заданный шаблон конфликтует с уже зарегистрированным или является недопустимым, Handle вызывает панику.
Подробные сведения о допустимых шаблонах и правилах конфликтов см. в описании ServeMux.
Пример
Код:
mux := http.NewServeMux()
mux.Handle("/api/", apiHandler{})
mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
// The "/" pattern matches everything, so we need to check
// that we're at the root here.
if req.URL.Path != "/" {
http.NotFound(w, req)
return
}
fmt.Fprintf(w, "Welcome to the home page!")
})
func (*ServeMux) HandleFunc
func (mux *ServeMux) HandleFunc(pattern string, handler func(ResponseWriter, *Request))
HandleFunc регистрирует функцию-обработчик для заданного шаблона. Если заданный шаблон конфликтует с уже зарегистрированным или является недопустимым, HandleFunc вызывает панику.
Подробные сведения о допустимых шаблонах и правилах конфликтов см. в описании ServeMux.
func (*ServeMux) Handler 1.1
func (mux *ServeMux) Handler(r *Request) (h Handler, pattern string)
Handler возвращает обработчик для заданного запроса, учитывая r.Method, r.Host и r.URL.Path. Он всегда возвращает ненулевой обработчик. Если путь не имеет канонической формы, обработчиком будет созданный внутри обработчик, перенаправляющий на канонический путь. Если хост содержит порт, при сопоставлении обработчиков он игнорируется.
Для запросов CONNECT путь и хост используются без изменений.
Handler также возвращает зарегистрированный шаблон, соответствующий запросу, или, в случае созданных внутри перенаправлений, путь, которому запрос будет соответствовать после перенаправления.
Если для запроса нет подходящего зарегистрированного обработчика, Handler возвращает обработчик «страница не найдена» или «метод не поддерживается» и пустой шаблон.
Handler не изменяет свой аргумент. В частности, он не заполняет именованные подстановки пути, поэтому r.PathValue всегда возвращает пустую строку.
func (*ServeMux) ServeHTTP
func (mux *ServeMux) ServeHTTP(w ResponseWriter, r *Request)
ServeHTTP передаёт запрос обработчику, шаблон которого наиболее точно соответствует URL запроса.
type Server
Server задаёт параметры для запуска HTTP-сервера. Нулевое значение Server является допустимой конфигурацией.
type Server struct {
// Addr optionally specifies the TCP address for the server to listen on,
// in the form "host:port". If empty, ":http" (port 80) is used.
// The service names are defined in RFC 6335 and assigned by IANA.
// See net.Dial for details of the address format.
Addr string
Handler Handler // handler to invoke, http.DefaultServeMux if nil
// DisableGeneralOptionsHandler, if true, passes "OPTIONS *" requests to the Handler,
// otherwise responds with 200 OK and Content-Length: 0.
DisableGeneralOptionsHandler bool // Go 1.20
// TLSConfig optionally provides a TLS configuration for use
// by ServeTLS and ListenAndServeTLS. Note that this value is
// cloned by ServeTLS and ListenAndServeTLS, so it's not
// possible to modify the configuration with methods like
// tls.Config.SetSessionTicketKeys. To use
// SetSessionTicketKeys, use Server.Serve with a TLS Listener
// instead.
TLSConfig *tls.Config
// ReadTimeout is the maximum duration for reading the entire
// request, including the body. A zero or negative value means
// there will be no timeout.
//
// Because ReadTimeout does not let Handlers make per-request
// decisions on each request body's acceptable deadline or
// upload rate, most users will prefer to use
// ReadHeaderTimeout. It is valid to use them both.
ReadTimeout time.Duration
// ReadHeaderTimeout is the amount of time allowed to read
// request headers. The connection's read deadline is reset
// after reading the headers and the Handler can decide what
// is considered too slow for the body. If zero, the value of
// ReadTimeout is used. If negative, or if zero and ReadTimeout
// is zero or negative, there is no timeout.
ReadHeaderTimeout time.Duration // Go 1.8
// WriteTimeout is the maximum duration before timing out
// writes of the response. It is reset whenever a new
// request's header is read. Like ReadTimeout, it does not
// let Handlers make decisions on a per-request basis.
// A zero or negative value means there will be no timeout.
WriteTimeout time.Duration
// IdleTimeout is the maximum amount of time to wait for the
// next request when keep-alives are enabled. If zero, the value
// of ReadTimeout is used. If negative, or if zero and ReadTimeout
// is zero or negative, there is no timeout.
IdleTimeout time.Duration // Go 1.8
// MaxHeaderBytes controls the maximum number of bytes the
// server will read parsing the request header's keys and
// values, including the request line. It does not limit the
// size of the request body.
// If zero, DefaultMaxHeaderBytes is used.
MaxHeaderBytes int
// MaxHeaderValueCount controls the maximum number of header
// values that the server is willing to parse from a request.
// If zero, DefaultMaxHeaderValueCount is used.
// Note that comma-separated values in a single header line are
// counted once, while values sent as multiple header lines are
// counted multiple times.
MaxHeaderValueCount int // Go 1.27
// TLSNextProto optionally specifies a function to take over
// ownership of the provided TLS connection when an ALPN
// protocol upgrade has occurred. The map key is the protocol
// name negotiated. The Handler argument should be used to
// handle HTTP requests and will initialize the Request's TLS
// and RemoteAddr if not already set. The connection is
// automatically closed when the function returns.
// If TLSNextProto is not nil, HTTP/2 support is not enabled
// automatically.
//
// Historically, TLSNextProto was used to disable HTTP/2 support.
// The Server.Protocols field now provides a simpler way to do this.
TLSNextProto map[string]func(*Server, *tls.Conn, Handler) // Go 1.1
// ConnState specifies an optional callback function that is
// called when a client connection changes state. See the
// ConnState type and associated constants for details.
ConnState func(net.Conn, ConnState) // Go 1.3
// ErrorLog specifies an optional logger for errors accepting
// connections, unexpected behavior from handlers, and
// underlying FileSystem errors.
// If nil, logging is done via the log package's standard logger.
ErrorLog *log.Logger // Go 1.3
// BaseContext optionally specifies a function that returns
// the base context for incoming requests on this server.
// The provided Listener is the specific Listener that's
// about to start accepting requests.
// If BaseContext is nil, the default is context.Background().
// If non-nil, it must return a non-nil context.
BaseContext func(net.Listener) context.Context // Go 1.13
// ConnContext optionally specifies a function that modifies
// the context used for a new connection c. The provided ctx
// is derived from the base context and has a ServerContextKey
// value.
ConnContext func(ctx context.Context, c net.Conn) context.Context // Go 1.13
// HTTP2 configures HTTP/2 connections.
HTTP2 *HTTP2Config // Go 1.24
// Protocols is the set of protocols accepted by the server.
//
// If Protocols includes UnencryptedHTTP2, the server will accept
// unencrypted HTTP/2 connections. The server can serve both
// HTTP/1 and unencrypted HTTP/2 on the same address and port.
//
// If Protocols is nil, the default is usually HTTP/1 and HTTP/2.
// If TLSNextProto is non-nil and does not contain an "h2" entry,
// the default is HTTP/1 only.
Protocols *Protocols // Go 1.24
// DisableClientPriority specifies whether client-specified priority, as
// specified in RFC 9218, should be respected or not.
//
// This field only takes effect if using HTTP/2, and if no custom write
// scheduler is defined for the HTTP/2 server. Otherwise, this field is a
// no-op.
//
// If set to true, requests will be served in a round-robin manner, without
// prioritization.
DisableClientPriority bool // Go 1.27
// contains filtered or unexported fields
}
func (*Server) Close 1.8
func (s *Server) Close() error
Close немедленно закрывает все активные net.Listeners и все соединения в состояниях StateNew, StateActive или StateIdle. Для корректного завершения работы используйте Server.Shutdown.
Close не пытается закрывать перехваченные соединения, например WebSocket, и даже не знает о них.
Close возвращает ошибки, возникшие при закрытии базовых Listener(s) объекта Server.
func (*Server) ListenAndServe
func (s *Server) ListenAndServe() error
ListenAndServe принимает подключения по TCP-адресу s.Addr, а затем вызывает Serve для обработки запросов по входящим соединениям. Для принятых соединений включается поддержка TCP keep-alive.
Если s.Addr пуст, используется ":http".
ListenAndServe всегда возвращает ненулевую ошибку. После вызова Server.Shutdown или Server.Close возвращается ошибка ErrServerClosed.
func (*Server) ListenAndServeTLS
func (s *Server) ListenAndServeTLS(certFile, keyFile string) error
ListenAndServeTLS принимает подключения по TCP-адресу s.Addr, а затем вызывает ServeTLS для обработки запросов по входящим TLS-соединениям. Для принятых соединений включается поддержка TCP keep-alive.
Если ни TLSConfig.Certificates, ни TLSConfig.GetCertificate объекта Server не заполнены, необходимо предоставить имена файлов, содержащих сертификат сервера и соответствующий закрытый ключ. Если сертификат подписан центром сертификации, certFile должен содержать объединённые сертификат сервера, все промежуточные сертификаты и сертификат центра сертификации.
Если s.Addr пуст, используется ":https".
ListenAndServeTLS всегда возвращает ненулевую ошибку. После вызова Server.Shutdown или Server.Close возвращается ошибка ErrServerClosed.
func (*Server) RegisterOnShutdown 1.9
func (s *Server) RegisterOnShutdown(f func())
RegisterOnShutdown регистрирует функцию, вызываемую при Server.Shutdown. Это можно использовать для корректного завершения соединений, прошедших обновление протокола ALPN или перехваченных соединений. Эта функция должна запустить корректное завершение работы, специфичное для протокола, но не должна ожидать его окончания.
func (*Server) Serve
func (s *Server) Serve(l net.Listener) error
Serve принимает входящие подключения через Listener l, создавая для каждого из них новую служебную горутину. Служебные горутины считывают запросы, а затем вызывают s.Handler для отправки ответов.
Поддержка HTTP/2 включается только в том случае, если Listener возвращает соединения *tls.Conn и они настроены с "h2" в TLS Config.NextProtos.
Serve всегда возвращает ненулевую ошибку и закрывает l. После вызова Server.Shutdown или Server.Close возвращается ошибка ErrServerClosed.
func (*Server) ServeTLS 1.9
func (s *Server) ServeTLS(l net.Listener, certFile, keyFile string) error
ServeTLS принимает входящие подключения через Listener l, создавая для каждого из них новую служебную горутину. Служебные горутины выполняют настройку TLS, а затем считывают запросы и вызывают s.Handler для отправки ответов.
Если ни TLSConfig.Certificates, ни TLSConfig.GetCertificate объекта Server, ни config.GetConfigForClient не заполнены, необходимо предоставить файлы, содержащие сертификат сервера и соответствующий закрытый ключ. Если сертификат подписан центром сертификации, certFile должен содержать объединённые сертификат сервера, все промежуточные сертификаты и сертификат центра сертификации.
ServeTLS всегда возвращает ненулевую ошибку. После вызова Server.Shutdown или Server.Close возвращается ошибка ErrServerClosed.
func (*Server) SetKeepAlivesEnabled 1.3
func (s *Server) SetKeepAlivesEnabled(v bool)
SetKeepAlivesEnabled управляет включением HTTP keep-alive. По умолчанию keep-alive всегда включён. Отключать его следует только в средах с очень ограниченными ресурсами или на серверах, завершающих работу.
func (*Server) Shutdown 1.8
func (s *Server) Shutdown(ctx context.Context) error
Shutdown корректно завершает работу сервера, не прерывая активные соединения. Сначала Shutdown закрывает все открытые слушатели, затем закрывает все простаивающие соединения, а после этого неограниченно долго ждёт, пока соединения перейдут в состояние ожидания и затем завершат работу. Если срок действия переданного контекста истекает до завершения работы, Shutdown возвращает ошибку контекста; в противном случае он возвращает ошибки, возникшие при закрытии базовых Listener(s) объекта Server.
При вызове Shutdown функции Serve, ServeTLS, ListenAndServe и ListenAndServeTLS немедленно возвращают ErrServerClosed. Убедитесь, что программа не завершается и вместо этого ожидает возврата Shutdown.
Shutdown не пытается закрывать перехваченные соединения, например WebSocket, и не ожидает их закрытия. При необходимости вызывающий Shutdown должен отдельно уведомить такие долгоживущие соединения о завершении работы и дождаться их закрытия. Способ регистрации функций уведомления о завершении работы см. в описании Server.RegisterOnShutdown.
После вызова Shutdown для сервера его нельзя использовать повторно; последующие вызовы таких методов, как Serve, будут возвращать ErrServerClosed.
Пример
Код:
var srv http.Server
idleConnsClosed := make(chan struct{})
go func() {
sigint := make(chan os.Signal, 1)
signal.Notify(sigint, os.Interrupt)
<-sigint
// We received an interrupt signal, shut down.
if err := srv.Shutdown(context.Background()); err != nil {
// Error from closing listeners, or context timeout:
log.Printf("HTTP server Shutdown: %v", err)
}
close(idleConnsClosed)
}()
if err := srv.ListenAndServe(); err != http.ErrServerClosed {
// Error starting or closing listener:
log.Fatalf("HTTP server ListenAndServe: %v", err)
}
<-idleConnsClosed
type Transport
Transport — это реализация RoundTripper, поддерживающая HTTP, HTTPS и HTTP-прокси (как для HTTP, так и для HTTPS с CONNECT).
По умолчанию Transport кэширует соединения для повторного использования. При обращении ко множеству хостов это может привести к тому, что останется открыто много соединений. Этим поведением можно управлять с помощью метода Transport.CloseIdleConnections и полей Transport.MaxIdleConnsPerHost и Transport.DisableKeepAlives.
Transport следует повторно использовать, а не создавать по мере необходимости. Экземпляры Transport безопасно использовать одновременно из нескольких горутин.
Transport — низкоуровневый примитив для выполнения HTTP- и HTTPS-запросов. Функции более высокого уровня, например работа с cookie и перенаправлениями, предоставляет Client.
Для URL HTTP Transport использует HTTP/1.1, а для URL HTTPS — HTTP/1.1 или HTTP/2 в зависимости от поддержки HTTP/2 сервером и конфигурации Transport. DefaultTransport поддерживает HTTP/2. Чтобы явно включить HTTP/2 для транспорта, задайте Transport.Protocols.
Ответы с кодами состояния в диапазоне 1xx либо обрабатываются автоматически (100 expect-continue), либо игнорируются. Исключение — код состояния HTTP 101 (Switching Protocols), который считается окончательным статусом и возвращается методом Transport.RoundTrip. Чтобы просматривать игнорируемые ответы 1xx, используйте ClientTrace.Got1xxResponse из пакета трассировки httptrace.
Transport повторяет запрос только при возникновении сетевой ошибки, если соединение уже было успешно использовано, запрос является идемпотентным и либо не имеет тела, либо для него определён Request.GetBody. HTTP-запросы считаются идемпотентными, если в них используются методы GET, HEAD, OPTIONS или TRACE либо если их карта Header содержит запись "Idempotency-Key" или "X-Idempotency-Key". Если значение ключа идемпотентности представляет собой срез нулевой длины, запрос считается идемпотентным, но заголовок не передаётся по сети.
type Transport struct {
// Proxy specifies a function to return a proxy for a given
// Request. If the function returns a non-nil error, the
// request is aborted with the provided error.
//
// The proxy type is determined by the URL scheme. "http",
// "https", "socks5", and "socks5h" are supported. If the scheme is empty,
// "http" is assumed.
// "socks5" is treated the same as "socks5h".
//
// If the proxy URL contains a userinfo subcomponent,
// the proxy request will pass the username and password
// in a Proxy-Authorization header.
//
// If Proxy is nil or returns a nil *URL, no proxy is used.
Proxy func(*Request) (*url.URL, error)
// OnProxyConnectResponse is called when the Transport gets an HTTP response from
// a proxy for a CONNECT request. It's called before the check for a 200 OK response.
// If it returns an error, the request fails with that error.
OnProxyConnectResponse func(ctx context.Context, proxyURL *url.URL, connectReq *Request, connectRes *Response) error // Go 1.20
// DialContext specifies the dial function for creating unencrypted TCP connections.
// If DialContext is nil (and the deprecated Dial below is also nil),
// then the transport dials using package net.
//
// DialContext runs concurrently with calls to RoundTrip.
// A RoundTrip call that initiates a dial may end up using
// a connection dialed previously when the earlier connection
// becomes idle before the later DialContext completes.
DialContext func(ctx context.Context, network, addr string) (net.Conn, error) // Go 1.7
// Dial specifies the dial function for creating unencrypted TCP connections.
//
// Dial runs concurrently with calls to RoundTrip.
// A RoundTrip call that initiates a dial may end up using
// a connection dialed previously when the earlier connection
// becomes idle before the later Dial completes.
//
// Deprecated: Use DialContext instead, which allows the transport
// to cancel dials as soon as they are no longer needed.
// If both are set, DialContext takes priority.
Dial func(network, addr string) (net.Conn, error)
// DialTLSContext specifies an optional dial function for creating
// TLS connections for non-proxied HTTPS requests.
//
// If DialTLSContext is nil (and the deprecated DialTLS below is also nil),
// DialContext and TLSClientConfig are used.
//
// If DialTLSContext is set, the Dial and DialContext hooks are not used for HTTPS
// requests and the TLSClientConfig and TLSHandshakeTimeout
// are ignored. The returned net.Conn is assumed to already be
// past the TLS handshake.
//
// To support ALPN protocol negotiation, the returned net.Conn should be
// a *tls.Conn or implement the same ConnectionState method as *tls.Conn.
DialTLSContext func(ctx context.Context, network, addr string) (net.Conn, error) // Go 1.14
// DialTLS specifies an optional dial function for creating
// TLS connections for non-proxied HTTPS requests.
//
// Deprecated: Use DialTLSContext instead, which allows the transport
// to cancel dials as soon as they are no longer needed.
// If both are set, DialTLSContext takes priority.
DialTLS func(network, addr string) (net.Conn, error) // Go 1.4
// TLSClientConfig specifies the TLS configuration to use with
// tls.Client.
// If nil, the default configuration is used.
// If non-nil, HTTP/2 support may not be enabled by default.
TLSClientConfig *tls.Config
// TLSHandshakeTimeout specifies the maximum amount of time to
// wait for a TLS handshake. Zero means no timeout.
TLSHandshakeTimeout time.Duration // Go 1.3
// DisableKeepAlives, if true, disables HTTP keep-alives and
// will only use the connection to the server for a single
// HTTP request.
//
// This is unrelated to the similarly named TCP keep-alives.
DisableKeepAlives bool
// DisableCompression, if true, prevents the Transport from
// requesting compression with an "Accept-Encoding: gzip"
// request header when the Request contains no existing
// Accept-Encoding value. If the Transport requests gzip on
// its own and gets a gzipped response, it's transparently
// decoded in the Response.Body. However, if the user
// explicitly requested gzip it is not automatically
// uncompressed.
DisableCompression bool
// MaxIdleConns controls the maximum number of idle (keep-alive)
// connections across all hosts. Zero means no limit.
MaxIdleConns int // Go 1.7
// MaxIdleConnsPerHost, if non-zero, controls the maximum idle
// (keep-alive) connections to keep per-host. If zero,
// DefaultMaxIdleConnsPerHost is used.
MaxIdleConnsPerHost int
// MaxConnsPerHost optionally limits the total number of
// connections per host, including connections in the dialing,
// active, and idle states. On limit violation, dials will block.
//
// Zero means no limit.
MaxConnsPerHost int // Go 1.11
// IdleConnTimeout is the maximum amount of time an idle
// (keep-alive) connection will remain idle before closing
// itself.
// Zero means no limit.
IdleConnTimeout time.Duration // Go 1.7
// ResponseHeaderTimeout, if non-zero, specifies the amount of
// time to wait for a server's response headers after fully
// writing the request (including its body, if any). This
// time does not include the time to read the response body.
ResponseHeaderTimeout time.Duration // Go 1.1
// ExpectContinueTimeout, if non-zero, specifies the amount of
// time to wait for a server's first response headers after fully
// writing the request headers if the request has an
// "Expect: 100-continue" header. Zero means no timeout and
// causes the body to be sent immediately, without
// waiting for the server to approve.
// This time does not include the time to send the request header.
ExpectContinueTimeout time.Duration // Go 1.6
// TLSNextProto specifies how the Transport switches to an
// alternate protocol (such as HTTP/2) after a TLS ALPN
// protocol negotiation. If Transport dials a TLS connection
// with a non-empty protocol name and TLSNextProto contains a
// map entry for that key (such as "h2"), then the func is
// called with the request's authority (such as "example.com"
// or "example.com:1234") and the TLS connection. The function
// must return a RoundTripper that then handles the request.
// If TLSNextProto is not nil, HTTP/2 support is not enabled
// automatically.
//
// Historically, TLSNextProto was used to disable HTTP/2 support.
// The Transport.Protocols field now provides a simpler way to do this.
TLSNextProto map[string]func(authority string, c *tls.Conn) RoundTripper // Go 1.6
// ProxyConnectHeader optionally specifies headers to send to
// proxies during CONNECT requests.
// To set the header dynamically, see GetProxyConnectHeader.
ProxyConnectHeader Header // Go 1.8
// GetProxyConnectHeader optionally specifies a func to return
// headers to send to proxyURL during a CONNECT request to the
// ip:port target.
// If it returns an error, the Transport's RoundTrip fails with
// that error. It can return (nil, nil) to not add headers.
// If GetProxyConnectHeader is non-nil, ProxyConnectHeader is
// ignored.
GetProxyConnectHeader func(ctx context.Context, proxyURL *url.URL, target string) (Header, error) // Go 1.16
// MaxResponseHeaderBytes specifies a limit on how many
// response bytes are allowed in the server's response
// header.
//
// Zero means to use a default limit.
MaxResponseHeaderBytes int64 // Go 1.7
// WriteBufferSize specifies the size of the write buffer used
// when writing to the transport.
// If zero, a default (currently 4KB) is used.
WriteBufferSize int // Go 1.13
// ReadBufferSize specifies the size of the read buffer used
// when reading from the transport.
// If zero, a default (currently 4KB) is used.
ReadBufferSize int // Go 1.13
// ForceAttemptHTTP2 controls whether HTTP/2 is enabled when a non-zero
// Dial, DialTLS, or DialContext func or TLSClientConfig is provided.
// By default, use of any those fields conservatively disables HTTP/2.
// To use a custom dialer or TLS config and still attempt HTTP/2
// upgrades, set this to true.
ForceAttemptHTTP2 bool // Go 1.13
// HTTP2 configures HTTP/2 connections.
HTTP2 *HTTP2Config // Go 1.24
// Protocols is the set of protocols supported by the transport.
//
// If Protocols includes UnencryptedHTTP2 and does not include HTTP1,
// the transport will use unencrypted HTTP/2 for requests for http:// URLs.
//
// If Protocols is nil, the default is usually HTTP/1 only.
// If ForceAttemptHTTP2 is true, or if TLSNextProto contains an "h2" entry,
// the default is HTTP/1 and HTTP/2.
Protocols *Protocols // Go 1.24
// contains filtered or unexported fields
}
func (*Transport) CancelRequest 1.1
func (t *Transport) CancelRequest(req *Request)
CancelRequest отменяет выполняющийся запрос, закрывая его соединение. CancelRequest следует вызывать только после возврата Transport.RoundTrip.
Устарело: вместо этого используйте Request.WithContext, чтобы создать запрос с отменяемым контекстом. CancelRequest не может отменять запросы HTTP/2. В будущих версиях Go этот метод может стать пустой операцией.
func (*Transport) Clone 1.13
func (t *Transport) Clone() *Transport
Clone возвращает глубокую копию экспортируемых полей t.
func (*Transport) CloseIdleConnections
func (t *Transport) CloseIdleConnections()
CloseIdleConnections закрывает соединения, ранее использовавшиеся в предыдущих запросах, но теперь находящиеся в состоянии ожидания keep-alive. Он не прерывает соединения, которые в данный момент используются.
func (*Transport) NewClientConn 1.26
func (t *Transport) NewClientConn(ctx context.Context, scheme, address string) (*ClientConn, error)
NewClientConn создаёт новое клиентское соединение с заданным адресом.
Если схема — "http", соединение не шифруется. Если схема — "https", соединение использует TLS.
Протокол для нового соединения определяется схемой, полем конфигурации Transport.Protocols и протоколами, поддерживаемыми сервером. Дополнительные сведения см. в описании Transport.Protocols.
Если задан Transport.Proxy и он указывает, что для запроса к заданному адресу следует использовать прокси, новое соединение использует этот прокси.
NewClientConn всегда создаёт новое соединение, даже если у Transport уже есть кэшированное соединение с заданным хостом.
Новое соединение не добавляется в кэш соединений Transport и не будет использоваться методом Transport.RoundTrip. Оно не учитывается при проверке ограничений MaxIdleConns и MaxConnsPerHost.
Вызывающий код отвечает за закрытие нового соединения.
func (*Transport) RegisterProtocol
func (t *Transport) RegisterProtocol(scheme string, rt RoundTripper)
RegisterProtocol регистрирует новый протокол для схемы. Transport будет передавать запросы с указанной схемой в rt. rt отвечает за имитацию семантики HTTP-запросов.
Другие пакеты могут использовать RegisterProtocol для реализации протоколов, таких как "ftp" или "file".
Если rt.RoundTrip возвращает ErrSkipAltProtocol, Transport самостоятельно обработает этот запрос с помощью Transport.RoundTrip, как если бы протокол не был зарегистрирован.
func (*Transport) RoundTrip
func (t *Transport) RoundTrip(req *Request) (*Response, error)
RoundTrip реализует интерфейс RoundTripper.
Сведения о клиенте HTTP более высокого уровня (например, об обработке cookie и перенаправлений) см. в описаниях Get, Post и типа Client.
Как и для интерфейса RoundTripper, типы ошибок, возвращаемых RoundTrip, не определены.
Подкаталоги
| Имя | Краткое описание |
|---|---|
| .. | |
| cgi | Пакет cgi реализует CGI (Common Gateway Interface), определённый в RFC 3875. |
| cookiejar | Пакет cookiejar реализует соответствующий [RFC 6265] [http.CookieJar] в памяти. |
| fcgi | Пакет fcgi реализует протокол FastCGI. |
| httptest | Пакет httptest предоставляет средства для тестирования HTTP. |
| httptrace | Пакет httptrace предоставляет средства для трассировки событий в запросах HTTP-клиента. |
| httputil | Пакет httputil предоставляет вспомогательные функции для HTTP, дополняющие более распространённые функции пакета net/http. |
| pprof | Пакет pprof предоставляет через свой HTTP-сервер данные профилирования среды выполнения в формате, ожидаемом инструментом визуализации pprof. |
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/net/http/
