github.com/shogo82148/std@v1.22.1-0.20240327122250-4e474527810c/cmd/go/internal/web/api.go (about)

     1  // Copyright 2017 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package web defines minimal helper routines for accessing HTTP/HTTPS
     6  // resources without requiring external dependencies on the net package.
     7  //
     8  // If the cmd_go_bootstrap build tag is present, web avoids the use of the net
     9  // package and returns errors for all network operations.
    10  package web
    11  
    12  import (
    13  	"github.com/shogo82148/std/io"
    14  	"github.com/shogo82148/std/net/url"
    15  )
    16  
    17  // SecurityMode specifies whether a function should make network
    18  // calls using insecure transports (eg, plain text HTTP).
    19  // The zero value is "secure".
    20  type SecurityMode int
    21  
    22  const (
    23  	SecureOnly SecurityMode = iota
    24  	DefaultSecurity
    25  	Insecure
    26  )
    27  
    28  // An HTTPError describes an HTTP error response (non-200 result).
    29  type HTTPError struct {
    30  	URL        string
    31  	Status     string
    32  	StatusCode int
    33  	Err        error
    34  	Detail     string
    35  }
    36  
    37  func (e *HTTPError) Error() string
    38  
    39  func (e *HTTPError) Is(target error) bool
    40  
    41  func (e *HTTPError) Unwrap() error
    42  
    43  // GetBytes returns the body of the requested resource, or an error if the
    44  // response status was not http.StatusOK.
    45  //
    46  // GetBytes is a convenience wrapper around Get and Response.Err.
    47  func GetBytes(u *url.URL) ([]byte, error)
    48  
    49  type Response struct {
    50  	URL        string
    51  	Status     string
    52  	StatusCode int
    53  	Header     map[string][]string
    54  	Body       io.ReadCloser
    55  
    56  	fileErr     error
    57  	errorDetail errorDetailBuffer
    58  }
    59  
    60  // Err returns an *HTTPError corresponding to the response r.
    61  // If the response r has StatusCode 200 or 0 (unset), Err returns nil.
    62  // Otherwise, Err may read from r.Body in order to extract relevant error detail.
    63  func (r *Response) Err() error
    64  
    65  // Get returns the body of the HTTP or HTTPS resource specified at the given URL.
    66  //
    67  // If the URL does not include an explicit scheme, Get first tries "https".
    68  // If the server does not respond under that scheme and the security mode is
    69  // Insecure, Get then tries "http".
    70  // The URL included in the response indicates which scheme was actually used,
    71  // and it is a redacted URL suitable for use in error messages.
    72  //
    73  // For the "https" scheme only, credentials are attached using the
    74  // cmd/go/internal/auth package. If the URL itself includes a username and
    75  // password, it will not be attempted under the "http" scheme unless the
    76  // security mode is Insecure.
    77  //
    78  // Get returns a non-nil error only if the request did not receive a response
    79  // under any applicable scheme. (A non-2xx response does not cause an error.)
    80  func Get(security SecurityMode, u *url.URL) (*Response, error)
    81  
    82  // OpenBrowser attempts to open the requested URL in a web browser.
    83  func OpenBrowser(url string) (opened bool)
    84  
    85  // Join returns the result of adding the slash-separated
    86  // path elements to the end of u's path.
    87  func Join(u *url.URL, path string) *url.URL
    88  
    89  // IsLocalHost reports whether the given URL refers to a local
    90  // (loopback) host, such as "localhost" or "127.0.0.1:8080".
    91  func IsLocalHost(u *url.URL) bool