# Semconv v1.17.0

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.17.0)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.17.0)


# Semconv v1.18.0

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.18.0)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.18.0)

Perforator is a cluster-wide continuous profiling tool designed for large data centers


# Semconv v1.19.0

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.19.0)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.19.0)


# Semconv v1.20.0

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.20.0)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.20.0)


# Semconv v1.21.0

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.21.0)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.21.0)


# Semconv v1.22.0

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.22.0)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.22.0)


# Semconv v1.23.0

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.23.0)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.23.0)


# Semconv v1.23.1

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.23.1)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.23.1)


# Semconv v1.24.0

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.24.0)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.24.0)


# Semconv v1.25.0

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.25.0)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.25.0)


# Semconv v1.26.0

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.26.0)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.26.0)


# Semconv v1.27.0

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.27.0)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.27.0)


# Semconv v1.4.0

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.4.0)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.4.0)


# Semconv v1.5.0

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.5.0)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.5.0)


# Semconv v1.6.1

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.6.1)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.6.1)


# Semconv v1.7.0

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.7.0)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.7.0)


# Semconv v1.8.0

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.8.0)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.8.0)


# Semconv v1.9.0

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.9.0)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.9.0)


# Trace Embedded

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/trace/embedded)](https://pkg.go.dev/go.opentelemetry.io/otel/trace/embedded)


# Trace Noop

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/trace/noop)](https://pkg.go.dev/go.opentelemetry.io/otel/trace/noop)


# Building `sys/unix`

The sys/unix package provides access to the raw system call interface of the
underlying operating system. See: https://godoc.org/golang.org/x/sys/unix

Porting Go to a new architecture/OS combination or adding syscalls, types, or
constants to an existing architecture/OS pair requires some manual effort;
however, there are tools that automate much of the process.

## Build Systems

There are currently two ways we generate the necessary files. We are currently
migrating the build system to use containers so the builds are reproducible.
This is being done on an OS-by-OS basis. Please update this documentation as
components of the build system change.

### Old Build System (currently for `GOOS != "linux"`)

The old build system generates the Go files based on the C header files
present on your system. This means that files
for a given GOOS/GOARCH pair must be generated on a system with that OS and
architecture. This also means that the generated code can differ from system
to system, based on differences in the header files.

To avoid this, if you are using the old build system, only generate the Go
files on an installation with unmodified header files. It is also important to
keep track of which version of the OS the files were generated from (ex.
Darwin 14 vs Darwin 15). This makes it easier to track the progress of changes
and have each OS upgrade correspond to a single change.

To build the files for your current OS and architecture, make sure GOOS and
GOARCH are set correctly and run `mkall.sh`. This will generate the files for
your specific system. Running `mkall.sh -n` shows the commands that will be run.

Requirements: bash, go

### New Build System (currently for `GOOS == "linux"`)

The new build system uses a Docker container to generate the go files directly
from source checkouts of the kernel and various system libraries. This means
that on any platform that supports Docker, all the files using the new build
system can be generated at once, and generated files will not change based on
what the person running the scripts has installed on their computer.

The OS specific files for the new build system are located in the `${GOOS}`
directory, and the build is coordinated by the `${GOOS}/mkall.go` program. When
the kernel or system library updates, modify the Dockerfile at
`${GOOS}/Dockerfile` to checkout the new release of the source.

To build all the files under the new build system, you must be on an amd64/Linux
system and have your GOOS and GOARCH set accordingly. Running `mkall.sh` will
then generate all of the files for all of the GOOS/GOARCH pairs in the new build
system. Running `mkall.sh -n` shows the commands that will be run.

Requirements: bash, go, docker

## Component files

This section describes the various files used in the code generation process.
It also contains instructions on how to modify these files to add a new
architecture/OS or to add additional syscalls, types, or constants. Note that
if you are using the new build system, the scripts/programs cannot be called normally.
They must be called from within the docker container.

### asm files

The hand-written assembly file at `asm_${GOOS}_${GOARCH}.s` implements system
call dispatch. There are three entry points:
```
  func Syscall(trap, a1, a2, a3 uintptr) (r1, r2, err uintptr)
  func Syscall6(trap, a1, a2, a3, a4, a5, a6 uintptr) (r1, r2, err uintptr)
  func RawSyscall(trap, a1, a2, a3 uintptr) (r1, r2, err uintptr)
```
The first and second are the standard ones; they differ only in how many
arguments can be passed to the kernel. The third is for low-level use by the
ForkExec wrapper. Unlike the first two, it does not call into the scheduler to
let it know that a system call is running.

When porting Go to a new architecture/OS, this file must be implemented for
each GOOS/GOARCH pair.

### mksysnum

Mksysnum is a Go program located at `${GOOS}/mksysnum.go` (or `mksysnum_${GOOS}.go`
for the old system). This program takes in a list of header files containing the
syscall number declarations and parses them to produce the corresponding list of
Go numeric constants. See `zsysnum_${GOOS}_${GOARCH}.go` for the generated
constants.

Adding new syscall numbers is mostly done by running the build on a sufficiently
new installation of the target OS (or updating the source checkouts for the
new build system). However, depending on the OS, you may need to update the
parsing in mksysnum.

### mksyscall.go

The `syscall.go`, `syscall_${GOOS}.go`, `syscall_${GOOS}_${GOARCH}.go` are
hand-written Go files which implement system calls (for unix, the specific OS,
or the specific OS/Architecture pair respectively) that need special handling
and list `//sys` comments giving prototypes for ones that can be generated.

The mksyscall.go program takes the `//sys` and `//sysnb` comments and converts
them into syscalls. This requires the name of the prototype in the comment to
match a syscall number in the `zsysnum_${GOOS}_${GOARCH}.go` file. The function
prototype can be exported (capitalized) or not.

Adding a new syscall often just requires adding a new `//sys` function prototype
with the desired arguments and a capitalized name so it is exported. However, if
you want the interface to the syscall to be different, often one will make an
unexported `//sys` prototype, and then write a custom wrapper in
`syscall_${GOOS}.go`.

### types files

For each OS, there is a hand-written Go file at `${GOOS}/types.go` (or
`types_${GOOS}.go` on the old system). This file includes standard C headers and
creates Go type aliases to the corresponding C types. The file is then fed
through godef to get the Go compatible definitions. Finally, the generated code
is fed though mkpost.go to format the code correctly and remove any hidden or
private identifiers. This cleaned-up code is written to
`ztypes_${GOOS}_${GOARCH}.go`.

The hardest part about preparing this file is figuring out which headers to
include and which symbols need to be `#define`d to get the actual data
structures that pass through to the kernel system calls. Some C libraries
preset alternate versions for binary compatibility and translate them on the
way in and out of system calls, but there is almost always a `#define` that can
get the real ones.
See `types_darwin.go` and `linux/types.go` for examples.

To add a new type, add in the necessary include statement at the top of the
file (if it is not already there) and add in a type alias line. Note that if
your type is significantly different on different architectures, you may need
some `#if/#elif` macros in your include statements.

### mkerrors.sh

This script is used to generate the system's various constants. This doesn't
just include the error numbers and error strings, but also the signal numbers
and a wide variety of miscellaneous constants. The constants come from the list
of include files in the `includes_${uname}` variable. A regex then picks out
the desired `#define` statements, and generates the corresponding Go constants.
The error numbers and strings are generated from `#include <errno.h>`, and the
signal numbers and strings are generated from `#include <signal.h>`. All of
these constants are written to `zerrors_${GOOS}_${GOARCH}.go` via a C program,
`_errors.c`, which prints out all the constants.

To add a constant, add the header that includes it to the appropriate variable.
Then, edit the regex (if necessary) to match the desired constant. Avoid making
the regex too broad to avoid matching unintended constants.

### internal/mkmerge

This program is used to extract duplicate const, func, and type declarations
from the generated architecture-specific files listed below, and merge these
into a common file for each OS.

The merge is performed in the following steps:
1. Construct the set of common code that is identical in all architecture-specific files.
2. Write this common code to the merged file.
3. Remove the common code from all architecture-specific files.

## Generated files

### `zerrors_${GOOS}_${GOARCH}.go`

A file containing all of the system's generated error numbers, error strings,
signal numbers, and constants. Generated by `mkerrors.sh` (see above).

### `zsyscall_${GOOS}_${GOARCH}.go`

A file containing all the generated syscalls for a specific GOOS and GOARCH.
Generated by `mksyscall.go` (see above).

### `zsysnum_${GOOS}_${GOARCH}.go`

A list of numeric constants for all the syscall number of the specific GOOS
and GOARCH. Generated by mksysnum (see above).

### `ztypes_${GOOS}_${GOARCH}.go`

A file containing Go types for passing into (or returning from) syscalls.
Generated by godefs and the types file (see above).


`testv3.go` was generated with an older version of codegen, to test reflection
behavior with `grpc.SupportPackageIsVersion3`. DO NOT REGENERATE!

`testv3.go` was then manually edited to replace `"golang.org/x/net/context"`
with `"context"`.

`dynamic.go` was generated with a newer protoc and manually edited to remove
everything except the descriptor bytes var, which is renamed and exported.


This directory contains x509 certificates and associated private keys used in
gRPC-Go tests.

How were these test certs/keys generated ?
------------------------------------------
Run `./create.sh`


# Minimal Go logging using klog

This package implements the [logr interface](https://github.com/go-logr/logr)
in terms of Kubernetes' [klog](https://github.com/kubernetes/klog).  This
provides a relatively minimalist API to logging in Go, backed by a well-proven
implementation.

Because klogr was implemented before klog itself added supported for
structured logging, the default in klogr is to serialize key/value
pairs with JSON and log the result as text messages via klog. This
does not work well when klog itself forwards output to a structured
logger.

Therefore the recommended approach is to let klogr pass all log
messages through to klog and deal with structured logging there. Just
beware that the output of klog without a structured logger is meant to
be human-readable, in contrast to the JSON-based traditional format.

This is a BETA grade implementation.


# Semi-public headers
The headers listed here all export symbols into the ares namespace as public
symbols, but these headers are NOT included in the distribution.  They are
meant to be used by other tools such as `adig` and `ahost`.

These are most likely going to be general purpose library functions such
as data structures and algorithms.


## Logging types

This package contains shared [protocol buffer][protobuf] types that are populated
by the Stackdriver Logging API and consumed by other APIs.

### Key Concepts

- **HttpRequest**: Contains the complete set of information about a particular
  HTTP request, such as HTTP method, request URL, status code, and other things.
- **LogSeverity**: The severity of a log entry (e.g. `DEBUG`, `INFO`, `WARNING`).

[protobuf]: https://developers.google.com/protocol-buffers/


# gRPC EventEngine

An EventEngine handles all cross-platform I/O, task execution, and DNS
resolution for gRPC. A default, cross-platform implementation is provided with
gRPC, but part of the intent here is to provide an interface for external
integrators to bring their own functionality. This allows for integration with
external event loops, siloing I/O and task execution between channels or
servers, and other custom integrations that were previously unsupported.

*WARNING*: This is experimental code and is subject to change.

## High level expectations of an EventEngine implementation

### Provide their own I/O threads
EventEngines are expected to internally create whatever threads are required to
perform I/O and execute callbacks. For example, an EventEngine implementation
may want to spawn separate thread pools for polling and callback execution.

### Provisioning data buffers via Slice allocation
At a high level, gRPC provides a `ResourceQuota` system that allows gRPC to
reclaim memory and degrade gracefully when memory reaches application-defined
thresholds. To enable this feature, the memory allocation of read/write buffers
within an EventEngine must be acquired in the form of Slices from
SliceAllocators. This is covered more fully in the gRFC and code.

### Documentating expectations around callback execution
Some callbacks may be expensive to run. EventEngines should decide on and
document whether callback execution might block polling operations. This way,
application developers can plan accordingly (e.g., run their expensive callbacks
on a separate thread if necessary).

### Handling concurrent usage
Assume that gRPC may use an EventEngine concurrently across multiple threads.

## TODO: documentation

* Example usage
* Link to gRFC


**The APIs in this directory are not stable!**

This directory contains header files that need to be installed but are not part
of the public API. Users should not use these headers directly.


Optional plugins for gRPC Core: Modules in this directory extend gRPC Core in
useful ways. All optional code belongs here.

NOTE: The movement of code between lib and ext is an ongoing effort, so this
directory currently contains too much of the core library.


Required elements of gRPC Core: Each module in this directory is required to
build gRPC. If it's possible to envisage a configuration where code is not
required, then that code belongs in ext/ instead.

NOTE: The movement of code between lib and ext is an ongoing effort, so this
directory currently contains too much of the core library.


# Transport Security Interface
An abstraction library over crypto and auth modules (typically OpenSSL)


Implementation of BLAKE3, originating from https://github.com/BLAKE3-team/BLAKE3/tree/1.3.1/c

# Example

An example program that hashes bytes from standard input and prints the
result:

Using the C++ API:

```c++
#include "llvm/Support/BLAKE3.h"
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>

int main() {
  // Initialize the hasher.
  llvm::BLAKE3 hasher;

  // Read input bytes from stdin.
  char buf[65536];
  while (1) {
    ssize_t n = read(STDIN_FILENO, buf, sizeof(buf));
    if (n > 0) {
      hasher.update(llvm::StringRef(buf, n));
    } else if (n == 0) {
      break; // end of file
    } else {
      fprintf(stderr, "read failed: %s\n", strerror(errno));
      exit(1);
    }
  }

  // Finalize the hash. Default output length is 32 bytes.
  auto output = hasher.final();

  // Print the hash as hexadecimal.
  for (uint8_t byte : output) {
    printf("%02x", byte);
  }
  printf("\n");
  return 0;
}
```

Using the C API:

```c
#include "llvm-c/blake3.h"
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>

int main() {
  // Initialize the hasher.
  llvm_blake3_hasher hasher;
  llvm_blake3_hasher_init(&hasher);

  // Read input bytes from stdin.
  unsigned char buf[65536];
  while (1) {
    ssize_t n = read(STDIN_FILENO, buf, sizeof(buf));
    if (n > 0) {
      llvm_blake3_hasher_update(&hasher, buf, n);
    } else if (n == 0) {
      break; // end of file
    } else {
      fprintf(stderr, "read failed: %s\n", strerror(errno));
      exit(1);
    }
  }

  // Finalize the hash. LLVM_BLAKE3_OUT_LEN is the default output length, 32 bytes.
  uint8_t output[LLVM_BLAKE3_OUT_LEN];
  llvm_blake3_hasher_finalize(&hasher, output, LLVM_BLAKE3_OUT_LEN);

  // Print the hash as hexadecimal.
  for (size_t i = 0; i < LLVM_BLAKE3_OUT_LEN; i++) {
    printf("%02x", output[i]);
  }
  printf("\n");
  return 0;
}
```

# API

## The Class/Struct

```c++
class BLAKE3 {
  // API
private:
  llvm_blake3_hasher Hasher;
};
```
```c
typedef struct {
  // private fields
} llvm_blake3_hasher;
```

An incremental BLAKE3 hashing state, which can accept any number of
updates. This implementation doesn't allocate any heap memory, but
`sizeof(llvm_blake3_hasher)` itself is relatively large, currently 1912 bytes
on x86-64. This size can be reduced by restricting the maximum input
length, as described in Section 5.4 of [the BLAKE3
spec](https://github.com/BLAKE3-team/BLAKE3-specs/blob/master/blake3.pdf),
but this implementation doesn't currently support that strategy.

## Common API Functions

```c++
BLAKE3::BLAKE3();

void BLAKE3::init();
```
```c
void llvm_blake3_hasher_init(
  llvm_blake3_hasher *self);
```

Initialize a `llvm_blake3_hasher` in the default hashing mode.

---

```c++
void BLAKE3::update(ArrayRef<uint8_t> Data);

void BLAKE3::update(StringRef Str);
```
```c
void llvm_blake3_hasher_update(
  llvm_blake3_hasher *self,
  const void *input,
  size_t input_len);
```

Add input to the hasher. This can be called any number of times.

---

```c++
template <size_t NumBytes = LLVM_BLAKE3_OUT_LEN>
using BLAKE3Result = std::array<uint8_t, NumBytes>;

template <size_t NumBytes = LLVM_BLAKE3_OUT_LEN>
void BLAKE3::final(BLAKE3Result<NumBytes> &Result);

template <size_t NumBytes = LLVM_BLAKE3_OUT_LEN>
BLAKE3Result<NumBytes> BLAKE3::final();
```
```c
void llvm_blake3_hasher_finalize(
  const llvm_blake3_hasher *self,
  uint8_t *out,
  size_t out_len);
```

Finalize the hasher and return an output of any length, given in bytes.
This doesn't modify the hasher itself, and it's possible to finalize
again after adding more input. The constant `LLVM_BLAKE3_OUT_LEN` provides
the default output length, 32 bytes, which is recommended for most
callers.

Outputs shorter than the default length of 32 bytes (256 bits) provide
less security. An N-bit BLAKE3 output is intended to provide N bits of
first and second preimage resistance and N/2 bits of collision
resistance, for any N up to 256. Longer outputs don't provide any
additional security.

Shorter BLAKE3 outputs are prefixes of longer ones. Explicitly
requesting a short output is equivalent to truncating the default-length
output. (Note that this is different between BLAKE2 and BLAKE3.)

## Less Common API Functions

```c
void llvm_blake3_hasher_init_keyed(
  llvm_blake3_hasher *self,
  const uint8_t key[LLVM_BLAKE3_KEY_LEN]);
```

Initialize a `llvm_blake3_hasher` in the keyed hashing mode. The key must be
exactly 32 bytes.

---

```c
void llvm_blake3_hasher_init_derive_key(
  llvm_blake3_hasher *self,
  const char *context);
```

Initialize a `llvm_blake3_hasher` in the key derivation mode. The context
string is given as an initialization parameter, and afterwards input key
material should be given with `llvm_blake3_hasher_update`. The context string
is a null-terminated C string which should be **hardcoded, globally
unique, and application-specific**. The context string should not
include any dynamic input like salts, nonces, or identifiers read from a
database at runtime. A good default format for the context string is
`"[application] [commit timestamp] [purpose]"`, e.g., `"example.com
2019-12-25 16:18:03 session tokens v1"`.

This function is intended for application code written in C. For
language bindings, see `llvm_blake3_hasher_init_derive_key_raw` below.

---

```c
void llvm_blake3_hasher_init_derive_key_raw(
  llvm_blake3_hasher *self,
  const void *context,
  size_t context_len);
```

As `llvm_blake3_hasher_init_derive_key` above, except that the context string
is given as a pointer to an array of arbitrary bytes with a provided
length. This is intended for writing language bindings, where C string
conversion would add unnecessary overhead and new error cases. Unicode
strings should be encoded as UTF-8.

Application code in C should prefer `llvm_blake3_hasher_init_derive_key`,
which takes the context as a C string. If you need to use arbitrary
bytes as a context string in application code, consider whether you're
violating the requirement that context strings should be hardcoded.

---

```c
void llvm_blake3_hasher_finalize_seek(
  const llvm_blake3_hasher *self,
  uint64_t seek,
  uint8_t *out,
  size_t out_len);
```

The same as `llvm_blake3_hasher_finalize`, but with an additional `seek`
parameter for the starting byte position in the output stream. To
efficiently stream a large output without allocating memory, call this
function in a loop, incrementing `seek` by the output length each time.

---

```c
void llvm_blake3_hasher_reset(
  llvm_blake3_hasher *self);
```

Reset the hasher to its initial state, prior to any calls to
`llvm_blake3_hasher_update`. Currently this is no different from calling
`llvm_blake3_hasher_init` or similar again. However, if this implementation gains
multithreading support in the future, and if `llvm_blake3_hasher` holds (optional)
threading resources, this function will reuse those resources.

# Building

This implementation is just C and assembly files.

## x86

Dynamic dispatch is enabled by default on x86. The implementation will
query the CPU at runtime to detect SIMD support, and it will use the
widest instruction set available. By default, `blake3_dispatch.c`
expects to be linked with code for five different instruction sets:
portable C, SSE2, SSE4.1, AVX2, and AVX-512.

For each of the x86 SIMD instruction sets, four versions are available:
three flavors of assembly (Unix, Windows MSVC, and Windows GNU) and one
version using C intrinsics. The assembly versions are generally
preferred. They perform better, they perform more consistently across
different compilers, and they build more quickly. On the other hand, the
assembly versions are x86\_64-only, and you need to select the right
flavor for your target platform.

## ARM NEON

The NEON implementation is enabled by default on AArch64, but not on
other ARM targets, since not all of them support it. To enable it, set
`BLAKE3_USE_NEON=1`.

To explicitiy disable using NEON instructions on AArch64, set
`BLAKE3_USE_NEON=0`.

## Other Platforms

The portable implementation should work on most other architectures.

# Multithreading

The implementation doesn't currently support multithreading.


# How to use this folder

Edit exiting config files. This files are passed into `tpl` function allowing for templating from values.
Note: The field storage.host should always be a template due to storage hostname dependency on release name.


# testdata

The private key used in these tests is of the correct format, but does not
really allow access to any cloud project. DO NOT put any real credentials in
this folder, it is strictly for use in unit tests.


# YAML reader for CUE

This yaml parser is a heavily modified version of Canonical's go-yaml parser,
which in turn is a port of the [libyaml](http://pyyaml.org/wiki/LibYAML) parser.

License
-------

The yaml package is licensed under the Apache License 2.0. Please see the LICENSE file for details.


bpf2go
===

`bpf2go` compiles a C source file into eBPF bytecode and then emits a
Go file containing the eBPF. The goal is to avoid loading the
eBPF from disk at runtime and to minimise the amount of manual
work required to interact with eBPF programs. It takes inspiration
from `bpftool gen skeleton`.

Invoke the program using go generate:

    //go:generate go run github.com/cilium/ebpf/cmd/bpf2go foo path/to/src.c -- -I/path/to/include

This will emit `foo_bpfel.go` and `foo_bpfeb.go`, with types using `foo`
as a stem. The two files contain compiled BPF for little and big
endian systems, respectively.

## Environment Variables

You can use environment variables to affect all bpf2go invocations
across a project, e.g. to set specific C flags:

    BPF2GO_FLAGS="-O2 -g -Wall -Werror $(CFLAGS)" go generate ./...

Alternatively, by exporting `$BPF2GO_FLAGS` from your build system, you can
control all builds from a single location.

Most bpf2go arguments can be controlled this way. See `bpf2go -h` for an
up-to-date list.

## Generated types

`bpf2go` generates Go types for all map keys and values by default. You can
disable this behaviour using `-no-global-types`. You can add to the set of
types by specifying `-type foo` for each type you'd like to generate.

## Examples

See [examples/kprobe](../../examples/kprobe/main.go) for a fully worked out example.


CRDB
====

`crdb` is a wrapper around the logic for issuing SQL transactions which performs
retries (as required by CockroachDB).

Note that unfortunately there is no generic way of extracting a pg error code;
the library has to recognize driver-dependent error types. We currently use
the `SQLState() string` method that is implemented in both
[`github.com/lib/pq`](https://github.com/lib/pq), since version 1.10.6, and
[`github.com/jackc/pgx`](https://github.com/jackc/pgx) when used in database/sql
driver mode.

Subpackages provide support for [gorm](https://github.com/go-gorm/gorm), [pgx](https://github.com/jackc/pgx), and [sqlx](https://github.com/jmoiron/sqlx) used in standalone-library mode.

Note for developers: if you make any changes here (especially if they modify public
APIs), please verify that the code in https://github.com/cockroachdb/examples-go
still works and update as necessary.


# Deprecated

Use [cmd/migrate](../cmd/migrate) instead


**This directory has the implementation of the S2Av2's gRPC-Go client libraries**


# pgconn

Package pgconn is a low-level PostgreSQL database driver. It operates at nearly the same level as the C library libpq.
It is primarily intended to serve as the foundation for higher level libraries such as https://github.com/jackc/pgx.
Applications should handle normal queries with a higher level library and only use pgconn directly when required for
low-level access to PostgreSQL functionality.

## Example Usage

```go
pgConn, err := pgconn.Connect(context.Background(), os.Getenv("DATABASE_URL"))
if err != nil {
	log.Fatalln("pgconn failed to connect:", err)
}
defer pgConn.Close(context.Background())

result := pgConn.ExecParams(context.Background(), "SELECT email FROM users WHERE id=$1", [][]byte{[]byte("123")}, nil, nil, nil)
for result.NextRow() {
	fmt.Println("User 123 has email:", string(result.Values()[0]))
}
_, err = result.Close()
if err != nil {
	log.Fatalln("failed reading result:", err)
}
```

## Testing

See CONTRIBUTING.md for setup instructions.


# pgproto3

Package pgproto3 is an encoder and decoder of the PostgreSQL wire protocol version 3.

pgproto3 can be used as a foundation for PostgreSQL drivers, proxies, mock servers, load balancers and more.

See example/pgfortune for a playful example of a fake PostgreSQL server.


# Test Setup

This directory contains miscellaneous files used to setup a test database.


# orb/clip/smartclip [![Godoc Reference](https://pkg.go.dev/badge/github.com/paulmach/orb)](https://pkg.go.dev/github.com/paulmach/orb/clip/smartclip)

This package extends the clip functionality to handle partial 2d geometries. The input polygon
rings need to only intersect the bound. The algorithm will use that, plus the orientation, to
wrap/close the rings around the edge of the bound.

The use case is [OSM multipolyon relations](https://wiki.openstreetmap.org/wiki/Relation#Multipolygon)
where a ring (inner or outer) contains multiple ways but only one is in the current viewport.
With only the ways intersecting the viewport and their orientation the correct shape can be drawn.

## Example

```go
bound := orb.Bound{Min: orb.Point{1, 1}, Max: orb.Point{10, 10}}

// a partial ring cutting the bound down the middle.
ring := orb.Ring{{0, 0}, {11, 11}}
clipped := smartclip.Ring(bound, ring, orb.CCW)

// clipped is a multipolyon with one ring that wraps counter-clockwise
// around the top triangle of the box
// [[[[1 1] [10 10] [5.5 10] [1 10] [1 5.5] [1 1]]]]
```


# encoding/ewkb [![Godoc Reference](https://pkg.go.dev/badge/github.com/paulmach/orb)](https://pkg.go.dev/github.com/paulmach/orb/encoding/ewkb)

This package provides encoding and decoding of [extended WKB](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry#Format_variations)
data. This format includes the [SRID](https://en.wikipedia.org/wiki/Spatial_reference_system) in the data.
If the SRID is not needed use the [wkb](../wkb) package for a simpler interface.
The interface is defined as:

```go
func Marshal(geom orb.Geometry, srid int, byteOrder ...binary.ByteOrder) ([]byte, error)
func MarshalToHex(geom orb.Geometry, srid int, byteOrder ...binary.ByteOrder) (string, error)
func MustMarshal(geom orb.Geometry, srid int, byteOrder ...binary.ByteOrder) []byte
func MustMarshalToHex(geom orb.Geometry, srid int, byteOrder ...binary.ByteOrder) string

func NewEncoder(w io.Writer) *Encoder
func (e *Encoder) SetByteOrder(bo binary.ByteOrder) *Encoder
func (e *Encoder) SetSRID(srid int) *Encoder
func (e *Encoder) Encode(geom orb.Geometry) error

func Unmarshal(b []byte) (orb.Geometry, int, error)

func NewDecoder(r io.Reader) *Decoder
func (d *Decoder) Decode() (orb.Geometry, int, error)
```

## Inserting geometry into a database

Depending on the database different formats and functions are supported.

### PostgreSQL and PostGIS

PostGIS stores geometry as EWKB internally. As a result it can be inserted without
a wrapper function.

```go
db.Exec("INSERT INTO geodata(geom) VALUES (ST_GeomFromEWKB($1))", ewkb.Value(coord, 4326))

db.Exec("INSERT INTO geodata(geom) VALUES ($1)", ewkb.Value(coord, 4326))
```

### MySQL/MariaDB

MySQL and MariaDB
[store geometry](https://dev.mysql.com/doc/refman/5.7/en/gis-data-formats.html)
data in WKB format with a 4 byte SRID prefix.

```go
coord := orb.Point{1, 2}

// as WKB in hex format
data := wkb.MustMarshalToHex(coord)
db.Exec("INSERT INTO geodata(geom) VALUES (ST_GeomFromWKB(UNHEX(?), 4326))", data)

// relying on the raw encoding
db.Exec("INSERT INTO geodata(geom) VALUES (?)", ewkb.ValuePrefixSRID(coord, 4326))
```

## Reading geometry from a database query

As stated above, different databases supported different formats and functions.

### PostgreSQL and PostGIS

When working with PostGIS the raw format is EWKB so the wrapper function is not necessary

```go
// both of these queries return the same data
row := db.QueryRow("SELECT ST_AsEWKB(geom) FROM geodata")
row := db.QueryRow("SELECT geom FROM geodata")

// if you don't need the SRID
p := orb.Point{}
err := row.Scan(ewkb.Scanner(&p))
log.Printf("geom: %v", p)

// if you need the SRID
p := orb.Point{}
gs := ewkb.Scanner(&p)
err := row.Scan(gs)

log.Printf("srid: %v", gs.SRID)
log.Printf("geom: %v", gs.Geometry)
log.Printf("also geom: %v", p)
```

### MySQL/MariaDB

```go
// using the ST_AsBinary function
row := db.QueryRow("SELECT st_srid(geom), ST_AsBinary(geom) FROM geodata")
row.Scan(&srid, ewkb.Scanner(&data))

// relying on the raw encoding
row := db.QueryRow("SELECT geom FROM geodata")

// if you don't need the SRID
p := orb.Point{}
err := row.Scan(ewkb.ScannerPrefixSRID(&p))
log.Printf("geom: %v", p)

// if you need the SRID
p := orb.Point{}
gs := ewkb.ScannerPrefixSRID(&p)
err := row.Scan(gs)

log.Printf("srid: %v", gs.SRID)
log.Printf("geom: %v", gs.Geometry)
```


# encoding/mvt [![Godoc Reference](https://pkg.go.dev/badge/github.com/paulmach/orb)](https://pkg.go.dev/github.com/paulmach/orb/encoding/mvt)

Package mvt provides functions for encoding and decoding
[Mapbox Vector Tiles](https://www.mapbox.com/vector-tiles/specification/).
The interface is defined as:

```go
type Layer struct {
    Name     string
    Version  uint32
    Extent   uint32
    Features []*geojson.Feature
}

func MarshalGzipped(layers Layers) ([]byte, error)
func Marshal(layers Layers) ([]byte, error)

func UnmarshalGzipped(data []byte) (Layers, error)
func Unmarshal(data []byte) (Layers, error)
```

These function decode the geometry and leave it in the "tile coordinates".
To project it to and from WGS84 (standard lon/lat) use:

```go
func (l Layer) ProjectToTile(tile maptile.Tile)
func (l Layer) ProjectToWGS84(tile maptile.Tile)
```

## Version 1 vs. Version 2

There is no data format difference between v1 and v2. The difference is v2 requires geometries
be simple/clean. e.g. lines that are not self intersecting and polygons that are encoded in the correct winding order.

This library does not do anything to validate the geometry, it just encodes what you give it, so it defaults to v1.
I've seen comments from Mapbox about this and they only want you to claim your library is a v2 encoder if it does cleanup/validation.

However, if you know your geometry is simple/clean you can change the [layer version](https://pkg.go.dev/github.com/paulmach/orb/encoding/mvt#Layer) manually.

## Encoding example

```go
// Start with a set of feature collections defining each layer in lon/lat (WGS84).
collections := map[string]*geojson.FeatureCollection{}

// Convert to a layers object and project to tile coordinates.
layers := mvt.NewLayers(collections)
layers.ProjectToTile(maptile.New(x, y, z))

// In order to be used as source for MapboxGL geometries need to be clipped
// to max allowed extent. (uncomment next line)
// layers.Clip(mvt.MapboxGLDefaultExtentBound)

// Simplify the geometry now that it's in the tile coordinate space.
layers.Simplify(simplify.DouglasPeucker(1.0))

// Depending on use-case remove empty geometry, those two small to be
// represented in this tile space.
// In this case lines shorter than 1, and areas smaller than 1.
layers.RemoveEmpty(1.0, 1.0)

// encoding using the Mapbox Vector Tile protobuf encoding.
data, err := mvt.Marshal(layers) // this data is NOT gzipped.

// Sometimes MVT data is stored and transfered gzip compressed. In that case:
data, err := mvt.MarshalGzipped(layers)
```

## Feature IDs

Since GeoJSON ids can be any number or string they won't necessarily map to vector tile uint64 ids.
This is a common incompatibility between the two types.

During marshaling the code tries to convert the geojson.Feature.ID to a positive integer, possibly parsing a string.
If the number is negative, the id is omitted. If the number is a positive decimal the number is truncated.

For unmarshaling the id will be converted into a float64 to be consistent with how
the encoding/json package decodes numbers.

## Geometry Collections

GeoJSON geometry collections are flattened and their features are encoded individually.
As a result the "collection" information is lost when encoding and there could be more
features in the output (mvt) vs. in the input (GeoJSON)


# encoding/wkb [![Godoc Reference](https://pkg.go.dev/badge/github.com/paulmach/orb)](https://pkg.go.dev/github.com/paulmach/orb/encoding/wkb)

This package provides encoding and decoding of [WKB](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry#Well-known_binary)
data. The interface is defined as:

```go
func Marshal(geom orb.Geometry, byteOrder ...binary.ByteOrder) ([]byte, error)
func MarshalToHex(geom orb.Geometry, byteOrder ...binary.ByteOrder) (string, error)
func MustMarshal(geom orb.Geometry, byteOrder ...binary.ByteOrder) []byte
func MustMarshalToHex(geom orb.Geometry, byteOrder ...binary.ByteOrder) string

func NewEncoder(w io.Writer) *Encoder
func (e *Encoder) SetByteOrder(bo binary.ByteOrder)
func (e *Encoder) Encode(geom orb.Geometry) error

func Unmarshal(b []byte) (orb.Geometry, error)

func NewDecoder(r io.Reader) *Decoder
func (d *Decoder) Decode() (orb.Geometry, error)
```

## Reading and Writing to a SQL database

This package provides wrappers for `orb.Geometry` types that implement
`sql.Scanner` and `driver.Value`. For example:

```go
row := db.QueryRow("SELECT ST_AsBinary(point_column) FROM postgis_table")

var p orb.Point
err := row.Scan(wkb.Scanner(&p))

db.Exec("INSERT INTO table (point_column) VALUES (?)", wkb.Value(p))
```

The column can also be wrapped in `ST_AsEWKB`. The SRID will be ignored.

If you don't know the type of the geometry try something like

```go
s := wkb.Scanner(nil)
err := row.Scan(&s)

switch g := s.Geometry.(type) {
case orb.Point:
case orb.LineString:
}
```

Scanning directly from MySQL columns is supported. By default MySQL returns geometry
data as WKB but prefixed with a 4 byte SRID. To support this, if the data is not
valid WKB, the code will strip the first 4 bytes, the SRID, and try again.
This works for most use cases.


# encoding/wkt [![Godoc Reference](https://pkg.go.dev/badge/github.com/paulmach/orb)](https://pkg.go.dev/github.com/paulmach/orb/encoding/wkt)

This package provides encoding and decoding of [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)
data. The interface is defined as:

```go
func MarshalString(orb.Geometry) string

func Unmarshal(string) (orb.Geometry, error)
func UnmarshalPoint(string) (orb.Point, err error)
func UnmarshalMultiPoint(string) (orb.MultiPoint, err error)
func UnmarshalLineString(string) (orb.LineString, err error)
func UnmarshalMultiLineString(string) (orb.MultiLineString, err error)
func UnmarshalPolygon(string) (orb.Polygon, err error)
func UnmarshalMultiPolygon(string) (orb.MultiPolygon, err error)
func UnmarshalCollection(string) (orb.Collection, err error)
```


# orb/maptile/tilecover [![Godoc Reference](https://pkg.go.dev/badge/github.com/paulmach/orb)](https://pkg.go.dev/github.com/paulmach/orb/maptile/tilecover)

Package `tilecover` computes the covering set of tiles for an `orb.Geometry`.
It is a a port of the nodejs library [tile-cover](https://github.com/mapbox/tile-cover)
which is a port from Google's S2 library. The same set of tests pass.

## Usage

```go
poly := orb.Polygon{}
tiles, err := tilecover.Geometry(poly, zoom)
if err != nil {
	// indicates a non-closed ring
}

for t := range tiles {
    // do something with tile
}

// to merge up to as much as possible to a specific zoom
tiles = tilecover.MergeUp(tiles, 0)
```

## Similar libraries in other languages:

-   [tilecover](https://github.com/mapbox/tile-cover) - Node


# OpenTracing Migration

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/bridge/opentracing/migration)](https://pkg.go.dev/go.opentelemetry.io/otel/bridge/opentracing/migration)


# OTLP Trace Exporter

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/exporters/otlp/otlptrace)](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlptrace)


# STDOUT Trace Exporter

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/exporters/stdout/stdouttrace)](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/stdout/stdouttrace)


# Experimental Features

The SDK contains features that have not yet stabilized in the OpenTelemetry specification.
These features are added to the OpenTelemetry Go SDK prior to stabilization in the specification so that users can start experimenting with them and provide feedback.

These feature may change in backwards incompatible ways as feedback is applied.
See the [Compatibility and Stability](#compatibility-and-stability) section for more information.

## Features

- [Resource](#resource)

### Resource

[OpenTelemetry resource semantic conventions] include many attribute definitions that are defined as experimental.
To have experimental semantic conventions be added by [resource detectors] set the `OTEL_GO_X_RESOURCE` environment variable.
The value set must be the case-insensitive string of `"true"` to enable the feature.
All other values are ignored.

<!-- TODO: document what attributes are added by which detector -->

[OpenTelemetry resource semantic conventions]: https://opentelemetry.io/docs/specs/semconv/resource/
[resource detectors]: https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#Detector

#### Examples

Enable experimental resource semantic conventions.

```console
export OTEL_GO_X_RESOURCE=true
```

Disable experimental resource semantic conventions.

```console
unset OTEL_GO_X_RESOURCE
```

## Compatibility and Stability

Experimental features do not fall within the scope of the OpenTelemetry Go versioning and stability [policy](../../../VERSIONING.md).
These features may be removed or modified in successive version releases, including patch versions.

When an experimental feature is promoted to a stable feature, a migration path will be included in the changelog entry of the release.
There is no guarantee that any environment variable feature flags that enabled the experimental feature will be supported by the stable version.
If they are supported, they may be accompanied with a deprecation notice stating a timeline for the removal of that support.


# SDK Trace test

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/sdk/trace/tracetest)](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/trace/tracetest)


# Semconv v1.13.0 HTTP conv

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.13.0/httpconv)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.13.0/httpconv)


# Semconv v1.13.0 NET conv

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.13.0/netconv)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.13.0/netconv)


# Semconv v1.14.0 HTTP conv

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.14.0/httpconv)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.14.0/httpconv)


# Semconv v1.14.0 NET conv

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.14.0/netconv)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.14.0/netconv)


# Semconv v1.15.0 HTTP conv

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.15.0/httpconv)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.15.0/httpconv)


# Semconv v1.15.0 NET conv

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.15.0/netconv)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.15.0/netconv)


# Semconv v1.16.0 HTTP conv

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.16.0/httpconv)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.16.0/httpconv)


# Semconv v1.16.0 NET conv

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.16.0/netconv)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.16.0/netconv)


# Semconv v1.17.0 HTTP conv

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.17.0/httpconv)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.17.0/httpconv)


# Semconv v1.18.0 HTTP conv

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.18.0/httpconv)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.18.0/httpconv)


# Semconv v1.18.0 NET conv

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.18.0/netconv)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.18.0/netconv)


# Semconv v1.19.0 HTTP conv

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.19.0/httpconv)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.19.0/httpconv)


# Semconv v1.19.0 NET conv

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.19.0/netconv)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.19.0/netconv)


# Semconv v1.20.0 HTTP conv

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.20.0/httpconv)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.20.0/httpconv)


# Semconv v1.20.0 NET conv

[![PkgGoDev](https://pkg.go.dev/badge/go.opentelemetry.io/otel/semconv/v1.20.0/netconv)](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.20.0/netconv)


# h2i

**h2i** is an interactive HTTP/2 ("h2") console debugger. Miss the good ol'
days of telnetting to your HTTP/1.n servers? We're bringing you
back.

Features:
- send raw HTTP/2 frames
 - PING
 - SETTINGS
 - HEADERS
 - etc
- type in HTTP/1.n and have it auto-HPACK/frame-ify it for HTTP/2
- pretty print all received HTTP/2 frames from the peer (including HPACK decoding)
- tab completion of commands, options

Not yet features, but soon:
- unnecessary CONTINUATION frames on short boundaries, to test peer implementations
- request bodies (DATA frames)
- send invalid frames for testing server implementations (supported by underlying Framer)

Later:
- act like a server

## Installation

```
$ go install golang.org/x/net/http2/h2i@latest
$ h2i <host>
```

## Demo

```
$ h2i
Usage: h2i <hostname>

  -insecure
        Whether to skip TLS cert validation
  -nextproto string
        Comma-separated list of NPN/ALPN protocol names to negotiate. (default "h2,h2-14")

$ h2i google.com
Connecting to google.com:443 ...
Connected to 74.125.224.41:443
Negotiated protocol "h2-14"
[FrameHeader SETTINGS len=18]
  [MAX_CONCURRENT_STREAMS = 100]
  [INITIAL_WINDOW_SIZE = 1048576]
  [MAX_FRAME_SIZE = 16384]
[FrameHeader WINDOW_UPDATE len=4]
  Window-Increment = 983041

h2i> PING h2iSayHI
[FrameHeader PING flags=ACK len=8]
  Data = "h2iSayHI"
h2i> headers
(as HTTP/1.1)> GET / HTTP/1.1
(as HTTP/1.1)> Host: ip.appspot.com
(as HTTP/1.1)> User-Agent: h2i/brad-n-blake
(as HTTP/1.1)>
Opening Stream-ID 1:
 :authority = ip.appspot.com
 :method = GET
 :path = /
 :scheme = https
 user-agent = h2i/brad-n-blake
[FrameHeader HEADERS flags=END_HEADERS stream=1 len=77]
  :status = "200"
  alternate-protocol = "443:quic,p=1"
  content-length = "15"
  content-type = "text/html"
  date = "Fri, 01 May 2015 23:06:56 GMT"
  server = "Google Frontend"
[FrameHeader DATA flags=END_STREAM stream=1 len=15]
  "173.164.155.78\n"
[FrameHeader PING len=8]
  Data = "\x00\x00\x00\x00\x00\x00\x00\x00"
h2i> ping
[FrameHeader PING flags=ACK len=8]
  Data = "h2i_ping"
h2i> ping
[FrameHeader PING flags=ACK len=8]
  Data = "h2i_ping"
h2i> ping
[FrameHeader GOAWAY len=22]
  Last-Stream-ID = 1; Error-Code = PROTOCOL_ERROR (1)

ReadFrame: EOF
```

## Status

Quick few hour hack. So much yet to do. Feel free to file issues for
bugs or wishlist items, but [@bmizerany](https://github.com/bmizerany/)
and I aren't yet accepting pull requests until things settle down.


# Clock

This package provides an interface for time-based operations.  It allows
mocking time for testing.

This is a copy of k8s.io/utils/clock. We have to copy it to avoid a circular
dependency (k8s.io/klog -> k8s.io/utils -> k8s.io/klog).


We have been working inside Google on a fork of Go that uses
BoringCrypto (the core of [BoringSSL](https://boringssl.googlesource.com/boringssl/))
for various crypto primitives, in furtherance of some work related to FIPS 140.
We have heard that some external users of Go would be
interested in this code as well, so we have published this code
here in the main Go repository behind the setting GOEXPERIMENT=boringcrypto.

Use of GOEXPERIMENT=boringcrypto outside Google is _unsupported_.
This mode is not part of the [Go 1 compatibility rules](https://go.dev/doc/go1compat),
and it may change incompatibly or break in other ways at any time.

To be clear, we are not making any statements or representations about
the suitability of this code in relation to the FIPS 140 standard.
Interested users will have to evaluate for themselves whether the code
is useful for their own purposes.

---

This directory holds the core of the BoringCrypto implementation
as well as the build scripts for the module itself: syso/*.syso.

syso/goboringcrypto_linux_amd64.syso is built with:

	GOARCH=amd64 ./build.sh

syso/goboringcrypto_linux_arm64.syso is built with:

	GOARCH=arm64 ./build.sh

Both run on an x86 Debian Linux system using Docker.
For the arm64 build to run on an x86 system, you need

	apt-get install qemu-user-static qemu-binfmt-support

to allow the x86 kernel to run arm64 binaries via QEMU.

See build.sh for more details about the build.


The `dnsinfo.h` header was extracted from Apple's OpenSource repository:
[https://opensource.apple.com/source/configd/configd-453.19/dnsinfo/dnsinfo.h](https://opensource.apple.com/source/configd/configd-453.19/dnsinfo/dnsinfo.h)

We then had to make a few edits to this file:
1. Add `AvailabilityMacros.h` header file
2. conditionalize `reach_flags` in `dns_resolver_t` on MacOS 10.8 or higher, in
   order to maintain compatibility with the last MacOS PPC release, 10.6.
3. conditionalize `_dns_configuration_ack()` on MacOS 10.8 or higher.
4. Update parameter list to `(void)` for both `dns_configuration_notify_key()`
   and `dns_configuration_copy()` to sidestep compiler warnings in this old
   header.

We had tried initially to use the latest 1109.140.1 which only worked on
MacOS 11+, then downgraded to 963.50.8 for MacOS 10.8+ support, then finally
to 453.19 with additional patches.

This is needed to call into `dns_configuration_copy()` and
`dns_configuration_free()`.


# Welcome to `include/grpc/impl/codegen`

## Why is this directory here?

This directory exists so that generated C++ code can include selected files upon
which it depends without having to depend on the entire gRPC C++ library. This
directory thus exists to support `include/grpcpp/impl/codegen`. This constraint
is particularly relevant for users of bazel, particularly if they use the
multi-lingual `proto_library` target type. Generated code that uses this target
only depends on the gRPC C++ targets associated with these header files, not the
entire gRPC C++ codebase since that would make the build time of these types of
targets excessively large (particularly when they are not even C++ specific).

## What should user code do?

User code should *not* include anything from this directory. Only generated code
and gRPC library code should include contents from this directory. C++ user code
should instead include contents from the main `grpcpp` directory or its
accessible subcomponents like `grpcpp/support`. It is possible that we may
remove this directory altogether if the motivations for its existence are no
longer strong enough (e.g., if the gRPC C++ library no longer has a need for an
`impl/codegen` directory of its own).


# Welcome to `include/grpcpp/impl/codegen`

## Why is this directory here?

This directory exists so that generated code can include selected files upon
which it depends without having to depend on the entire gRPC C++ library. This
is particularly relevant for users of bazel, particularly if they use the
multi-lingual `proto_library` target type. Generated code that uses this target
only depends on the gRPC C++ targets associated with these header files, not the
entire gRPC C++ codebase since that would make the build time of these types of
targets excessively large (particularly when they are not even C++ specific).

## What should user code do?

User code should *not* include anything from this directory. Only generated code
and gRPC library code should include contents from this directory. User code
should instead include contents from the main `grpcpp` directory or its
accessible subcomponents like `grpcpp/support`. It is possible that we may
remove this directory altogether if the motivations for its existence are no
longer strong enough (e.g., if most users migrate away from the `proto_library`
target type or if the additional overhead of depending on gRPC C++ is not high).


# Channel

Provides channel/call stack implementation, and implementation of common filters
for that implementation.


# GPR - Google Portable Runtime for C

The files in this directory contain basic utility code and platform
abstractions for C code.  None of this code is gRPC-specific; anything
here may also be useful for other open source projects written in C.

Note that this is one of the few places in src/core where we allow
the use of portability macros.


# GPR++ - Google Portable Runtime for C++

The files in this directory contain various utility code for C++ code.
None of this code is gRPC-specific; anything here may also be useful
for other open source projects written in C++.

Note that this is one of the few places in src/core where we allow
the use of portability macros.


# iomgr

Platform abstractions for I/O (mostly network).

Provides abstractions over TCP/UDP I/O, file loading, polling, and concurrency
management for various operating systems.


# Surface

Surface provides the bulk of the gRPC Core public API, and translates it into
calls against core components.


# Transport

Common implementation details for gRPC Transports.

Transports multiplex messages across some single connection. In ext/ there are
implementations atop [a custom http2 implementation](/src/core/ext/transport/chttp2/README.md)
and atop [cronet](/src/core/ext/transport/cronet/README.md).


# Legacy API type versions

This package includes types for legacy API versions. The stable version of the API types live in `api/types/*.go`.

Consider moving a type here when you need to keep backwards compatibility in the API. This legacy types are organized by the latest API version they appear in. For instance, types in the `v1p19` package are valid for API versions below or equal `1.19`. Types in the `v1p20` package are valid for the API version `1.20`, since the versions below that will use the legacy types in `v1p19`.

## Package name conventions

The package name convention is to use `v` as a prefix for the version number and `p`(patch) as a separator. We use this nomenclature due to a few restrictions in the Go package name convention:

1. We cannot use `.` because it's interpreted by the language, think of `v1.20.CallFunction`.
2. We cannot use `_` because golint complains about it. The code is actually valid, but it looks probably more weird: `v1_20.CallFunction`.

For instance, if you want to modify a type that was available in the version `1.21` of the API but it will have different fields in the version `1.22`, you want to create a new package under `api/types/versions/v1p21`.


# migrate CLI

## Installation

### Download pre-built binary (Windows, MacOS, or Linux)

[Release Downloads](https://github.com/golang-migrate/migrate/releases)

```bash
$ curl -L https://github.com/golang-migrate/migrate/releases/download/$version/migrate.$platform-amd64.tar.gz | tar xvz
```

### MacOS

```bash
$ brew install golang-migrate
```

### Windows

Using [scoop](https://scoop.sh/)

```bash
$ scoop install migrate
```

### Linux (*.deb package)

```bash
$ curl -L https://packagecloud.io/golang-migrate/migrate/gpgkey | apt-key add -
$ echo "deb https://packagecloud.io/golang-migrate/migrate/ubuntu/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/migrate.list
$ apt-get update
$ apt-get install -y migrate
```

### With Go toolchain

#### Versioned

```bash
$ go get -u -d github.com/golang-migrate/migrate/cmd/migrate
$ cd $GOPATH/src/github.com/golang-migrate/migrate/cmd/migrate
$ git checkout $TAG  # e.g. v4.1.0
$ # Go 1.15 and below
$ go build -tags 'postgres' -ldflags="-X main.Version=$(git describe --tags)" -o $GOPATH/bin/migrate $GOPATH/src/github.com/golang-migrate/migrate/cmd/migrate
$ # Go 1.16+
$ go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@$TAG
```

#### Unversioned

```bash
$ # Go 1.15 and below
$ go get -tags 'postgres' -u github.com/golang-migrate/migrate/cmd/migrate
$ # Go 1.16+
$ go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest
```

#### Notes

1. Requires a version of Go that [supports modules](https://golang.org/cmd/go/#hdr-Preliminary_module_support). e.g. Go 1.11+
1. These examples build the cli which will only work with postgres.  In order
to build the cli for use with other databases, replace the `postgres` build tag
with the appropriate database tag(s) for the databases desired.  The tags
correspond to the names of the sub-packages underneath the
[`database`](../database) package.
1. Similarly to the database build tags, if you need to support other sources, use the appropriate build tag(s).
1. Support for build constraints will be removed in the future: https://github.com/golang-migrate/migrate/issues/60
1. For versions of Go 1.15 and lower, [make sure](https://github.com/golang-migrate/migrate/pull/257#issuecomment-705249902) you're not installing the `migrate` CLI from a module. e.g. there should not be any `go.mod` files in your current directory or any directory from your current directory to the root

## Usage

```bash
$ migrate -help
Usage: migrate OPTIONS COMMAND [arg...]
       migrate [ -version | -help ]

Options:
  -source          Location of the migrations (driver://url)
  -path            Shorthand for -source=file://path
  -database        Run migrations against this database (driver://url)
  -prefetch N      Number of migrations to load in advance before executing (default 10)
  -lock-timeout N  Allow N seconds to acquire database lock (default 15)
  -verbose         Print verbose logging
  -version         Print version
  -help            Print usage

Commands:
  create [-ext E] [-dir D] [-seq] [-digits N] [-format] NAME
               Create a set of timestamped up/down migrations titled NAME, in directory D with extension E.
               Use -seq option to generate sequential up/down migrations with N digits.
               Use -format option to specify a Go time format string.
  goto V       Migrate to version V
  up [N]       Apply all or N up migrations
  down [N]     Apply all or N down migrations
  drop         Drop everything inside database
  force V      Set version V but don't run migration (ignores dirty state)
  version      Print current migration version
```

So let's say you want to run the first two migrations

```bash
$ migrate -source file://path/to/migrations -database postgres://localhost:5432/database up 2
```

If your migrations are hosted on github

```bash
$ migrate -source github://mattes:personal-access-token@mattes/migrate_test \
    -database postgres://localhost:5432/database down 2
```

The CLI will gracefully stop at a safe point when SIGINT (ctrl+c) is received.
Send SIGKILL for immediate halt.

## Reading CLI arguments from somewhere else

### ENV variables

```bash
$ migrate -database "$MY_MIGRATE_DATABASE"
```

### JSON files

Check out https://stedolan.github.io/jq/

```bash
$ migrate -database "$(cat config.json | jq '.database')"
```

### YAML files

```bash
$ migrate -database "$(cat config/database.yml | ruby -ryaml -e "print YAML.load(STDIN.read)['database']")"
$ migrate -database "$(cat config/database.yml | python -c 'import yaml,sys;print yaml.safe_load(sys.stdin)["database"]')"
```


# Cassandra

* Drop command will not work on Cassandra 2.X because it rely on
system_schema table which comes with 3.X
* Other commands should work properly but are **not tested**
* The Cassandra driver (gocql) does not natively support executing multiple statements in a single query. To allow for multiple statements in a single migration, you can use the `x-multi-statement` param. There are two important caveats:
  * This mode splits the migration text into separately-executed statements by a semi-colon `;`. Thus `x-multi-statement` cannot be used when a statement in the migration contains a string with a semi-colon.
  * The queries are not executed in any sort of transaction/batch, meaning you are responsible for fixing partial migrations.

## Usage
`cassandra://host:port/keyspace?param1=value&param2=value2`

| URL Query  | Default value | Description |
|------------|-------------|-----------|
| `x-migrations-table` | schema_migrations | Name of the migrations table |
| `x-multi-statement` | false | Enable multiple statements to be ran in a single migration (See note above) |
| `port` | 9042 | The port to bind to  |
| `consistency` | ALL | Migration consistency
| `protocol` |  | Cassandra protocol version (3 or 4)
| `timeout` | 1 minute | Migration timeout
| `connect-timeout` | 600ms | Initial connection timeout to the cluster |
| `username` | nil | Username to use when authenticating. |
| `password` | nil | Password to use when authenticating. |
| `sslcert` | | Cert file location. The file must contain PEM encoded data. |
| `sslkey` | | Key file location. The file must contain PEM encoded data. |
| `sslrootcert` | | The location of the root certificate file. The file must contain PEM encoded data. |
| `sslmode` | | Whether or not to use SSL (disable\|require\|verify-ca\|verify-full) |
| `disable-host-lookup`| false | Disable initial host lookup. |

`timeout` is parsed using [time.ParseDuration(s string)](https://golang.org/pkg/time/#ParseDuration)

## Upgrading from v1

1. Write down the current migration version from schema_migrations
2. `DROP TABLE schema_migrations`
4. Download and install the latest migrate version.
5. Force the current migration version with `migrate force <current_version>`.


# ClickHouse

`clickhouse://username:password@host:port/database=clicks?x-multi-statement=true`

| URL Query  | Description |
|------------|-------------|
| `x-migrations-table`| Name of the migrations table |
| `x-migrations-table-engine`| Engine to use for the migrations table, defaults to TinyLog |
| `x-cluster-name` | Name of cluster for creating `schema_migrations` table cluster wide |
| `database` | The name of the database to connect to |
| `username` | The user to sign in as |
| `password` | The user's password |
| `host` | The host to connect to. |
| `port` | The port to bind to. |
| `x-multi-statement` | false | Enable multiple statements to be ran in a single migration (See note below) |

## Notes

* The Clickhouse driver does not natively support executing multipe statements in a single query. To allow for multiple statements in a single migration, you can use the `x-multi-statement` param. There are two important caveats:
  * This mode splits the migration text into separately-executed statements by a semi-colon `;`. Thus `x-multi-statement` cannot be used when a statement in the migration contains a string with a semi-colon.
  * The queries are not executed in any sort of transaction/batch, meaning you are responsible for fixing partial migrations.
* Using the default TinyLog table engine for the schema_versions table prevents backing up the table if using the [clickhouse-backup](https://github.com/AlexAkulov/clickhouse-backup) tool. If backing up the database with make sure the migrations are run with `x-migrations-table-engine=MergeTree`.
* Clickhouse cluster mode is not officially supported, since it's not tested right now, but you can try enabling `schema_migrations` table replication by specifying a `x-cluster-name`:
  * When `x-cluster-name` is specified, `x-migrations-table-engine` also should be specified. See the docs regarding [replicated table engines](https://clickhouse.tech/docs/en/engines/table-engines/mergetree-family/replication/#table_engines-replication).
  * When `x-cluster-name` is specified, only the `schema_migrations` table is replicated across the cluster. You still need to write your migrations so that the application tables are replicated within the cluster.


# cockroachdb

`cockroachdb://user:password@host:port/dbname?query` (`cockroach://`, and `crdb-postgres://` work, too)

| URL Query  | WithInstance Config | Description |
|------------|---------------------|-------------|
| `x-migrations-table` | `MigrationsTable` | Name of the migrations table |
| `x-lock-table` | `LockTable` | Name of the table which maintains the migration lock |
| `x-force-lock` | `ForceLock` | Force lock acquisition to fix faulty migrations which may not have released the schema lock (Boolean, default is `false`) |
| `dbname` | `DatabaseName` | The name of the database to connect to |
| `user` | | The user to sign in as |
| `password` | | The user's password |
| `host` | | The host to connect to. Values that start with / are for unix domain sockets. (default is localhost) |
| `port` | | The port to bind to. (default is 5432) |
| `connect_timeout` | | Maximum wait for connection, in seconds. Zero or not specified means wait indefinitely. |
| `sslcert` | | Cert file location. The file must contain PEM encoded data. |
| `sslkey` | | Key file location. The file must contain PEM encoded data. |
| `sslrootcert` | | The location of the root certificate file. The file must contain PEM encoded data. |
| `sslmode` | | Whether or not to use SSL (disable\|require\|verify-ca\|verify-full) |


# MongoDB

* Driver work with mongo through [db.runCommands](https://docs.mongodb.com/manual/reference/command/)
* Migrations support json format. It contains array of commands for `db.runCommand`. Every command is executed in separate request to database
* All keys have to be in quotes `"`
* [Examples](./examples)

# Usage

`mongodb://user:password@host:port/dbname?query` (`mongodb+srv://` also works, but behaves a bit differently. See [docs](https://docs.mongodb.com/manual/reference/connection-string/#dns-seedlist-connection-format) for more information)

| URL Query  | WithInstance Config | Description |
|------------|---------------------|-------------|
| `x-migrations-collection` | `MigrationsCollection` | Name of the migrations collection |
| `x-transaction-mode` | `TransactionMode` | If set to `true` wrap commands in [transaction](https://docs.mongodb.com/manual/core/transactions). Available only for replica set. Driver is using [strconv.ParseBool](https://golang.org/pkg/strconv/#ParseBool) for parsing|
| `x-advisory-locking` | `true` | Feature flag for advisory locking, if set to false, disable advisory locking |
| `x-advisory-lock-collection` | `migrate_advisory_lock` | The name of the collection to use for advisory locking.|
| `x-advisory-lock-timeout` | `15` | The max time in seconds that migrate will wait to acquire a lock before failing. |
| `x-advisory-lock-timeout-interval` | `10` | The max time in seconds between attempts to acquire the advisory lock, the lock is attempted to be acquired using an exponential backoff algorithm. |
| `dbname` | `DatabaseName` | The name of the database to connect to |
| `user` | | The user to sign in as. Can be omitted |
| `password` | | The user's password. Can be omitted |
| `host` | | The host to connect to |
| `port` | | The port to bind to |


# MySQL

`mysql://user:password@tcp(host:port)/dbname?query`

| URL Query  | WithInstance Config | Description |
|------------|---------------------|-------------|
| `x-migrations-table` | `MigrationsTable` | Name of the migrations table |
| `x-no-lock` | `NoLock` | Set to `true` to skip `GET_LOCK`/`RELEASE_LOCK` statements. Useful for [multi-master MySQL flavors](https://www.percona.com/doc/percona-xtradb-cluster/LATEST/features/pxc-strict-mode.html#explicit-table-locking). Only run migrations from one host when this is enabled. |
| `dbname` | `DatabaseName` | The name of the database to connect to |
| `user` | | The user to sign in as |
| `password` | | The user's password |
| `host` | | The host to connect to. |
| `port` | | The port to bind to. |
| `tls`  | | TLS / SSL encrypted connection parameter; see [go-sql-driver](https://github.com/go-sql-driver/mysql#tls). Use any name (e.g. `migrate`) if you want to use a custom TLS config (`x-tls-` queries). |
| `x-tls-ca` | | The location of the CA (certificate authority) file. |
| `x-tls-cert` | | The location of the client certicicate file. Must be used with `x-tls-key`. |
| `x-tls-key` | | The location of the private key file. Must be used with `x-tls-cert`. |
| `x-tls-insecure-skip-verify` | | Whether or not to use SSL (true\|false) |

## Use with existing client

If you use the MySQL driver with existing database client, you must create the client with parameter `multiStatements=true`:

```go
package main

import (
    "database/sql"

    _ "github.com/go-sql-driver/mysql"
    "github.com/golang-migrate/migrate/v4"
    "github.com/golang-migrate/migrate/v4/database/mysql"
    _ "github.com/golang-migrate/migrate/v4/source/file"
)

func main() {
    db, _ := sql.Open("mysql", "user:password@tcp(host:port)/dbname?multiStatements=true")
    driver, _ := mysql.WithInstance(db, &mysql.Config{})
    m, _ := migrate.NewWithDatabaseInstance(
        "file:///migrations",
        "mysql",
        driver,
    )

    m.Steps(2)
}
```

## Upgrading from v1

1. Write down the current migration version from schema_migrations
1. `DROP TABLE schema_migrations`
2. Wrap your existing migrations in transactions ([BEGIN/COMMIT](https://dev.mysql.com/doc/refman/5.7/en/commit.html)) if you use multiple statements within one migration.
3. Download and install the latest migrate version.
4. Force the current migration version with `migrate force <current_version>`.


# pgx

`pgx://user:password@host:port/dbname?query`

| URL Query  | WithInstance Config | Description |
|------------|---------------------|-------------|
| `x-migrations-table` | `MigrationsTable` | Name of the migrations table |
| `x-migrations-table-quoted` | `MigrationsTableQuoted` | By default, migrate quotes the migration table for SQL injection safety reasons. This option disable quoting and naively checks that you have quoted the migration table name. e.g. `"my_schema"."schema_migrations"` |
| `x-statement-timeout` | `StatementTimeout` | Abort any statement that takes more than the specified number of milliseconds |
| `x-multi-statement` | `MultiStatementEnabled` | Enable multi-statement execution (default: false) |
| `x-multi-statement-max-size` | `MultiStatementMaxSize` | Maximum size of single statement in bytes (default: 10MB) |
| `dbname` | `DatabaseName` | The name of the database to connect to |
| `search_path` | | This variable specifies the order in which schemas are searched when an object is referenced by a simple name with no schema specified. |
| `user` | | The user to sign in as |
| `password` | | The user's password |
| `host` | | The host to connect to. Values that start with / are for unix domain sockets. (default is localhost) |
| `port` | | The port to bind to. (default is 5432) |
| `fallback_application_name` | | An application_name to fall back to if one isn't provided. |
| `connect_timeout` | | Maximum wait for connection, in seconds. Zero or not specified means wait indefinitely. |
| `sslcert` | | Cert file location. The file must contain PEM encoded data. |
| `sslkey` | | Key file location. The file must contain PEM encoded data. |
| `sslrootcert` | | The location of the root certificate file. The file must contain PEM encoded data. |
| `sslmode` | | Whether or not to use SSL (disable\|require\|verify-ca\|verify-full) |

## Upgrading from v1

1. Write down the current migration version from schema_migrations
1. `DROP TABLE schema_migrations`
2. Wrap your existing migrations in transactions ([BEGIN/COMMIT](https://www.postgresql.org/docs/current/static/transaction-iso.html)) if you use multiple statements within one migration.
3. Download and install the latest migrate version.
4. Force the current migration version with `migrate force <current_version>`.

## Multi-statement mode

In PostgreSQL running multiple SQL statements in one `Exec` executes them inside a transaction. Sometimes this
behavior is not desirable because some statements can be only run outside of transaction (e.g.
`CREATE INDEX CONCURRENTLY`). If you want to use `CREATE INDEX CONCURRENTLY` without activating multi-statement mode
you have to put such statements in a separate migration files.


# postgres

`postgres://user:password@host:port/dbname?query` (`postgresql://` works, too)

| URL Query  | WithInstance Config | Description |
|------------|---------------------|-------------|
| `x-migrations-table` | `MigrationsTable` | Name of the migrations table |
| `x-migrations-table-quoted` | `MigrationsTableQuoted` | By default, migrate quotes the migration table for SQL injection safety reasons. This option disable quoting and naively checks that you have quoted the migration table name. e.g. `"my_schema"."schema_migrations"` |
| `x-statement-timeout` | `StatementTimeout` | Abort any statement that takes more than the specified number of milliseconds |
| `x-multi-statement` | `MultiStatementEnabled` | Enable multi-statement execution (default: false) |
| `x-multi-statement-max-size` | `MultiStatementMaxSize` | Maximum size of single statement in bytes (default: 10MB) |
| `dbname` | `DatabaseName` | The name of the database to connect to |
| `search_path` | | This variable specifies the order in which schemas are searched when an object is referenced by a simple name with no schema specified. |
| `user` | | The user to sign in as |
| `password` | | The user's password |
| `host` | | The host to connect to. Values that start with / are for unix domain sockets. (default is localhost) |
| `port` | | The port to bind to. (default is 5432) |
| `fallback_application_name` | | An application_name to fall back to if one isn't provided. |
| `connect_timeout` | | Maximum wait for connection, in seconds. Zero or not specified means wait indefinitely. |
| `sslcert` | | Cert file location. The file must contain PEM encoded data. |
| `sslkey` | | Key file location. The file must contain PEM encoded data. |
| `sslrootcert` | | The location of the root certificate file. The file must contain PEM encoded data. |
| `sslmode` | | Whether or not to use SSL (disable\|require\|verify-ca\|verify-full) |

## Upgrading from v1

1. Write down the current migration version from schema_migrations
1. `DROP TABLE schema_migrations`
2. Wrap your existing migrations in transactions ([BEGIN/COMMIT](https://www.postgresql.org/docs/current/static/transaction-iso.html)) if you use multiple statements within one migration.
3. Download and install the latest migrate version.
4. Force the current migration version with `migrate force <current_version>`.

## Multi-statement mode

In PostgreSQL running multiple SQL statements in one `Exec` executes them inside a transaction. Sometimes this
behavior is not desirable because some statements can be only run outside of transaction (e.g.
`CREATE INDEX CONCURRENTLY`). If you want to use `CREATE INDEX CONCURRENTLY` without activating multi-statement mode
you have to put such statements in a separate migration files.


# Redshift

`redshift://user:password@host:port/dbname?query`

| URL Query  | WithInstance Config | Description |
|------------|---------------------|-------------|
| `x-migrations-table` | `MigrationsTable` | Name of the migrations table |
| `dbname` | `DatabaseName` | The name of the database to connect to |
| `search_path` | | This variable specifies the order in which schemas are searched when an object is referenced by a simple name with no schema specified. |
| `user` | | The user to sign in as |
| `password` | | The user's password |
| `host` | | The host to connect to. Values that start with / are for unix domain sockets. (default is localhost) |
| `port` | | The port to bind to. (default is 5439) |
| `fallback_application_name` | | An application_name to fall back to if one isn't provided. |
| `connect_timeout` | | Maximum wait for connection, in seconds. Zero or not specified means wait indefinitely. |
| `sslcert` | | Cert file location. The file must contain PEM encoded data. |
| `sslkey` | | Key file location. The file must contain PEM encoded data. |
| `sslrootcert` | | The location of the root certificate file. The file must contain PEM encoded data. |
| `sslmode` | | Whether or not to use SSL (disable\|require\|verify-ca\|verify-full) |

Redshift is PostgreSQL compatible but has some specific features (or lack thereof) that require slightly different behavior.


# Google Cloud Spanner

## Usage

See [Google Spanner Documentation](https://cloud.google.com/spanner/docs) for
more details.

The DSN must be given in the following format.

`spanner://projects/{projectId}/instances/{instanceId}/databases/{databaseName}?param=true`

as described in [README.md#database-urls](../../README.md#database-urls)

| Param | WithInstance Config | Description |
| ----- | ------------------- | ----------- |
| `x-migrations-table` | `MigrationsTable` | Name of the migrations table |
| `x-clean-statements` | `CleanStatements` | Whether to parse and clean DDL statements before running migration towards Spanner (Required for comments and multiple statements) |
| `url` | `DatabaseName` | The full path to the Spanner database resource. If provided as part of `Config` it must not contain a scheme or query string to match the format `projects/{projectId}/instances/{instanceId}/databases/{databaseName}`|
| `projectId` || The Google Cloud Platform project id
| `instanceId` || The id of the instance running Spanner
| `databaseName` || The name of the Spanner database

> **Note:** Google Cloud Spanner migrations can take a considerable amount of
> time. The migrations provided as part of the example take about 6 minutes to
> run on a small instance.
>
> ```log
> 1481574547/u create_users_table (21.354507597s)
> 1496539702/u add_city_to_users (41.647359754s)
> 1496601752/u add_index_on_user_emails (2m12.155787369s)
> 1496602638/u create_books_table (2m30.77299181s)

## DDL with comments

At the moment the GCP Spanner backed does not seem to allow for comments (See https://issuetracker.google.com/issues/159730604)
so in order to be able to use migration with DDL containing comments `x-clean-stamements` is required

## Multiple statements

In order to be able to use more than 1 DDL statement in the same migration file, the file has to be parsed and therefore the `x-clean-statements` flag is required

## Testing

To unit test the `spanner` driver, `SPANNER_DATABASE` needs to be set. You'll
need to sign-up to Google Cloud Platform (GCP) and have a running Spanner
instance since it is not possible to run Google Spanner outside GCP.


# sqlite

`sqlite://path/to/database?query`

Unlike other migrate database drivers, the sqlite driver will automatically wrap each migration in an implicit transaction by default.  Migrations must not contain explicit `BEGIN` or `COMMIT` statements.  This behavior may change in a future major release.  (See below for a workaround.)

The auxiliary query parameters listed below may be supplied to tailor migrate behavior.  All auxiliary query parameters are optional.

| URL Query  | WithInstance Config | Description |
|------------|---------------------|-------------|
| `x-migrations-table` | `MigrationsTable` | Name of the migrations table.  Defaults to `schema_migrations`. |
| `x-no-tx-wrap` | `NoTxWrap` | Disable implicit transactions when `true`.  Migrations may, and should, contain explicit `BEGIN` and `COMMIT` statements. |

## Notes

* Uses the `modernc.org/sqlite` sqlite db driver (pure Go)
  * Has [limited `GOOS` and `GOARCH` support](https://pkg.go.dev/modernc.org/sqlite?utm_source=godoc#hdr-Supported_platforms_and_architectures)


# sqlite3

`sqlite3://path/to/database?query`

Unlike other migrate database drivers, the sqlite3 driver will automatically wrap each migration in an implicit transaction by default.  Migrations must not contain explicit `BEGIN` or `COMMIT` statements.  This behavior may change in a future major release.  (See below for a workaround.)

Refer to [upstream documentation](https://github.com/mattn/go-sqlite3/blob/master/README.md#connection-string) for a complete list of query parameters supported by the sqlite3 database driver.  The auxiliary query parameters listed below may be supplied to tailor migrate behavior.  All auxiliary query parameters are optional.

| URL Query  | WithInstance Config | Description |
|------------|---------------------|-------------|
| `x-migrations-table` | `MigrationsTable` | Name of the migrations table.  Defaults to `schema_migrations`. |
| `x-no-tx-wrap` | `NoTxWrap` | Disable implicit transactions when `true`.  Migrations may, and should, contain explicit `BEGIN` and `COMMIT` statements. |

## Notes

* Uses the `github.com/mattn/go-sqlite3` sqlite db driver (cgo)


# file

`file:///absolute/path`
`file://relative/path`


# go_bindata

## Usage

### Read bindata with NewWithSourceInstance

```shell
go get -u github.com/jteeuwen/go-bindata/...
cd examples/migrations && go-bindata -pkg migrations .
```

```go
import (
  "github.com/golang-migrate/migrate/v4"
  "github.com/golang-migrate/migrate/v4/source/go_bindata"
  "github.com/golang-migrate/migrate/v4/source/go_bindata/examples/migrations"
)

func main() {
  // wrap assets into Resource
  s := bindata.Resource(migrations.AssetNames(),
    func(name string) ([]byte, error) {
      return migrations.Asset(name)
    })

  d, err := bindata.WithInstance(s)
  m, err := migrate.NewWithSourceInstance("go-bindata", d, "database://foobar")
  m.Up() // run your migrations and handle the errors above of course
}
```

### Read bindata with URL (todo)

This will restore the assets in a tmp directory and then
proxy to source/file. go-bindata must be in your `$PATH`.

```
migrate -source go-bindata://examples/migrations/bindata.go
```


# Google Cloud Storage

## Import

```go
import (
  _ "github.com/golang-migrate/migrate/v4/source/google_cloud_storage"
 )
 ```

## Connection String

`gcs://<bucket>/<prefix>`


# httpfs

## Usage

This package could be used to create new migration source drivers that uses
`http.FileSystem` to read migration files.

Struct `httpfs.PartialDriver` partly implements the `source.Driver` interface. It has all
the methods except for `Open()`. Embedding this struct and adding `Open()` method
allows users of this package to create new migration sources. Example:

```go
struct mydriver {
        httpfs.PartialDriver
}

func (d *mydriver) Open(url string) (source.Driver, error) {
	var fs http.FileSystem
	var path string
	var ds mydriver

	// acquire fs and path from url
	// set-up ds if necessary

	if err := ds.Init(fs, path); err != nil {
		return nil, err
	}
	return &ds, nil
}
```

This package also provides a simple `source.Driver` implementation that works
with `http.FileSystem` provided by the user of this package. It is created with
`httpfs.New()` call.

Example of using `http.Dir()` to read migrations from `sql` directory:

```go
	src, err := httpfs.New(http.Dir("sql"))
	if err != nil {
		// do something
	}
	m, err := migrate.NewWithSourceInstance("httpfs", src, "database://url")
	if err != nil {
		// do something
	}
        err = m.Up()
	...
```


# iofs

https://pkg.go.dev/github.com/golang-migrate/migrate/v4/source/iofs


Copyright 2010, 2019 The Go Authors.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

    * Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following disclaimer
in the documentation and/or other materials provided with the
distribution.
    * Neither the name of Google Inc. nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


# Case conversion

This package contains two functions:
- `Camel` copied from the `github.com/golang/protobuf/protoc-gen-go/generator` package.
- `JSONCamelCase` copied from the `github.com/protocolbuffers/protobuf-go/internal/strs` package.

Both these modules are licensed by The Go Authors, as reflected in this package's [LICENSE.md].


# Description

This is a sample chat program implemented using PostgreSQL's listen/notify
functionality with pgx.

Start multiple instances of this program connected to the same database to chat
between them.

## Connection configuration

The database connection is configured via DATABASE_URL and standard PostgreSQL environment variables (PGHOST, PGUSER, etc.)

You can either export them then run chat:

    export PGHOST=/private/tmp
    ./chat

Or you can prefix the chat execution with the environment variables:

    PGHOST=/private/tmp ./chat


# Description

This is a sample todo list implemented using pgx as the connector to a
PostgreSQL data store.

# Usage

Create a PostgreSQL database and run structure.sql into it to create the
necessary data schema.

Example:

    createdb todo
    psql todo < structure.sql

Build todo:

    go build

## Connection configuration

The database connection is configured via DATABASE_URL and standard PostgreSQL environment variables (PGHOST, PGUSER, etc.)

You can either export them then run todo:

    export PGDATABASE=todo
    ./todo list

Or you can prefix the todo execution with the environment variables:

    PGDATABASE=todo ./todo list

## Add a todo item

    ./todo add 'Learn go'

## List tasks

    ./todo list

## Update a task

    ./todo update 1 'Learn more go'

## Delete a task

    ./todo remove 1

# Example Setup and Execution

    jack@hk-47~/dev/go/src/github.com/jackc/pgx/examples/todo$ createdb todo
    jack@hk-47~/dev/go/src/github.com/jackc/pgx/examples/todo$ psql todo < structure.sql
    Expanded display is used automatically.
    Timing is on.
    CREATE TABLE
    Time: 6.363 ms
    jack@hk-47~/dev/go/src/github.com/jackc/pgx/examples/todo$ go build
    jack@hk-47~/dev/go/src/github.com/jackc/pgx/examples/todo$ export PGDATABASE=todo
    jack@hk-47~/dev/go/src/github.com/jackc/pgx/examples/todo$ ./todo list
    jack@hk-47~/dev/go/src/github.com/jackc/pgx/examples/todo$ ./todo add 'Learn Go'
    jack@hk-47~/dev/go/src/github.com/jackc/pgx/examples/todo$ ./todo list
    1. Learn Go
    jack@hk-47~/dev/go/src/github.com/jackc/pgx/examples/todo$ ./todo update 1 'Learn more Go'
    jack@hk-47~/dev/go/src/github.com/jackc/pgx/examples/todo$ ./todo list
    1. Learn more Go
    jack@hk-47~/dev/go/src/github.com/jackc/pgx/examples/todo$ ./todo remove 1
    jack@hk-47~/dev/go/src/github.com/jackc/pgx/examples/todo$ ./todo list


# Description

This is a sample REST URL shortener service implemented using pgx as the connector to a PostgreSQL data store.

# Usage

Create a PostgreSQL database and run structure.sql into it to create the necessary data schema.

Configure the database connection with `DATABASE_URL` or standard PostgreSQL (`PG*`) environment variables or

Run main.go:

```
go run main.go
```

## Create or Update a Shortened URL

```
curl -X PUT -d 'http://www.google.com' http://localhost:8080/google
```

## Get a Shortened URL

```
curl http://localhost:8080/google
```

## Delete a Shortened URL

```
curl -X DELETE http://localhost:8080/google
```


# pgio

Package pgio is a low-level toolkit building messages in the PostgreSQL wire protocol.

pgio provides functions for appending integers to a []byte while doing byte
order conversion.


# xxhash

VENDORED: Go to [github.com/cespare/xxhash](https://github.com/cespare/xxhash) for original package.

xxhash is a Go implementation of the 64-bit [xxHash] algorithm, XXH64. This is a
high-quality hashing algorithm that is much faster than anything in the Go
standard library.

This package provides a straightforward API:

```
func Sum64(b []byte) uint64
func Sum64String(s string) uint64
type Digest struct{ ... }
    func New() *Digest
```

The `Digest` type implements hash.Hash64. Its key methods are:

```
func (*Digest) Write([]byte) (int, error)
func (*Digest) WriteString(string) (int, error)
func (*Digest) Sum64() uint64
```

The package is written with optimized pure Go and also contains even faster
assembly implementations for amd64 and arm64. If desired, the `purego` build tag
opts into using the Go code even on those architectures.

[xxHash]: http://cyan4973.github.io/xxHash/

## Compatibility

This package is in a module and the latest code is in version 2 of the module.
You need a version of Go with at least "minimal module compatibility" to use
github.com/cespare/xxhash/v2:

* 1.9.7+ for Go 1.9
* 1.10.3+ for Go 1.10
* Go 1.11 or later

I recommend using the latest release of Go.

## Benchmarks

Here are some quick benchmarks comparing the pure-Go and assembly
implementations of Sum64.

| input size | purego    | asm       |
| ---------- | --------- | --------- |
| 4 B        |  1.3 GB/s |  1.2 GB/s |
| 16 B       |  2.9 GB/s |  3.5 GB/s |
| 100 B      |  6.9 GB/s |  8.1 GB/s |
| 4 KB       | 11.7 GB/s | 16.7 GB/s |
| 10 MB      | 12.0 GB/s | 17.3 GB/s |

These numbers were generated on Ubuntu 20.04 with an Intel Xeon Platinum 8252C
CPU using the following commands under Go 1.19.2:

```
benchstat <(go test -tags purego -benchtime 500ms -count 15 -bench 'Sum64$')
benchstat <(go test -benchtime 500ms -count 15 -bench 'Sum64$')
```

## Projects using this package

- [InfluxDB](https://github.com/influxdata/influxdb)
- [Prometheus](https://github.com/prometheus/prometheus)
- [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics)
- [FreeCache](https://github.com/coocood/freecache)
- [FastCache](https://github.com/VictoriaMetrics/fastcache)


Client Configuration Support for GRPC
=====================================

This library provides high level configuration machinery to construct client
channels and load balance between them.

Each `grpc_channel` is created with a `Resolver`. It is the resolver's duty
to resolve a name into a set of arguments for the channel. Such arguments
might include:

- a list of (ip, port) addresses to connect to
- a load balancing policy to decide which server to send a request to
- a set of filters to mutate outgoing requests (say, by adding metadata)

The resolver provides this data as a stream of `grpc_channel_args` objects to
the channel. We represent arguments as a stream so that they can be changed
by the resolver during execution, by reacting to external events (such as
new service configuration data being pushed to some store).

Load Balancing
--------------

Load balancing configuration is provided by a `LoadBalancingPolicy` object.

The primary job of the load balancing policies is to pick a target server
given only the initial metadata for a request. It does this by providing
a `ConnectedSubchannel` object to the owning channel.

Sub-Channels
------------

A sub-channel provides a connection to a server for a client channel. It has a
connectivity state like a regular channel, and so can be connected or
disconnected. This connectivity state can be used to inform load balancing
decisions (for example, by avoiding disconnected backends).

Configured sub-channels are fully setup to participate in the grpc data plane.
Their behavior is specified by a set of grpc channel filters defined at their
construction. To customize this behavior, transports build
`ClientChannelFactory` objects, which customize construction arguments for
concrete subchannel instances.

Naming for GRPC
===============

See [/doc/naming.md](gRPC name resolution).


# Binder transport for cross process IPC on Android

EXPERIMENTAL. API stability not guaranteed.

This transport implements
[BinderChannel for native cross-process communication on Android](https://github.com/grpc/proposal/blob/master/L73-java-binderchannel.md) and enables C++/Java cross-process communication on Android with gRPC.

Tests: https://github.com/grpc/grpc/tree/master/test/core/transport/binder/

Example apps: https://github.com/grpc/grpc/tree/master/examples/android/binder/java/io/grpc/binder/cpp


CHTTP2 - gRPC's implementation of a HTTP2 based transport


# Customization Points

The custom directory is an injection point for custom user configurations.

## Header `gmock-port.h`

The following macros can be defined:

### Flag related macros:

*   `GMOCK_DECLARE_bool_(name)`
*   `GMOCK_DECLARE_int32_(name)`
*   `GMOCK_DECLARE_string_(name)`
*   `GMOCK_DEFINE_bool_(name, default_val, doc)`
*   `GMOCK_DEFINE_int32_(name, default_val, doc)`
*   `GMOCK_DEFINE_string_(name, default_val, doc)`
*   `GMOCK_FLAG_GET(flag_name)`
*   `GMOCK_FLAG_SET(flag_name, value)`


# Customization Points

The custom directory is an injection point for custom user configurations.

## Header `gtest.h`

### The following macros can be defined:

*   `GTEST_OS_STACK_TRACE_GETTER_` - The name of an implementation of
    `OsStackTraceGetterInterface`.
*   `GTEST_CUSTOM_TEMPDIR_FUNCTION_` - An override for `testing::TempDir()`. See
    `testing::TempDir` for semantics and signature.

## Header `gtest-port.h`

The following macros can be defined:

### Logging:

*   `GTEST_LOG_(severity)`
*   `GTEST_CHECK_(condition)`
*   Functions `LogToStderr()` and `FlushInfoLog()` have to be provided too.

### Threading:

*   `GTEST_HAS_NOTIFICATION_` - Enabled if Notification is already provided.
*   `GTEST_HAS_MUTEX_AND_THREAD_LOCAL_` - Enabled if `Mutex` and `ThreadLocal`
    are already provided. Must also provide `GTEST_DECLARE_STATIC_MUTEX_(mutex)`
    and `GTEST_DEFINE_STATIC_MUTEX_(mutex)`
*   `GTEST_EXCLUSIVE_LOCK_REQUIRED_(locks)`
*   `GTEST_LOCK_EXCLUDED_(locks)`

### Underlying library support features

*   `GTEST_HAS_CXXABI_H_`

### Exporting API symbols:

*   `GTEST_API_` - Specifier for exported symbols.

## Header `gtest-printers.h`

*   See documentation at `gtest/gtest-printers.h` for details on how to define a
    custom printer.


Run
===

```sh
siege -t60m -c200  http://127.0.0.1:8080/test
```


# HTTP JSON Error Schema

The `error.proto` represents the HTTP-JSON schema used by Google APIs to convey
error payloads as described by https://cloud.google.com/apis/design/errors#http_mapping.
This package is for internal parsing logic only and should not be used in any
other context.

## Regeneration

To regenerate the protobuf Go code you will need the following:

* A local copy of [googleapis], the absolute path to which should be exported to
the environment variable `GOOGLEAPIS`
* The protobuf compiler [protoc]
* The Go [protobuf plugin]
* The [goimports] tool

From this directory run the following command:
```sh
protoc -I $GOOGLEAPIS -I. --go_out=. --go_opt=module=github.com/googleapis/gax-go/v2/apierror/internal/proto error.proto
goimports -w .
```

Note: the `module` plugin option ensures the generated code is placed in this
directory, and not in several nested directories defined by `go_package` option.

[googleapis]: https://github.com/googleapis/googleapis
[protoc]: https://github.com/protocolbuffers/protobuf#protocol-compiler-installation
[protobuf plugin]: https://developers.google.com/protocol-buffers/docs/reference/go-generated
[goimports]: https://pkg.go.dev/golang.org/x/tools/cmd/goimports


# pgfortune

pgfortune is a mock PostgreSQL server that responds to every query with a fortune.

## Installation

Install `fortune` and `cowsay`. They should be available in any Unix package manager (apt, yum, brew, etc.)

```
go get -u github.com/jackc/pgproto3/example/pgfortune
```

## Usage

```
$ pgfortune
```

By default pgfortune listens on 127.0.0.1:15432 and responds to queries with `fortune | cowsay -f elephant`. These are
configurable with the `listen` and `response-command` arguments respectively.

While `pgfortune` is running connect to it with `psql`.

```
$ psql -h 127.0.0.1 -p 15432
Timing is on.
Null display is "∅".
Line style is unicode.
psql (11.5, server 0.0.0)
Type "help" for help.

jack@127.0.0.1:15432 jack=# select foo;
                   fortune
─────────────────────────────────────────────
  _________________________________________ ↵
 / Ships are safe in harbor, but they were \↵
 \ never meant to stay there.              /↵
  ----------------------------------------- ↵
  \     /\  ___  /\                         ↵
   \   // \/   \/ \\                        ↵
      ((    O O    ))                       ↵
       \\ /     \ //                        ↵
        \/  | |  \/                         ↵
         |  | |  |                          ↵
         |  | |  |                          ↵
         |   o   |                          ↵
         | |   | |                          ↵
         |m|   |m|                          ↵

(1 row)

Time: 28.161 ms
```


# Resolver

Implementations of various name resolution schemes.
See the [naming spec](/doc/naming.md).


chttp2 transport plugin - implements grpc over http2

Used by chttp2/{client,server}/{insecure,secure} plugins to implement most of
their functionality