Import Debian changes 1.64.0-6

.github/ISSUE_TEMPLATE/bug.md

 ---
 name: Bug Report
-about: Create a report to help us improve
+about: Report a non-security bug.  For suspected security vulnerabilities or crashes, please use "Report a Security Vulnerability", below.
 labels: 'Type: Bug'
 
 ---
 
-Please see the FAQ in our main README.md, then answer the questions below before
-submitting your issue.
+NOTE: if you are reporting is a potential security vulnerability or a crash,
+please follow our CVE process at
+https://github.com/grpc/proposal/blob/master/P4-grpc-cve-process.md instead of
+filing an issue here.
+
+Please see the FAQ in our main README.md, then answer the questions below
+before submitting your issue.
 
 ### What version of gRPC are you using?
 

.github/codecov.yml

+coverage:
+  status:
+    project:
+      default:
+        informational: true
+    patch:
+      default:
+        informational: true
+ignore:
+  # All 'pb.go's.
+  - "**/*.pb.go"
+  # Tests and test related files.
+  - "**/test"
+  - "**/testdata"
+  - "**/testutils"
+  - "benchmark"
+  - "interop"
+  # Other submodules.
+  - "cmd"
+  - "examples"
+  - "gcp"
+  - "security"
+  - "stats/opencensus"
+comment:
+  layout: "header, diff, files"

.github/lock.yml

-daysUntilLock: 180
-lockComment: false

.github/mergeable.yml

@@ -5,32 +5,17 @@ mergeable:
       - do: label
         must_include:
           regex: '^Type:'
-    fail:
-      - do: checks
-        status: 'failure'
-        payload:
-          title: 'Need an appropriate "Type:" label'
-          summary: 'Need an appropriate "Type:" label'
-  - when: pull_request.*
-    # This validator requires either the "no release notes" label OR a "Release" milestone
-    # to be considered successful.  However, validators "pass" in mergeable only if all
-    # checks pass.  So it is implemented in reverse.
-    # I.e.: !(!no_relnotes && !release_milestone) ==> no_relnotes || release_milestone
-    # If both validators pass, then it is considered a failure, and if either fails, it is
-    # considered a success.
-    validate:
-      - do: label
-        must_exclude:
-          regex: '^no release notes$'
+      - do: description
+        must_include:
+          # Allow:
+          # RELEASE NOTES: none (case insensitive)
+          #
+          # RELEASE NOTES: N/A (case insensitive)
+          #
+          # RELEASE NOTES:
+          # * <text>
+          regex: '^RELEASE NOTES:\s*([Nn][Oo][Nn][Ee]|[Nn]/[Aa]|\n(\*|-)\s*.+)$'
+          regex_flag: 'm'
       - do: milestone
-        must_exclude:
+        must_include:
           regex: 'Release$'
-    pass:
-      - do: checks
-        status: 'failure'  # fail on pass
-        payload:
-          title: 'Need Release milestone or "no release notes" label'
-          summary: 'Need Release milestone or "no release notes" label'
-    fail:
-      - do: checks
-        status: 'success' # pass on fail

.github/stale.yml

-# Configuration for probot-stale - https://github.com/probot/stale
-
-# Number of days of inactivity before an Issue or Pull Request becomes stale
-daysUntilStale: 6
-
-# Number of days of inactivity before an Issue or Pull Request with the stale label is closed.
-# Set to false to disable. If disabled, issues still need to be closed manually, but will remain marked as stale.
-daysUntilClose: 7
-
-# Only issues or pull requests with all of these labels are check if stale. Defaults to `[]` (disabled)
-onlyLabels:
-  - "Status: Requires Reporter Clarification"
-
-# Issues or Pull Requests with these labels will never be considered stale. Set to `[]` to disable
-exemptLabels: []
-
-# Set to true to ignore issues in a project (defaults to false)
-exemptProjects: false
-
-# Set to true to ignore issues in a milestone (defaults to false)
-exemptMilestones: false
-
-# Set to true to ignore issues with an assignee (defaults to false)
-exemptAssignees: false
-
-# Label to use when marking as stale
-staleLabel: "stale"
-
-# Comment to post when marking as stale. Set to `false` to disable
-markComment: >
-  This issue is labeled as requiring an update from the reporter, and no update has been received
-  after 6 days.  If no update is provided in the next 7 days, this issue will be automatically closed.
-
-# Comment to post when removing the stale label.
-# unmarkComment: >
-#   Your comment here.
-
-# Comment to post when closing a stale Issue or Pull Request.
-# closeComment: >
-#   Your comment here.
-
-# Limit the number of actions per hour, from 1-30. Default is 30
-limitPerRun: 1
-
-# Limit to only `issues` or `pulls`
-# only: issues
-
-# Optionally, specify configuration settings that are specific to just 'issues' or 'pulls':
-# pulls:
-#   daysUntilStale: 30
-#   markComment: >
-#     This pull request has been automatically marked as stale because it has not had
-#     recent activity. It will be closed if no further activity occurs. Thank you
-#     for your contributions.
-
-# issues:
-#   exemptLabels:
-#     - confirmed

.github/workflows/codeql-analysis.yml

+name: "CodeQL"
+
+on:
+  push:
+    branches: [ master ]
+  schedule:
+    - cron: '24 20 * * 3'
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    permissions:
+      security-events: write
+      pull-requests: read
+      actions: read
+
+    strategy:
+      fail-fast: false
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v2
+      with:
+        languages: go
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v2

.github/workflows/coverage.yml

+name: codecov
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  upload:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install checkout
+        uses: actions/checkout@v4
+
+      - name: Install checkout
+        uses: actions/setup-go@v5
+        with:
+          go-version: "stable"
+
+      - name: Run coverage
+        run: go test -coverprofile=coverage.out -coverpkg=./... ./...
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v3

.github/workflows/lock.yml

+name: 'Lock Threads'
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '22 1 * * *'
+
+permissions:
+  contents: read
+
+jobs:
+  lock:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: dessant/lock-threads@v5
+        with:
+          github-token: ${{ github.token }}
+          issue-inactive-days: 180
+          pr-inactive-days: 180

.github/workflows/release.yml

+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    permissions:
+      contents: write # to upload release asset (actions/upload-release-asset)
+
+    name: Release cmd/protoc-gen-go-grpc
+    runs-on: ubuntu-latest
+    if: startsWith(github.event.release.tag_name, 'cmd/protoc-gen-go-grpc/')
+    strategy:
+      matrix:
+        goos: [linux, darwin, windows]
+        goarch: [386, amd64, arm64]
+        exclude:
+          - goos: darwin
+            goarch: 386
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+
+      - name: Download dependencies
+        run: |
+          cd cmd/protoc-gen-go-grpc
+          go mod download
+
+      - name: Prepare build directory
+        run: |
+          mkdir -p build/
+          cp README.md build/
+          cp LICENSE build/
+
+      - name: Build
+        env:
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+        run: |
+          cd cmd/protoc-gen-go-grpc
+          go build -trimpath -o $GITHUB_WORKSPACE/build
+
+      - name: Create package
+        id: package
+        run: |
+          PACKAGE_NAME=protoc-gen-go-grpc.${GITHUB_REF#refs/tags/cmd/protoc-gen-go-grpc/}.${{ matrix.goos }}.${{ matrix.goarch }}.tar.gz
+          tar -czvf $PACKAGE_NAME -C build .
+          echo "name=${PACKAGE_NAME}" >> $GITHUB_OUTPUT
+
+      - name: Upload asset
+        uses: actions/upload-release-asset@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          upload_url: ${{ github.event.release.upload_url }}
+          asset_path: ./${{ steps.package.outputs.name }}
+          asset_name: ${{ steps.package.outputs.name }}
+          asset_content_type: application/gzip

.github/workflows/stale.yml

+name: Stale bot
+
+on:
+  workflow_dispatch:
+  schedule:
+  - cron: "44 */2 * * *"
+
+permissions:
+  contents: read
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+
+    steps:
+    - uses: actions/stale@v8
+      with:
+        repo-token: ${{ secrets.GITHUB_TOKEN }}
+        days-before-stale: 6
+        days-before-close: 7
+        only-labels: 'Status: Requires Reporter Clarification'
+        stale-issue-label: 'stale'
+        stale-pr-label: 'stale'
+        operations-per-run: 999
+        stale-issue-message: >
+          This issue is labeled as requiring an update from the reporter, and no update has been received
+          after 6 days.  If no update is provided in the next 7 days, this issue will be automatically closed.
+        stale-pr-message: >
+          This PR is labeled as requiring an update from the reporter, and no update has been received
+          after 6 days.  If no update is provided in the next 7 days, this issue will be automatically closed.

.github/workflows/testing.yml

@@ -4,12 +4,12 @@ name: Testing
 on:
   push:
   pull_request:
-    paths-ignore:
-      - 'Documentation/**'
-      - 'version.go'
   schedule:
     - cron: 0 0 * * * # daily at 00:00
 
+permissions:
+  contents: read
+
 # Always force the use of Go modules
 env:
   GO111MODULE: on
@@ -18,79 +18,111 @@ jobs:
   # Check generated protos match their source repos (optional for PRs).
   vet-proto:
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     steps:
       # Setup the environment.
       - name: Setup Go
-        uses: actions/setup-go@v2
+        uses: actions/setup-go@v5
         with:
-          go-version: 1.14
+          go-version: '1.22'
       - name: Checkout repo
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
-      # Run the vet checks.
-      - name: vet
-        run: ./vet.sh -install && ./vet.sh
+      # Run the vet-proto checks.
+      - name: vet-proto
+        run: ./scripts/vet-proto.sh -install && ./scripts/vet-proto.sh
 
   # Run the main gRPC-Go tests.
   tests:
-    # Proto checks are run in the above job.
-    env:
-      VET_SKIP_PROTO: 1
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     strategy:
+      fail-fast: false
       matrix:
         include:
           - type: vet
-            goversion: 1.14
-          - type: race
-            goversion: 1.14
-          - type: 386
-            goversion: 1.14
-          - type: retry
-            goversion: 1.14
+            goversion: '1.22'
+
           - type: extras
-            goversion: 1.14
+            goversion: '1.22'
+
+          - type: tests
+            goversion: '1.22'
+
+          - type: tests
+            goversion: '1.22'
+            testflags: -race
+
           - type: tests
-            goversion: 1.13
+            goversion: '1.22'
+            goarch: 386
+
           - type: tests
-            goversion: 1.12
+            goversion: '1.22'
+            goarch: arm64
+
           - type: tests
-            goversion: 1.11  # Keep until interop tests no longer require Go1.11
+            goversion: '1.21'
 
+          - type: tests
+            goversion: '1.20'
     steps:
       # Setup the environment.
-      - name: Setup GOARCH=386
-        if: ${{ matrix.type == '386' }}
-        run: echo "GOARCH=386" >> $GITHUB_ENV
-      - name: Setup RETRY
-        if: ${{ matrix.type == 'retry' }}
-        run: echo "GRPC_GO_RETRY=on" >> $GITHUB_ENV
+      - name: Setup GOARCH
+        if: matrix.goarch != ''
+        run: echo "GOARCH=${{ matrix.goarch }}" >> $GITHUB_ENV
+
+      - name: Setup qemu emulator
+        if: matrix.goarch == 'arm64'
+        # setup qemu-user-static emulator and register it with binfmt_misc so that aarch64 binaries
+        # are automatically executed using qemu.
+        run: docker run --rm --privileged multiarch/qemu-user-static:5.2.0-2 --reset --credential yes --persistent yes
+
+      - name: Setup GRPC environment
+        if: matrix.grpcenv != ''
+        run: echo "${{ matrix.grpcenv }}" >> $GITHUB_ENV
+
       - name: Setup Go
-        uses: actions/setup-go@v2
+        uses: actions/setup-go@v5
         with:
           go-version: ${{ matrix.goversion }}
+
       - name: Checkout repo
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       # Only run vet for 'vet' runs.
       - name: Run vet.sh
-        if: ${{ matrix.type == 'vet' }}
-        run: ./vet.sh -install && ./vet.sh
+        if: matrix.type == 'vet'
+        run: ./scripts/vet.sh -install && ./scripts/vet.sh
 
-      # Main tests run for everything except when testing "extras" and the race detector.
+      # Main tests run for everything except when testing "extras"
+      # (where we run a reduced set of tests).
       - name: Run tests
-        if: ${{ matrix.type != 'extras' && matrix.type != 'race' }}
-        run: make test
-
-      # Race detector tests
-      - name: Run test race
-        if: ${{ matrix.TYPE == 'race' }}
-        run: make testrace
+        if: matrix.type == 'tests'
+        run: |
+          go version
+          go test ${{ matrix.testflags }} -cpu 1,4 -timeout 7m google.golang.org/grpc/...
+          cd "${GITHUB_WORKSPACE}"
+          for MOD_FILE in $(find . -name 'go.mod' | grep -Ev '^\./go\.mod'); do
+            pushd "$(dirname ${MOD_FILE})"
+            go test ${{ matrix.testflags }} -cpu 1,4 -timeout 2m ./...
+            popd
+          done
 
       # Non-core gRPC tests (examples, interop, etc)
       - name: Run extras tests
-        if: ${{ matrix.TYPE == 'extras' }}
+        if: matrix.type == 'extras'
         run: |
+          export TERM=${TERM:-xterm}
+          go version
+          echo -e "\n-- Running Examples --"
           examples/examples_test.sh
+          echo -e "\n-- Running AdvancedTLS Examples --"
+          security/advancedtls/examples/examples_test.sh
+          echo -e "\n-- Running Interop Test --"
           interop/interop_test.sh
-          make testsubmodule
+          echo -e "\n-- Running xDS E2E Test --"
+          xds/internal/test/e2e/run.sh
+          echo -e "\n-- Running protoc-gen-go-grpc test --"
+          ./scripts/vet-proto.sh -install
+          cmd/protoc-gen-go-grpc/protoc-gen-go-grpc_test.sh

.travis.yml

-language: go
-
-matrix:
-  include:
-  - go: 1.14.x
-    env: VET=1 GO111MODULE=on
-  - go: 1.14.x
-    env: RACE=1 GO111MODULE=on
-  - go: 1.14.x
-    env: RUN386=1
-  - go: 1.14.x
-    env: GRPC_GO_RETRY=on
-  - go: 1.14.x
-    env: TESTEXTRAS=1
-  - go: 1.13.x
-    env: GO111MODULE=on
-  - go: 1.12.x
-    env: GO111MODULE=on
-  - go: 1.11.x  # Keep until interop tests no longer require Go1.11
-    env: GO111MODULE=on
-
-go_import_path: google.golang.org/grpc
-
-before_install:
-  - if [[ "${GO111MODULE}" = "on" ]]; then mkdir "${HOME}/go"; export GOPATH="${HOME}/go"; fi
-  - if [[ -n "${RUN386}" ]]; then export GOARCH=386; fi
-  - if [[ "${TRAVIS_EVENT_TYPE}" = "cron" && -z "${RUN386}" ]]; then RACE=1; fi
-  - if [[ "${TRAVIS_EVENT_TYPE}" != "cron" ]]; then export VET_SKIP_PROTO=1; fi
-
-install:
-  - try3() { eval "$*" || eval "$*" || eval "$*"; }
-  - try3 'if [[ "${GO111MODULE}" = "on" ]]; then go mod download; else make testdeps; fi'
-  - if [[ -n "${GAE}" ]]; then source ./install_gae.sh; make testappenginedeps; fi
-  - if [[ -n "${VET}" ]]; then ./vet.sh -install; fi
-
-script:
-  - set -e
-  - if [[ -n "${TESTEXTRAS}" ]]; then examples/examples_test.sh; interop/interop_test.sh; make testsubmodule; exit 0; fi
-  - if [[ -n "${VET}" ]]; then ./vet.sh; fi
-  - if [[ -n "${GAE}" ]]; then make testappengine; exit 0; fi
-  - if [[ -n "${RACE}" ]]; then make testrace; exit 0; fi
-  - make test

CONTRIBUTING.md

@@ -20,6 +20,15 @@ How to get your contributions merged smoothly and quickly.
   both author's & review's time is wasted. Create more PRs to address different
   concerns and everyone will be happy.
 
+- If you are searching for features to work on, issues labeled [Status: Help
+  Wanted](https://github.com/grpc/grpc-go/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22Status%3A+Help+Wanted%22)
+  is a great place to start. These issues are well-documented and usually can be
+  resolved with a single pull request.
+
+- If you are adding a new file, make sure it has the copyright message template 
+  at the top as a comment. You can copy over the message from an existing file 
+  and update the year.
+
 - The grpc package should only depend on standard Go packages and a small number
   of exceptions. If your contribution introduces new dependencies which are NOT
   in the [list](https://godoc.org/google.golang.org/grpc?imports), you need a
@@ -32,14 +41,18 @@ How to get your contributions merged smoothly and quickly.
 - Provide a good **PR description** as a record of **what** change is being made
   and **why** it was made. Link to a github issue if it exists.
 
-- Don't fix code style and formatting unless you are already changing that line
-  to address an issue. PRs with irrelevant changes won't be merged. If you do
-  want to fix formatting or style, do that in a separate PR.
+- If you want to fix formatting or style, consider whether your changes are an 
+  obvious improvement or might be considered a personal preference. If a style 
+  change is based on preference, it likely will not be accepted. If it corrects 
+  widely agreed-upon anti-patterns, then please do create a PR and explain the 
+  benefits of the change.
 
 - Unless your PR is trivial, you should expect there will be reviewer comments
-  that you'll need to address before merging. We expect you to be reasonably
-  responsive to those comments, otherwise the PR will be closed after 2-3 weeks
-  of inactivity.
+  that you'll need to address before merging. We'll mark it as `Status: Requires
+  Reporter Clarification` if we expect you to respond to these comments in a
+  timely manner. If the PR remains inactive for 6 days, it will be marked as
+  `stale` and automatically close 7 days after that if we don't hear back from
+  you.
 
 - Maintain **clean commit history** and use **meaningful commit messages**. PRs
   with messy commit history are difficult to review and won't be merged. Use
@@ -53,9 +66,8 @@ How to get your contributions merged smoothly and quickly.
 - **All tests need to be passing** before your change can be merged. We
   recommend you **run tests locally** before creating your PR to catch breakages
   early on.
-  - `make all` to test everything, OR
-  - `make vet` to catch vet errors
-  - `make test` to run the tests
-  - `make testrace` to run tests in race mode
+  - `./scripts/vet.sh` to catch vet errors
+  - `go test -cpu 1,4 -timeout 7m ./...` to run the tests
+  - `go test -race -cpu 1,4 -timeout 7m ./...` to run tests in race mode
 
 - Exceptions to the rules can be made if there's a compelling reason for doing so.

Documentation/anti-patterns.md

+## Anti-Patterns of Client creation
+
+### How to properly create a `ClientConn`: `grpc.NewClient`
+
+[`grpc.NewClient`](https://pkg.go.dev/google.golang.org/grpc#NewClient) is the
+function in the gRPC library that creates a virtual connection from a client
+application to a gRPC server.  It takes a target URI (which represents the name
+of a logical backend service and resolves to one or more physical addresses) and
+a list of options, and returns a
+[`ClientConn`](https://pkg.go.dev/google.golang.org/grpc#ClientConn) object that
+represents the virtual connection to the server.  The `ClientConn` contains one
+or more actual connections to real servers and attempts to maintain these
+connections by automatically reconnecting to them when they break.  `NewClient`
+was introduced in gRPC-Go v1.63.
+
+### The wrong way: `grpc.Dial`
+
+[`grpc.Dial`](https://pkg.go.dev/google.golang.org/grpc#Dial) is a deprecated
+function that also creates the same virtual connection pool as `grpc.NewClient`.
+However, unlike `grpc.NewClient`, it immediately starts connecting and supports
+a few additional `DialOption`s that control this initial connection attempt.
+These are: `WithBlock`, `WithTimeout`, `WithReturnConnectionError`, and
+`FailOnNonTempDialError.
+
+That `grpc.Dial` creates connections immediately is not a problem in and of
+itself, but this behavior differs from how gRPC works in all other languages,
+and it can be convenient to have a constructor that does not perform I/O.  It
+can also be confusing to users, as most people expect a function called `Dial`
+to create _a_ connection which may need to be recreated if it is lost.
+
+`grpc.Dial` uses "passthrough" as the default name resolver for backward
+compatibility while `grpc.NewClient` uses "dns" as its default name resolver.
+This subtle diffrence is important to legacy systems that also specified a
+custom dialer and expected it to receive the target string directly.
+
+For these reasons, using `grpc.Dial` is discouraged.  Even though it is marked
+as deprecated, we will continue to support it until a v2 is released (and no
+plans for a v2 exist at the time this was written).
+
+### Especially bad: using deprecated `DialOptions`
+
+`FailOnNonTempDialError`, `WithBlock`, and `WithReturnConnectionError` are three
+`DialOption`s that are only supported by `Dial` because they only affect the
+behavior of `Dial` itself. `WithBlock` causes `Dial` to wait until the
+`ClientConn` reports its `State` as `connectivity.Connected`.  The other two deal
+with returning connection errors before the timeout (`WithTimeout` or on the
+context when using `DialContext`).
+
+The reason these options can be a problem is that connections with a
+`ClientConn` are dynamic -- they may come and go over time.  If your client
+successfully connects, the server could go down 1 second later, and your RPCs
+will fail.  "Knowing you are connected" does not tell you much in this regard.
+
+Additionally, _all_ RPCs created on an "idle" or a "connecting" `ClientConn`
+will wait until their deadline or until a connection is established before
+failing.  This means that you don't need to check that a `ClientConn` is "ready"
+before starting your RPCs.  By default, RPCs will fail if the `ClientConn`
+enters the "transient failure" state, but setting `WaitForReady(true)` on a
+call will cause it to queue even in the "transient failure" state, and it will
+only ever fail due to a deadline, a server response, or a connection loss after
+the RPC was sent to a server.
+
+Some users of `Dial` use it as a way to validate the configuration of their
+system.  If you wish to maintain this behavior but migrate to `NewClient`, you
+can call `State` and `WaitForStateChange` until the channel is connected.
+However, if this fails, it does not mean that your configuration was bad - it
+could also mean the service is not reachable by the client due to connectivity
+reasons.
+
+## Best practices for error handling in gRPC
+
+Instead of relying on failures at dial time, we strongly encourage developers to
+rely on errors from RPCs.  When a client makes an RPC, it can receive an error
+response from the server.  These errors can provide valuable information about
+what went wrong, including information about network issues, server-side errors,
+and incorrect usage of the gRPC API.
+
+By handling errors from RPCs correctly, developers can write more reliable and
+robust gRPC applications.  Here are some best practices for error handling in
+gRPC:
+
+- Always check for error responses from RPCs and handle them appropriately.
+- Use the `status` field of the error response to determine the type of error
+  that occurred.
+- When retrying failed RPCs, consider using the built-in retry mechanism
+  provided by gRPC-Go, if available, instead of manually implementing retries.
+  Refer to the [gRPC-Go retry example
+  documentation](https://github.com/grpc/grpc-go/blob/master/examples/features/retry/README.md)
+  for more information.  Note that this is not a substitute for client-side
+  retries as errors that occur after an RPC starts on a server cannot be
+  retried through gRPC's built-in mechanism.
+- If making an outgoing RPC from a server handler, be sure to translate the
+  status code before returning the error from your method handler.  For example,
+  if the error is an `INVALID_ARGUMENT` status code, that probably means
+  your service has a bug (otherwise it shouldn't have triggered this error), in
+  which case `INTERNAL` is more appropriate to return back to your users.
+
+### Example: Handling errors from an RPC
+
+The following code snippet demonstrates how to handle errors from an RPC in
+gRPC:
+
+```go
+ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+defer cancel()
+
+res, err := client.MyRPC(ctx, &MyRequest{})
+if err != nil {
+    // Handle the error appropriately,
+    // log it & return an error to the caller, etc.
+    log.Printf("Error calling MyRPC: %v", err)
+    return nil, err
+}
+
+// Use the response as appropriate
+log.Printf("MyRPC response: %v", res)
+```
+
+To determine the type of error that occurred, you can use the status field of
+the error response:
+
+```go
+resp, err := client.MakeRPC(context.TODO(), request)
+if err != nil {
+  if status, ok := status.FromError(err); ok {
+    // Handle the error based on its status code
+    if status.Code() == codes.NotFound {
+      log.Println("Requested resource not found")
+    } else {
+      log.Printf("RPC error: %v", status.Message())
+    }
+  } else {
+    // Handle non-RPC errors
+    log.Printf("Non-RPC error: %v", err)
+  }
+  return
+}
+
+// Use the response as needed
+log.Printf("Response received: %v", resp)
+```
+
+### Example: Using a backoff strategy
+
+When retrying failed RPCs, use a backoff strategy to avoid overwhelming the
+server or exacerbating network issues:
+
+```go
+var res *MyResponse
+var err error
+
+retryableStatusCodes := map[codes.Code]bool{
+  codes.Unavailable: true, // etc
+}
+
+// Retry the RPC a maximum number of times.
+for i := 0; i < maxRetries; i++ {
+    // Make the RPC.
+    res, err = client.MyRPC(context.TODO(), &MyRequest{})
+
+    // Check if the RPC was successful.
+    if !retryableStatusCodes[status.Code(err)] {
+        // The RPC was successful or errored in a non-retryable way;
+        // do not retry.
+        break
+    }
+
+    // The RPC is retryable; wait for a backoff period before retrying.
+    backoff := time.Duration(i+1) * time.Second
+    log.Printf("Error calling MyRPC: %v; retrying in %v", err, backoff)
+    time.Sleep(backoff)
+}
+
+// Check if the RPC was successful after all retries.
+if err != nil {
+    // All retries failed, so handle the error appropriately
+    log.Printf("Error calling MyRPC: %v", err)
+    return nil, err
+}
+
+// Use the response as appropriate.
+log.Printf("MyRPC response: %v", res)
+```

Documentation/encoding.md

@@ -132,7 +132,7 @@ As a reminder, all `CallOption`s may be converted into `DialOption`s that become
 the default for all RPCs sent through a client using `grpc.WithDefaultCallOptions`:
 
 ```go
-	myclient := grpc.Dial(ctx, target, grpc.WithDefaultCallOptions(grpc.UseCompresor("gzip")))
+	myclient := grpc.Dial(ctx, target, grpc.WithDefaultCallOptions(grpc.UseCompressor("gzip")))
 ```
 
 When specified in either of these ways, messages will be compressed using this

Documentation/grpc-auth-support.md

@@ -53,7 +53,7 @@ Alternatively, a client may also use the `grpc.CallOption`
 on each invocation of an RPC.
 
 To create a `credentials.PerRPCCredentials`, use
-[oauth.NewOauthAccess](https://godoc.org/google.golang.org/grpc/credentials/oauth#NewOauthAccess).
+[oauth.TokenSource](https://godoc.org/google.golang.org/grpc/credentials/oauth#TokenSource).
 Note, the OAuth2 implementation of `grpc.PerRPCCredentials` requires a client to use
 [grpc.WithTransportCredentials](https://godoc.org/google.golang.org/grpc#WithTransportCredentials)
 to prevent any insecure transmission of tokens.

Documentation/grpc-metadata.md

@@ -110,9 +110,9 @@ md := metadata.Pairs("k1", "v1", "k1", "v2", "k2", "v3")
 ctx := metadata.NewOutgoingContext(context.Background(), md)
 
 // later, add some more metadata to the context (e.g. in an interceptor)
-md, _ := metadata.FromOutgoingContext(ctx)
+send, _ := metadata.FromOutgoingContext(ctx)
 newMD := metadata.Pairs("k3", "v3")
-ctx = metadata.NewContext(ctx, metadata.Join(metadata.New(send), newMD))
+ctx = metadata.NewOutgoingContext(ctx, metadata.Join(send, newMD))
 
 // make unary RPC
 response, err := client.SomeRPC(ctx, someRequest)
@@ -223,3 +223,8 @@ func (s *server) SomeStreamingRPC(stream pb.Service_SomeStreamingRPCServer) erro
     stream.SetTrailer(trailer)
 }
 ```
+
+## Updating metadata from a server interceptor
+
+An example for updating metadata from a server interceptor is
+available [here](../examples/features/metadata_interceptor/server/main.go).

Documentation/keepalive.md

@@ -8,6 +8,17 @@ activity on the connection.
 For how to configure keepalive, see
 https://godoc.org/google.golang.org/grpc/keepalive for the options.
 
+## Why do I need this?
+
+Keepalive can be useful to detect TCP level connection failures. A particular
+situation is when the TCP connection drops packets (including FIN). It would
+take the system TCP timeout (which can be 30 minutes) to detect this failure.
+Keepalive would allow gRPC to detect this failure much sooner.
+
+Another usage is (as the name suggests) to keep the connection alive. For
+example in cases where the L4 proxies are configured to kill "idle" connections.
+Sending pings would make the connections not "idle".
+
 ## What should I set?
 
 It should be sufficient for most users to set [client

Documentation/proxy.md

 # Proxy
 
 HTTP CONNECT proxies are supported by default in gRPC. The proxy address can be
-specified by the environment variables HTTP_PROXY, HTTPS_PROXY and NO_PROXY (or
-the lowercase versions thereof).
+specified by the environment variables `HTTPS_PROXY` and `NO_PROXY`.  (Note that
+these environment variables are case insensitive.)
 
 ## Custom proxy
 
@@ -12,4 +12,4 @@ connection before giving it to gRPC.
 
 If the default proxy doesn't work for you, replace the default dialer with your
 custom proxy dialer. This can be done using
-[`WithDialer`](https://godoc.org/google.golang.org/grpc#WithDialer).
\ No newline at end of file
+[`WithDialer`](https://godoc.org/google.golang.org/grpc#WithDialer).

Documentation/server-reflection-tutorial.md

@@ -2,8 +2,9 @@
 
 gRPC Server Reflection provides information about publicly-accessible gRPC
 services on a server, and assists clients at runtime to construct RPC requests
-and responses without precompiled service information. It is used by gRPC CLI,
-which can be used to introspect server protos and send/receive test RPCs.
+and responses without precompiled service information. It is used by
+[gRPCurl](https://github.com/fullstorydev/grpcurl), which can be used to
+introspect server protos and send/receive test RPCs.
 
 ## Enable Server Reflection
 
@@ -39,36 +40,41 @@ make the following changes:
 An example server with reflection registered can be found at
 `examples/features/reflection/server`.
 
-## gRPC CLI
+## gRPCurl
 
-After enabling Server Reflection in a server application, you can use gRPC CLI
-to check its services. gRPC CLI is only available in c++. Instructions on how to
-build and use gRPC CLI can be found at
-[command_line_tool.md](https://github.com/grpc/grpc/blob/master/doc/command_line_tool.md).
+After enabling Server Reflection in a server application, you can use gRPCurl
+to check its services. gRPCurl is built with Go and has packages available.
+Instructions on how to install and use gRPCurl can be found at
+[gRPCurl Installation](https://github.com/fullstorydev/grpcurl#installation).
 
-## Use gRPC CLI to check services
+## Use gRPCurl to check services
 
 First, start the helloworld server in grpc-go directory:
 
 ```sh
-$ cd <grpc-go-directory>
-$ go run examples/features/reflection/server/main.go
+$ cd <grpc-go-directory>/examples
+$ go run features/reflection/server/main.go
 ```
 
-Open a new terminal and make sure you are in the directory where grpc_cli lives:
-
+output:
 ```sh
-$ cd <grpc-cpp-dirctory>/bins/opt
+server listening at [::]:50051
 ```
 
-### List services
+After installing gRPCurl, open a new terminal and run the commands from the new
+terminal.
+
+**NOTE:** gRPCurl expects a TLS-encrypted connection by default. For all of
+the commands below, use the `-plaintext` flag to use an unencrypted connection.
 
-`grpc_cli ls` command lists services and methods exposed at a given port:
+### List services and methods
+
+The `list` command lists services exposed at a given port:
 
 - List all the services exposed at a given port
 
   ```sh
-  $ ./grpc_cli ls localhost:50051
+  $ grpcurl -plaintext localhost:50051 list
   ```
 
   output:
@@ -78,72 +84,88 @@ $ cd <grpc-cpp-dirctory>/bins/opt
   helloworld.Greeter
   ```
 
-- List one service with details
+- List all the methods of a service
 
-  `grpc_cli ls` command inspects a service given its full name (in the format of
-  \<package\>.\<service\>). It can print information with a long listing format
-  when `-l` flag is set. This flag can be used to get more details about a
-  service.
+  The `list` command lists methods given the full service name (in the format of
+  \<package\>.\<service\>).
 
   ```sh
-  $ ./grpc_cli ls localhost:50051 helloworld.Greeter -l
+  $ grpcurl -plaintext localhost:50051 list helloworld.Greeter
   ```
 
   output:
   ```sh
-  filename: helloworld.proto
-  package: helloworld;
-  service Greeter {
-    rpc SayHello(helloworld.HelloRequest) returns (helloworld.HelloReply) {}
-  }
+  helloworld.Greeter.SayHello
+  ```
+
+### Describe services and methods
+
+- Describe all services
 
+  The `describe` command inspects a service given its full name (in the format
+  of \<package\>.\<service\>). 
+
+  ```sh
+  $ grpcurl -plaintext localhost:50051 describe helloworld.Greeter
   ```
 
-### List methods
+  output:
+  ```sh
+  helloworld.Greeter is a service:
+  service Greeter {
+    rpc SayHello ( .helloworld.HelloRequest ) returns ( .helloworld.HelloReply );
+  }
+  ```
 
-- List one method with details
+- Describe all methods of a service
 
-  `grpc_cli ls` command also inspects a method given its full name (in the
-  format of \<package\>.\<service\>.\<method\>).
+  The `describe` command inspects a method given its full name (in the format of
+  \<package\>.\<service\>.\<method\>).
 
   ```sh
-  $ ./grpc_cli ls localhost:50051 helloworld.Greeter.SayHello -l
+  $ grpcurl -plaintext localhost:50051 describe helloworld.Greeter.SayHello
   ```
 
   output:
   ```sh
-    rpc SayHello(helloworld.HelloRequest) returns (helloworld.HelloReply) {}
+  helloworld.Greeter.SayHello is a method:
+  rpc SayHello ( .helloworld.HelloRequest ) returns ( .helloworld.HelloReply );
   ```
 
 ### Inspect message types
 
-We can use`grpc_cli type` command to inspect request/response types given the
+We can use the `describe` command to inspect request/response types given the
 full name of the type (in the format of \<package\>.\<type\>).
 
 - Get information about the request type
 
   ```sh
-  $ ./grpc_cli type localhost:50051 helloworld.HelloRequest
+  $ grpcurl -plaintext localhost:50051 describe helloworld.HelloRequest
   ```
 
   output:
   ```sh
+  helloworld.HelloRequest is a message:
   message HelloRequest {
-    optional string name = 1[json_name = "name"];
+    string name = 1;
   }
   ```
 
 ### Call a remote method
 
-We can send RPCs to a server and get responses using `grpc_cli call` command.
+We can send RPCs to a server and get responses using the full method name (in
+the format of \<package\>.\<service\>.\<method\>). The `-d <string>` flag
+represents the request data and the `-format text` flag indicates that the
+request data is in text format.
 
 - Call a unary method
 
   ```sh
-  $ ./grpc_cli call localhost:50051 SayHello "name: 'gRPC CLI'"
+  $ grpcurl -plaintext -format text -d 'name: "gRPCurl"' \
+    localhost:50051 helloworld.Greeter.SayHello
   ```
 
   output:
   ```sh
-  message: "Hello gRPC CLI"
+  message: "Hello gRPCurl"
   ```