<span class="comment">// Background возвращает пустой Context. Он никогда не отменяется, не имеет дедлайна,</span>
<span class="comment">// и не содержит значений. Background обычно используется в main, init и тестах,</span>
<span class="comment">// а также как корневой Context для входящих запросов.</span>
func Background() Context

<span class="comment">// WithCancel возвращает копию parent, канал Done которого закрывается как только</span>
<span class="comment">// parent.Done закрывается или вызывается cancel.</span>
func WithCancel(parent Context) (ctx Context, cancel CancelFunc)
<span class="comment">// CancelFunc отменяет Context.</span>
type CancelFunc func()
<span class="comment">// WithTimeout возвращает копию parent, канал Done которого закрывается как только</span>
<span class="comment">// parent.Done закрывается, cancel вызывается, или истекает таймаут. Новый</span>
<span class="comment">// Context получает дедлайн, который является более ранним из now+timeout и дедлайна родителя,</span>
<span class="comment">// если таковой имеется. Если таймер все еще работает, функция cancel освобождает</span>
<span class="comment">// свои ресурсы.</span>
func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc)

<span class="comment">// WithValue возвращает копию parent, метод Value которого возвращает val для key.</span>
func WithValue(parent Context, key interface{}, val interface{}) Context

func handleSearch(w http.ResponseWriter, req *http.Request) {
  <span class="comment">// ctx — это Context для данного обработчика. Вызов cancel закрывает</span>
  <span class="comment">// канал ctx.Done, который служит сигналом отмены для запросов,</span>
  <span class="comment">// запущенных этим обработчиком.</span>
  var (
    ctx    context.Context
    cancel context.CancelFunc
  )
  timeout, err := time.ParseDuration(req.FormValue("timeout"))
  if err == nil {
    <span class="comment">// Запрос содержит таймаут, поэтому создаётся контекст,</span>
    <span class="comment">// который автоматически отменяется по истечении времени.</span>
    ctx, cancel = context.WithTimeout(context.Background(), timeout)
  } else {
    ctx, cancel = context.WithCancel(context.Background())
  }
  defer cancel() <span class="comment">// Отменить ctx как только handleSearch завершится.</span>

<span class="comment">// Проверить поисковый запрос.</span>
query := req.FormValue("q")
if query == "" {
  http.Error(w, "no query", http.StatusBadRequest)
  return
}
<span class="comment">// Сохранить IP пользователя в ctx для использования кодом в других пакетах.</span>
userIP, err := userip.FromRequest(req)
if err != nil {
  http.Error(w, err.Error(), http.StatusBadRequest)
  return
}
ctx = userip.NewContext(ctx, userIP)

<span class="comment">// Запустить поиск в Google и вывести результаты.</span>
start := time.Now()
results, err := google.Search(ctx, query)
elapsed := time.Since(start)

if err := resultsTemplate.Execute(w, struct {
  Results          google.Results
  Timeout, Elapsed time.Duration
}{
  Results: results,
  Timeout: timeout,
  Elapsed: elapsed,
}); err != nil {
  log.Print(err)
  return
}

<span class="comment">// Тип ключа не экспортируется, чтобы предотвратить конфликты с ключами контекста, определёнными в</span>
<span class="comment">// других пакетах.</span>
type key int
<span class="comment">// userIPkey — это ключ контекста для IP-адреса пользователя. Его значение равно нулю,</span>
<span class="comment">// что является произвольным. Если бы этот пакет определял другие ключи контекста,</span>
<span class="comment">// они имели бы разные целочисленные значения.</span>
const userIPKey key = 0

func FromRequest(req *http.Request) (net.IP, error) {
  ip, _, err := net.SplitHostPort(req.RemoteAddr)
  if err != nil {
    return nil, fmt.Errorf("userip: %q is not IP:port", req.RemoteAddr)
  }

func NewContext(ctx context.Context, userIP net.IP) context.Context {
  return context.WithValue(ctx, userIPKey, userIP)
}

func FromContext(ctx context.Context) (net.IP, bool) {
  <span class="comment">// ctx.Value возвращает nil, если в ctx нет значения для ключа;</span>
  <span class="comment">// утверждение типа net.IP возвращает ok=false для nil.</span>
  userIP, ok := ctx.Value(userIPKey).(net.IP)
  return userIP, ok
}

func Search(ctx context.Context, query string) (Results, error) {
  <span class="comment">// Подготовить запрос к Google Search API.</span>
  req, err := http.NewRequest("GET", "https://ajax.googleapis.com/ajax/services/search/web?v=1.0", nil)
  if err != nil {
    return nil, err
  }
  q := req.URL.Query()
  q.Set("q", query)
  <span class="comment">// Если ctx содержит IP-адрес пользователя, передать его серверу.</span>
  <span class="comment">// Google APIs используют IP-адрес пользователя, чтобы отличать запросы, инициированные сервером,</span>
  <span class="comment">// от запросов конечного пользователя.</span>
  if userIP, ok := userip.FromContext(ctx); ok {
    q.Set("userip", userIP.String())
  }
  req.URL.RawQuery = q.Encode()

var results Results
err = httpDo(ctx, req, func(resp *http.Response, err error) error {
  if err != nil {
    return err
  }
  defer resp.Body.Close()
  <span class="comment">// Разобрать результаты поиска в формате JSON.</span>
  <span class="comment">// https://developers.google.com/web-search/docs/#fonje</span>
  var data struct {
    ResponseData struct {
      Results []struct {
        TitleNoFormatting string
        URL               string
      }
    }
  }
  if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
    return err
  }
  for _, res := range data.ResponseData.Results {
    results = append(results, Result{Title: res.TitleNoFormatting, URL: res.URL})
  }
  return nil
})
<span class="comment">// httpDo ожидает, пока замыкание, переданное нами, завершится, поэтому безопасно</span>
<span class="comment">// читать results здесь.</span>
return results, err

func httpDo(ctx context.Context, req *http.Request, f func(*http.Response, error) error) error {
  <span class="comment">// Выполнить HTTP-запрос в горутине и передать ответ в f.</span>
  c := make(chan error, 1)
  req = req.WithContext(ctx)
  go func() { c <- f(http.DefaultClient.Do(req)) }()
  select {
    case <-ctx.Done():
      <-c <span class="comment">// Дождаться завершения f.</span>
      return ctx.Err()
      case err := <-c:
        return err
      }
    }