skopeo Documentation

Technical Documentation: containers/skopeo

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

skopeo is a command line utility that performs various operations on container images and image repositories.

skopeo does not require the user to be running as root to do most of its operations.

skopeo does not require a daemon to be running to perform its operations.

skopeo can work with OCI images as well as the original Docker v2 images.

Skopeo works with API V2 container image registries such as docker.io and quay.io registries, private registries, local directories and local OCI-layout directories. Skopeo can perform operations which consist of:

• Copying an image from and to various storage mechanisms.
  For example you can copy images from one registry to another, without requiring privilege.
• Inspecting a remote image showing its properties including its layers, without requiring you to pull the image to the host.
• Deleting an image from an image repository.
• Syncing an external image repository to an internal registry for air-gapped deployments.
• When required by the repository, skopeo can pass the appropriate credentials and certificates for authentication.

Skopeo operates on the following image and repository types:

• containers-storage:docker-reference
  An image located in a local containers/storage image store. Both the location and image store are specified in /etc/containers/storage.conf. (This is the backend for Podman, CRI-O, Buildah and friends)

• dir:path
  An existing local directory path storing the manifest, layer tarballs and signatures as individual files. This is a non-standardized format, primarily useful for debugging or noninvasive container inspection.

• docker://docker-reference
  An image in a registry implementing the "Docker Registry HTTP API V2". By default, uses the authorization state in $XDG_RUNTIME_DIR/containers/auth.json, which is set using skopeo login.

• docker-archive:path[:docker-reference]
  An image is stored in a docker save-formatted file. docker-reference is only used when creating such a file, and it must not contain a digest.

• docker-daemon:docker-reference
  An image docker-reference stored in the docker daemon internal storage. docker-reference must contain either a tag or a digest. Alternatively, when reading images, the format can also be docker-daemon:algo:digest (an image ID).

• oci:path:tag
  An image tag in a directory compliant with "Open Container Image Layout Specification" at path.

[Obtaining skopeo](./install.md) Copy Chapter

For a detailed description how to install or build skopeo, see
install.md.

Skopeo is also available as a Container Image on quay.io. For more information, see the Skopeo Image page.

Skopeo has no separate project website. This repository, and the container images
documented above, are the only upstream builds; users can also use packages from
distributions they trust, as documented in install.md. Other
websites presenting themselves as the home of skopeo or offering their own skopeo
downloads are not affiliated with the project.

Inspecting a repository Copy Chapter

skopeo is able to inspect a repository on a container registry and fetch images layers.
The inspect command fetches the repository's manifest and it is able to show you a docker inspect-like
json output about a whole repository or a tag. This tool, in contrast to docker inspect, helps you gather useful information about
a repository or a tag before pulling it (using disk space). The inspect command can show you which tags are available for the given
repository, the labels the image has, the creation date and operating system of the image and more.

Examples:

Show properties of fedora:latest

$ skopeo inspect docker://registry.fedoraproject.org/fedora:latest
{
    "Name": "registry.fedoraproject.org/fedora",
    "Digest": "sha256:0f65bee641e821f8118acafb44c2f8fe30c2fc6b9a2b3729c0660376391aa117",
    "RepoTags": [
        "34-aarch64",
        "34",
        "latest",
        ...
    ],
    "Created": "2022-11-24T13:54:18Z",
    "DockerVersion": "1.10.1",
    "Labels": {
        "license": "MIT",
        "name": "fedora",
        "vendor": "Fedora Project",
        "version": "37"
    },
    "Architecture": "amd64",
    "Os": "linux",
    "Layers": [
        "sha256:2a0fc6bf62e155737f0ace6142ee686f3c471c1aab4241dc3128904db46288f0"
    ],
    "LayersData": [
        {
            "MIMEType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
            "Digest": "sha256:2a0fc6bf62e155737f0ace6142ee686f3c471c1aab4241dc3128904db46288f0",
            "Size": 71355009,
            "Annotations": null
        }
    ],
    "Env": [
        "DISTTAG=f37container",
        "FGC=f37",
        "container=oci"
    ]
}

Show container configuration from `fedora:latest`

$ skopeo inspect --config docker://registry.fedoraproject.org/fedora:latest  | jq
{
  "created": "2020-04-29T06:48:16Z",
  "architecture": "amd64",
  "os": "linux",
  "config": {
    "Env": [
      "DISTTAG=f32container",
      "FGC=f32",
      "container=oci"
    ],
    "Cmd": [
      "/bin/bash"
    ],
    "Labels": {
      "license": "MIT",
      "name": "fedora",
      "vendor": "Fedora Project",
      "version": "32"
    }
  },
  "rootfs": {
    "type": "layers",
    "diff_ids": [
      "sha256:a4c0fa2b217d3fd63d51e55a6fd59432e543d499c0df2b1acd48fbe424f2ddd1"
    ]
  },
  "history": [
    {
      "created": "2020-04-29T06:48:16Z",
      "comment": "Created by Image Factory"
    }
  ]
}

Show unverified image's digest

$ skopeo inspect docker://registry.fedoraproject.org/fedora:latest | jq '.Digest'
"sha256:655721ff613ee766a4126cb5e0d5ae81598e1b0c3bcf7017c36c4d72cb092fe9"

Copying images Copy Chapter

skopeo can copy container images between various storage mechanisms, including:

• Container registries

  • The Quay, Docker Hub, OpenShift, GCR, Artifactory ...

• Container Storage backends

  • github.com/containers/storage (Backend for Podman, CRI-O, Buildah and friends)

  • Docker daemon storage

• Local directories

• Local OCI-layout directories

$ skopeo copy docker://quay.io/buildah/stable docker://registry.internal.company.com/buildah
$ skopeo copy oci:busybox_ocilayout:latest dir:existingemptydirectory

Deleting images Copy Chapter

$ skopeo delete docker://localhost:5000/imagename:latest

Syncing registries Copy Chapter

$ skopeo sync --src docker --dest dir registry.example.com/busybox /media/usb

Authenticating to a registry Copy Chapter

Private registries with authentication

skopeo uses credentials from the --creds (for skopeo inspect|delete) or --src-creds|--dest-creds (for skopeo copy) flags, if set; otherwise it uses configuration set by skopeo login, podman login, buildah login, or docker login.

$ skopeo login --username USER myregistrydomain.com:5000
Password:
$ skopeo inspect docker://myregistrydomain.com:5000/busybox
{"Tag":"latest","Digest":"sha256:473bb2189d7b913ed7187a33d11e743fdc2f88931122a44d91a301b64419f092","RepoTags":["latest"],"Comment":"","Created":"2016-01-15T18:06:41.282540103Z","ContainerConfig":{"Hostname":"aded96b43f48","Domainname":"","User":"","AttachStdin":false,"AttachStdout":false,"AttachStderr":false,"Tty":false,"OpenStdin":false,"StdinOnce":false,"Env":null,"Cmd":["/bin/sh","-c","#(nop) CMD [\"sh\"]"],"Image":"9e77fef7a1c9f989988c06620dabc4020c607885b959a2cbd7c2283c91da3e33","Volumes":null,"WorkingDir":"","Entrypoint":null,"OnBuild":null,"Labels":null},"DockerVersion":"1.8.3","Author":"","Config":{"Hostname":"aded96b43f48","Domainname":"","User":"","AttachStdin":false,"AttachStdout":false,"AttachStderr":false,"Tty":false,"OpenStdin":false,"StdinOnce":false,"Env":null,"Cmd":["sh"],"Image":"9e77fef7a1c9f989988c06620dabc4020c607885b959a2cbd7c2283c91da3e33","Volumes":null,"WorkingDir":"","Entrypoint":null,"OnBuild":null,"Labels":null},"Architecture":"amd64","Os":"linux"}
$ skopeo logout myregistrydomain.com:5000

Using --creds directly

$ skopeo inspect --creds=testuser:testpassword docker://myregistrydomain.com:5000/busybox
{"Tag":"latest","Digest":"sha256:473bb2189d7b913ed7187a33d11e743fdc2f88931122a44d91a301b64419f092","RepoTags":["latest"],"Comment":"","Created":"2016-01-15T18:06:41.282540103Z","ContainerConfig":{"Hostname":"aded96b43f48","Domainname":"","User":"","AttachStdin":false,"AttachStdout":false,"AttachStderr":false,"Tty":false,"OpenStdin":false,"StdinOnce":false,"Env":null,"Cmd":["/bin/sh","-c","#(nop) CMD [\"sh\"]"],"Image":"9e77fef7a1c9f989988c06620dabc4020c607885b959a2cbd7c2283c91da3e33","Volumes":null,"WorkingDir":"","Entrypoint":null,"OnBuild":null,"Labels":null},"DockerVersion":"1.8.3","Author":"","Config":{"Hostname":"aded96b43f48","Domainname":"","User":"","AttachStdin":false,"AttachStdout":false,"AttachStderr":false,"Tty":false,"OpenStdin":false,"StdinOnce":false,"Env":null,"Cmd":["sh"],"Image":"9e77fef7a1c9f989988c06620dabc4020c607885b959a2cbd7c2283c91da3e33","Volumes":null,"WorkingDir":"","Entrypoint":null,"OnBuild":null,"Labels":null},"Architecture":"amd64","Os":"linux"}

$ skopeo copy --src-creds=testuser:testpassword docker://myregistrydomain.com:5000/private oci:local_oci_image

Contributing Copy Chapter

Please read the contribution guide if you want to collaborate in the project.

Commands Copy Chapter

License Copy Chapter

skopeo is licensed under the Apache License, Version 2.0. See
LICENSE for the full license text.

Overview (`contrib/skopeoimage/README.md`) Copy Section

The skopeo container image build context and automation have been
moved to https://github.com/containers/image_build/tree/main/skopeo

Overview (`vendor/dario.cat/mergo/README.md`) Copy Section

Mergo

A helper to merge structs and maps in Golang. Useful for configuration default values, avoiding messy if-statements.

Mergo merges same-type structs and maps by setting default values in zero-value fields. Mergo won't merge unexported (private) fields. It will do recursively any exported one. It also won't merge structs inside maps (because they are not addressable using Go reflection).

Also a lovely comune (municipality) in the Province of Ancona in the Italian region of Marche.

Status Copy Chapter

Mergo is stable and frozen, ready for production. Check a short list of the projects using at large scale it here.

No new features are accepted. They will be considered for a future v2 that improves the implementation and fixes bugs for corner cases.

Important notes Copy Section

1.0.0

In 1.0.0 Mergo moves to a vanity URL dario.cat/mergo. No more v1 versions will be released.

If the vanity URL is causing issues in your project due to a dependency pulling Mergo - it isn't a direct dependency in your project - it is recommended to use replace to pin the version to the last one with the old import URL:

replace github.com/imdario/mergo => github.com/imdario/mergo v0.3.16

0.3.9

Please keep in mind that a problematic PR broke 0.3.9. I reverted it in 0.3.10, and I consider it stable but not bug-free. Also, this version adds support for go modules.

Keep in mind that in 0.3.2, Mergo changed Merge()and Map() signatures to support transformers. I added an optional/variadic argument so that it won't break the existing code.

If you were using Mergo before April 6th, 2015, please check your project works as intended after updating your local copy with go get -u dario.cat/mergo. I apologize for any issue caused by its previous behavior and any future bug that Mergo could cause in existing projects after the change (release 0.2.0).

Donations Copy Section

If Mergo is useful to you, consider buying me a coffee, a beer, or making a monthly donation to allow me to keep building great free software. :heart_eyes:

Mergo in the wild Copy Section

Mergo is used by thousands of projects, including:

• containerd/containerd
• datadog/datadog-agent
• docker/cli/
• goreleaser/goreleaser
• go-micro/go-micro
• grafana/loki
• masterminds/sprig
• moby/moby
• slackhq/nebula
• volcano-sh/volcano

Install Copy Chapter

go get dario.cat/mergo

// use in your .go code
import (
    "dario.cat/mergo"
)

Usage Copy Chapter

You can only merge same-type structs with exported fields initialized as zero value of their type and same-types maps. Mergo won't merge unexported (private) fields but will do recursively any exported one. It won't merge empty structs value as they are zero values too. Also, maps will be merged recursively except for structs inside maps (because they are not addressable using Go reflection).

if err := mergo.Merge(&dst, src); err != nil {
    // ...
}

Also, you can merge overwriting values using the transformer WithOverride.

if err := mergo.Merge(&dst, src, mergo.WithOverride); err != nil {
    // ...
}

If you need to override pointers, so the source pointer's value is assigned to the destination's pointer, you must use WithoutDereference:

package main

import (
	"fmt"

	"dario.cat/mergo"
)

type Foo struct {
	A *string
	B int64
}

func main() {
	first := "first"
	second := "second"
	src := Foo{
		A: &first,
		B: 2,
	}

	dest := Foo{
		A: &second,
		B: 1,
	}

	mergo.Merge(&dest, src, mergo.WithOverride, mergo.WithoutDereference)
}

Additionally, you can map a map[string]interface{} to a struct (and otherwise, from struct to map), following the same restrictions as in Merge(). Keys are capitalized to find each corresponding exported field.

if err := mergo.Map(&dst, srcMap); err != nil {
    // ...
}

Warning: if you map a struct to map, it won't do it recursively. Don't expect Mergo to map struct members of your struct as map[string]interface{}. They will be just assigned as values.

Here is a nice example:

package main

import (
	"fmt"
	"dario.cat/mergo"
)

type Foo struct {
	A string
	B int64
}

func main() {
	src := Foo{
		A: "one",
		B: 2,
	}
	dest := Foo{
		A: "two",
	}
	mergo.Merge(&dest, src)
	fmt.Println(dest)
	// Will print
	// {two 2}
}

Transformers Copy Section

Transformers allow to merge specific types differently than in the default behavior. In other words, now you can customize how some types are merged. For example, time.Time is a struct; it doesn't have zero value but IsZero can return true because it has fields with zero value. How can we merge a non-zero time.Time?

package main

import (
	"fmt"
	"dario.cat/mergo"
    "reflect"
    "time"
)

type timeTransformer struct {
}

func (t timeTransformer) Transformer(typ reflect.Type) func(dst, src reflect.Value) error {
	if typ == reflect.TypeOf(time.Time{}) {
		return func(dst, src reflect.Value) error {
			if dst.CanSet() {
				isZero := dst.MethodByName("IsZero")
				result := isZero.Call([]reflect.Value{})
				if result[0].Bool() {
					dst.Set(src)
				}
			}
			return nil
		}
	}
	return nil
}

type Snapshot struct {
	Time time.Time
	// ...
}

func main() {
	src := Snapshot{time.Now()}
	dest := Snapshot{}
	mergo.Merge(&dest, src, mergo.WithTransformers(timeTransformer{}))
	fmt.Println(dest)
	// Will print
	// { 2018-01-12 01:15:00 +0000 UTC m=+0.000000001 }
}

Contact me Copy Chapter

If I can help you, you have an idea or you are using Mergo in your projects, don't hesitate to drop me a line (or a pull request): @im_dario

About Copy Chapter

Written by Dario Castañé.

License Copy Chapter

BSD 3-Clause license, as Go language.

Overview (`vendor/go.opentelemetry.io/otel/README.md`) Copy Section

OpenTelemetry-Go

OpenTelemetry-Go is the Go implementation of OpenTelemetry.
It provides a set of APIs to directly measure performance and behavior of your software and send this data to observability platforms.

Project Status Copy Chapter

Progress and status specific to this repository is tracked in our
project boards
and
milestones.

Project versioning information and stability guarantees can be found in the
versioning documentation.

Compatibility Copy Section

OpenTelemetry-Go ensures compatibility with the current supported versions of
the Go language:

Each major Go release is supported until there are two newer major releases.
For example, Go 1.5 was supported until the Go 1.7 release, and Go 1.6 was supported until the Go 1.8 release.

For versions of Go that are no longer supported upstream, opentelemetry-go will
stop ensuring compatibility with these versions in the following manner:

• A minor release of opentelemetry-go will be made to add support for the new
  supported release of Go.
• The following minor release of opentelemetry-go will remove compatibility
  testing for the oldest (now archived upstream) version of Go. This, and
  future, releases of opentelemetry-go may include features only supported by
  the currently supported versions of Go.

Currently, this project supports the following environments.

While this project should work for other systems, no compatibility guarantees
are made for those systems currently.

Getting Started Copy Chapter

You can find a getting started guide on opentelemetry.io.

OpenTelemetry's goal is to provide a single set of APIs to capture distributed
traces and metrics from your application and send them to an observability
platform. This project allows you to do just that for applications written in
Go. There are two steps to this process: instrument your application, and
configure an exporter.

Instrumentation Copy Section

To start capturing distributed traces and metric events from your application
it first needs to be instrumented. The easiest way to do this is by using an
instrumentation library for your code. Be sure to check out the officially
supported instrumentation
libraries.

If you need to extend the telemetry an instrumentation library provides or want
to build your own instrumentation for your application directly you will need
to use the
Go otel
package. The examples
are a good way to see some practical uses of this process.

Export Copy Section

Now that your application is instrumented to collect telemetry, it needs an
export pipeline to send that telemetry to an observability platform.

All officially supported exporters for the OpenTelemetry project are contained in the exporters directory.

Contributing Copy Chapter

See the contributing documentation.

Overview (`vendor/go.podman.io/storage/README.md`) Copy Section

storage is a Go library which aims to provide methods for storing filesystem
layers, container images, and containers. A containers-storage CLI wrapper
is also included for manual and scripting use.

To build the CLI wrapper, use 'make binary'.

Operations which use VMs expect to launch them using 'vagrant', defaulting to
using its 'libvirt' provider. The boxes used are also available for the
'virtualbox' provider, and can be selected by setting $VAGRANT_PROVIDER to
'virtualbox' before kicking off the build.

The library manages three types of items: layers, images, and containers.

A layer is a copy-on-write filesystem which is notionally stored as a set of
changes relative to its parent layer, if it has one. A given layer can only
have one parent, but any layer can be the parent of multiple layers. Layers
which are parents of other layers should be treated as read-only.

An image is a reference to a particular layer (its top layer), along with
other information which the library can manage for the convenience of its
caller. This information typically includes configuration templates for
running a binary contained within the image's layers, and may include
cryptographic signatures. Multiple images can reference the same layer, as the
differences between two images may not be in their layer contents.

A container is a read-write layer which is a child of an image's top layer,
along with information which the library can manage for the convenience of its
caller. This information typically includes configuration information for
running the specific container. Multiple containers can be derived from a
single image.

Layers, images, and containers are represented primarily by 32 character
hexadecimal IDs, but items of each kind can also have one or more arbitrary
names attached to them, which the library will automatically resolve to IDs
when they are passed in to API calls which expect IDs.

The library can store what it calls metadata for each of these types of
items. This is expected to be a small piece of data, since it is cached in
memory and stored along with the library's own bookkeeping information.

Additionally, the library can store one or more of what it calls big data for
images and containers. This is a named chunk of larger data, which is only in
memory when it is being read from or being written to its own disk file.

Contributing
Information about contributing to this project.

Overview (`vendor/google.golang.org/grpc/README.md`) Copy Section

gRPC-Go

The Go implementation of gRPC: A high performance, open source, general
RPC framework that puts mobile and HTTP/2 first. For more information see the
Go gRPC docs, or jump directly into the quick start.

Prerequisites Copy Chapter

• Go: any one of the two latest major releases.

Installation Copy Chapter

Simply add the following import to your code, and then go [build|run|test]
will automatically fetch the necessary dependencies:

import "google.golang.org/grpc"

Note: If you are trying to access grpc-go from China, see the
FAQ below.

Learn more Copy Chapter

• Go gRPC docs, which include a quick start and API
  reference among other resources
• Low-level technical docs from this repository
• Performance benchmark
• Examples
• Contribution guidelines

FAQ Copy Chapter

I/O Timeout Errors Copy Section

The golang.org domain may be blocked from some countries. go get usually
produces an error like the following when this happens:

$ go get -u google.golang.org/grpc
package google.golang.org/grpc: unrecognized import path "google.golang.org/grpc" (https fetch: Get https://google.golang.org/grpc?go-get=1: dial tcp 216.239.37.1:443: i/o timeout)

To build Go code, there are several options:

• Set up a VPN and access google.golang.org through that.

• With Go module support: it is possible to use the replace feature of go mod to create aliases for golang.org packages. In your project's directory:

  sh Copy

  go mod edit -replace=google.golang.org/grpc=github.com/grpc/grpc-go@latest
  go mod tidy
  go mod vendor
  go build -mod=vendor

  Again, this will need to be done for all transitive dependencies hosted on
  golang.org as well. For details, refer to golang/go issue
  #28652.

Compiling error, undefined: grpc.SupportPackageIsVersion Copy Section

Please update to the latest version of gRPC-Go using
go get google.golang.org/grpc.

How to turn on logging Copy Section

The default logger is controlled by environment variables. Turn everything on
like this:

$ export GRPC_GO_LOG_VERBOSITY_LEVEL=99
$ export GRPC_GO_LOG_SEVERITY_LEVEL=info

The RPC failed with error `"code = Unavailable desc = transport is closing"` Copy Section

This error means the connection the RPC is using was closed, and there are many
possible reasons, including:

1. mis-configured transport credentials, connection failed on handshaking
2. bytes disrupted, possibly by a proxy in between
3. server shutdown
4. Keepalive parameters caused connection shutdown, for example if you have
   configured your server to terminate connections regularly to trigger DNS
   lookups.
   If this is the case, you may want to increase your
   MaxConnectionAgeGrace,
   to allow longer RPC calls to finish.

It can be tricky to debug this because the error happens on the client side but
the root cause of the connection being closed is on the server side. Turn on
logging on both client and server, and see if there are any transport
errors.

Overview (`vendor/github.com/BurntSushi/toml/README.md`) Copy Section

TOML stands for Tom's Obvious, Minimal Language. This Go package provides a
reflection interface similar to Go's standard library json and xml packages.

Compatible with TOML version v1.1.0.

Documentation: https://pkg.go.dev/github.com/BurntSushi/toml

See the releases page for a
changelog; this information is also in the git tag annotations (e.g. git show v0.4.0).

This library requires Go 1.18 or newer; add it to your go.mod with:

% go get github.com/BurntSushi/toml@latest

It also comes with a TOML validator CLI tool:

% go install github.com/BurntSushi/toml/cmd/tomlv@latest
% tomlv some-toml-file.toml

Examples Copy Section

For the simplest example, consider some TOML file as just a list of keys and
values:

Age = 25
Cats = [ "Cauchy", "Plato" ]
Pi = 3.14
Perfection = [ 6, 28, 496, 8128 ]
DOB = 1987-07-05T05:45:00Z

Which can be decoded with:

type Config struct {
	Age        int
	Cats       []string
	Pi         float64
	Perfection []int
	DOB        time.Time
}

var conf Config
_, err := toml.Decode(tomlData, &conf)

You can also use struct tags if your struct field name doesn't map to a TOML key
value directly:

some_key_NAME = "wat"

type TOML struct {
    ObscureKey string `toml:"some_key_NAME"`
}

Beware that like other decoders only exported fields are considered when
encoding and decoding; private fields are silently ignored.

Using the `Marshaler` and `encoding.TextUnmarshaler` interfaces Copy Section

Here's an example that automatically parses values in a mail.Address:

contacts = [
    "Donald Duck <[email protected]>",
    "Scrooge McDuck <[email protected]>",
]

Can be decoded with:

// Create address type which satisfies the encoding.TextUnmarshaler interface.
type address struct {
	*mail.Address
}

func (a *address) UnmarshalText(text []byte) error {
	var err error
	a.Address, err = mail.ParseAddress(string(text))
	return err
}

// Decode it.
func decode() {
	blob := `
		contacts = [
			"Donald Duck <[email protected]>",
			"Scrooge McDuck <[email protected]>",
		]
	`

	var contacts struct {
		Contacts []address
	}

	_, err := toml.Decode(blob, &contacts)
	if err != nil {
		log.Fatal(err)
	}

	for _, c := range contacts.Contacts {
		fmt.Printf("%#v\n", c.Address)
	}

	// Output:
	// &mail.Address{Name:"Donald Duck", Address:"[email protected]"}
	// &mail.Address{Name:"Scrooge McDuck", Address:"[email protected]"}
}

To target TOML specifically you can implement UnmarshalTOML TOML interface in
a similar way.

More complex usage Copy Section

See the _example/ directory for a more complex example.

Overview (`vendor/github.com/Microsoft/go-winio/README.md`) Copy Section

go-winio [](https://github.com/microsoft/go-winio/actions/workflows/ci.yml)

This repository contains utilities for efficiently performing Win32 IO operations in
Go. Currently, this is focused on accessing named pipes and other file handles, and
for using named pipes as a net transport.

This code relies on IO completion ports to avoid blocking IO on system threads, allowing Go
to reuse the thread to schedule another goroutine. This limits support to Windows Vista and
newer operating systems. This is similar to the implementation of network sockets in Go's net
package.

Please see the LICENSE file for licensing information.

Contributing Copy Chapter

This project welcomes contributions and suggestions.
Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that
you have the right to, and actually do, grant us the rights to use your contribution.
For details, visit Microsoft CLA.

When you submit a pull request, a CLA-bot will automatically determine whether you need to
provide a CLA and decorate the PR appropriately (e.g., label, comment).
Simply follow the instructions provided by the bot.
You will only need to do this once across all repos using our CLA.

Additionally, the pull request pipeline requires the following steps to be performed before
mergining.

Code Sign-Off Copy Section

We require that contributors sign their commits using git commit --signoff
to certify they either authored the work themselves or otherwise have permission to use it in this project.

A range of commits can be signed off using git rebase --signoff.

Please see the developer certificate for more info,
as well as to make sure that you can attest to the rules listed.
Our CI uses the DCO Github app to ensure that all commits in a given PR are signed-off.

Linting Copy Section

Code must pass a linting stage, which uses golangci-lint.
The linting settings are stored in .golangci.yaml, and can be run
automatically with VSCode by adding the following to your workspace or folder settings:

"go.lintTool": "golangci-lint",
    "go.lintOnSave": "package",

Additional editor integrations options are also available.

Alternatively, golangci-lint can be installed locally and run from the repo root:

# use . or specify a path to only lint a package
# to show all lint errors, use flags "--max-issues-per-linter=0 --max-same-issues=0"
> golangci-lint run ./...

Go Generate Copy Section

The pipeline checks that auto-generated code, via go generate, are up to date.

This can be done for the entire repo:

> go generate ./...

Code of Conduct Copy Chapter

This project has adopted the Microsoft Open Source Code of Conduct.
For more information see the Code of Conduct FAQ or
contact [email protected] with any additional questions or comments.

Special Thanks Copy Chapter

Thanks to natefinch for the inspiration for this library.
See npipe for another named pipe implementation.

Overview (`vendor/github.com/VividCortex/ewma/README.md`) Copy Section

EWMA

This repo provides Exponentially Weighted Moving Average algorithms, or EWMAs for short, based on our
Quantifying Abnormal Behavior talk.

Exponentially Weighted Moving Average Copy Section

An exponentially weighted moving average is a way to continuously compute a type of
average for a series of numbers, as the numbers arrive. After a value in the series is
added to the average, its weight in the average decreases exponentially over time. This
biases the average towards more recent data. EWMAs are useful for several reasons, chiefly
their inexpensive computational and memory cost, as well as the fact that they represent
the recent central tendency of the series of values.

The EWMA algorithm requires a decay factor, alpha. The larger the alpha, the more the average
is biased towards recent history. The alpha must be between 0 and 1, and is typically
a fairly small number, such as 0.04. We will discuss the choice of alpha later.

The algorithm works thus, in pseudocode:

1. Multiply the next number in the series by alpha.
2. Multiply the current value of the average by 1 minus alpha.
3. Add the result of steps 1 and 2, and store it as the new current value of the average.
4. Repeat for each number in the series.

There are special-case behaviors for how to initialize the current value, and these vary
between implementations. One approach is to start with the first value in the series;
another is to average the first 10 or so values in the series using an arithmetic average,
and then begin the incremental updating of the average. Each method has pros and cons.

It may help to look at it pictorially. Suppose the series has five numbers, and we choose
alpha to be 0.50 for simplicity. Here's the series, with numbers in the neighborhood of 300.

Now let's take the moving average of those numbers. First we set the average to the value
of the first number.

Next we multiply the next number by alpha, multiply the current value by 1-alpha, and add
them to generate a new value.

This continues until we are done.

Notice how each of the values in the series decays by half each time a new value
is added, and the top of the bars in the lower portion of the image represents the
size of the moving average. It is a smoothed, or low-pass, average of the original
series.

For further reading, see Exponentially weighted moving average on wikipedia.

Choosing Alpha Copy Section

Consider a fixed-size sliding-window moving average (not an exponentially weighted moving average)
that averages over the previous N samples. What is the average age of each sample? It is N/2.

Now suppose that you wish to construct a EWMA whose samples have the same average age. The formula
to compute the alpha required for this is: alpha = 2/(N+1). Proof is in the book
"Production and Operations Analysis" by Steven Nahmias.

So, for example, if you have a time-series with samples once per second, and you want to get the
moving average over the previous minute, you should use an alpha of .032786885. This, by the way,
is the constant alpha used for this repository's SimpleEWMA.

Implementations Copy Section

This repository contains two implementations of the EWMA algorithm, with different properties.

The implementations all conform to the MovingAverage interface, and the constructor returns
that type.

Current implementations assume an implicit time interval of 1.0 between every sample added.
That is, the passage of time is treated as though it's the same as the arrival of samples.
If you need time-based decay when samples are not arriving precisely at set intervals, then
this package will not support your needs at present.

SimpleEWMA

A SimpleEWMA is designed for low CPU and memory consumption. It will have different behavior than the VariableEWMA
for multiple reasons. It has no warm-up period and it uses a constant
decay. These properties let it use less memory. It will also behave
differently when it's equal to zero, which is assumed to mean
uninitialized, so if a value is likely to actually become zero over time,
then any non-zero value will cause a sharp jump instead of a small change.

VariableEWMA

Unlike SimpleEWMA, this supports a custom age which must be stored, and thus uses more memory.
It also has a "warmup" time when you start adding values to it. It will report a value of 0.0
until you have added the required number of samples to it. It uses some memory to store the
number of samples added to it. As a result it uses a little over twice the memory of SimpleEWMA.

Usage Copy Chapter

API Documentation Copy Section

View the GoDoc generated documentation here.

package main

import "github.com/VividCortex/ewma"

func main() {
	samples := [100]float64{
		4599, 5711, 4746, 4621, 5037, 4218, 4925, 4281, 5207, 5203, 5594, 5149,
	}

	e := ewma.NewMovingAverage()  //=> Returns a SimpleEWMA if called without params
	a := ewma.NewMovingAverage(5) //=> returns a VariableEWMA with a decay of 2 / (5 + 1)

	for _, f := range samples {
		e.Add(f)
		a.Add(f)
	}

	e.Value() //=> 13.577404704631077
	a.Value() //=> 1.5806140565521463e-12
}

Contributing Copy Chapter

We only accept pull requests for minor fixes or improvements. This includes:

• Small bug fixes
• Typos
• Documentation or comments

Please open issues to discuss new features. Pull requests for new features will be rejected,
so we recommend forking the repository and making changes in your fork for your use case.

License Copy Chapter

This repository is Copyright (c) 2013 VividCortex, Inc. All rights reserved.
It is licensed under the MIT license. Please see the LICENSE file for applicable license terms.

Overview (`vendor/github.com/acarl005/stripansi/README.md`) Copy Section

Strip ANSI

This Go package removes ANSI escape codes from strings.

Ideally, we would prevent these from appearing in any text we want to process.
However, sometimes this can't be helped, and we need to be able to deal with that noise.
This will use a regexp to remove those unwanted escape codes.

Install Copy Chapter

$ go get -u github.com/acarl005/stripansi

Usage Copy Chapter

import (
	"fmt"
	"github.com/acarl005/stripansi"
)

func main() {
	msg := "\x1b[38;5;140m foo\x1b[0m bar"
	cleanMsg := stripansi.Strip(msg)
	fmt.Println(cleanMsg) // " foo bar"
}

Overview (`vendor/github.com/containerd/errdefs/README.md`) Copy Section

errdefs

A Go package for defining and checking common containerd errors.

Project details Copy Chapter

errdefs is a containerd sub-project, licensed under the Apache 2.0 license.
As a containerd sub-project, you will find the:

• Project governance,
• Maintainers,
• and Contributing guidelines

information in our containerd/project repository.

Overview (`vendor/github.com/containers/libtrust/README.md`) Copy Section

libtrust

WARNING this library is no longer actively developed, and will be integrated
in the [docker/distribution][https://www.github.com/docker/distribution]
repository in future.

Libtrust is library for managing authentication and authorization using public key cryptography.

Authentication is handled using the identity attached to the public key.
Libtrust provides multiple methods to prove possession of the private key associated with an identity.

• TLS x509 certificates
• Signature verification
• Key Challenge

Authorization and access control is managed through a distributed trust graph.
Trust servers are used as the authorities of the trust graph and allow caching portions of the graph for faster access.

Copyright and license Copy Chapter

Code and documentation copyright 2014 Docker, inc. Code released under the Apache 2.0 license.
Docs released under Creative commons.

Overview (`vendor/github.com/containers/ocicrypt/README.md`) Copy Section

OCIcrypt Library

The ocicrypt library is the OCI image spec implementation of container image encryption. More details of the spec can be seen in the OCI repository. The purpose of this library is to encode spec structures and consts in code, as well as provide a consistent implementation of image encryption across container runtimes and build tools.

Consumers of OCIcrypt:

• containerd/imgcrypt
• cri-o
• skopeo

Usage Copy Chapter

There are various levels of usage for this library. The main consumers of these would be runtime/build tools, and a more specific use would be in the ability to extend cryptographic function.

Runtime/Build tool usage Copy Section

The general exposed interface a runtime/build tool would use, would be to perform encryption or decryption of layers:

package "github.com/containers/ocicrypt"
func EncryptLayer(ec *config.EncryptConfig, encOrPlainLayerReader io.Reader, desc ocispec.Descriptor) (io.Reader, EncryptLayerFinalizer, error)
func DecryptLayer(dc *config.DecryptConfig, encLayerReader io.Reader, desc ocispec.Descriptor, unwrapOnly bool) (io.Reader, digest.Digest, error)

The settings/parameters to these functions can be specified via creation of an encryption config with the github.com/containers/ocicrypt/config package. We note that because setting of annotations and other fields of the layer descriptor is done through various means in different runtimes/build tools, it is the responsibility of the caller to still ensure that the layer descriptor follows the OCI specification (i.e. encoding, setting annotations, etc.).

Crypto Agility and Extensibility Copy Section

The implementation for both symmetric and asymmetric encryption used in this library are behind 2 main interfaces, which users can extend if need be. These are in the following packages:

• github.com/containers/ocicrypt/blockcipher - LayerBlockCipher interface for block ciphers
• github.com/containers/ocicrypt/keywrap - KeyWrapper interface for key wrapping

We note that adding interfaces here is risky outside the OCI spec is not recommended, unless for very specialized and confined usecases. Please open an issue or PR if there is a general usecase that could be added to the OCI spec.

Keyprovider interface

As part of the keywrap interface, there is a keyprovider implementation that allows one to call out to a binary or service.

Security Issues Copy Chapter

We consider security issues related to this library critical. Please report and security related issues by emailing maintainers in the MAINTAINERS file.

Ocicrypt Pkcs11 Support Copy Chapter

Ocicrypt Pkcs11 support is currently experiemental. For more details, please refer to the this document.

Overview (`vendor/github.com/cyphar/filepath-securejoin/README.md`) Copy Section

`filepath-securejoin` Copy Chapter

Old API Copy Section

This library was originally just an implementation of SecureJoin which was
intended to be included in the Go standard library as a safer
filepath.Join that would restrict the path lookup to be inside a root
directory.

The implementation was based on code that existed in several container
runtimes. Unfortunately, this API is fundamentally unsafe against attackers
that can modify path components after SecureJoin returns and before the
caller uses the path, allowing for some fairly trivial TOCTOU attacks.

SecureJoin (and SecureJoinVFS) are still provided by this library to
support legacy users, but new users are strongly suggested to avoid using
SecureJoin and instead use the new api or switch to
libpathrs.

With the above limitations in mind, this library guarantees the following:

• If no error is set, the resulting string must be a child path of
  root and will not contain any symlink path components (they will all be
  expanded).

• When expanding symlinks, all symlink path components must be resolved
  relative to the provided root. In particular, this can be considered a
  userspace implementation of how chroot(2) operates on file paths. Note that
  these symlinks will not be expanded lexically (filepath.Clean is not
  called on the input before processing).

• Non-existent path components are unaffected by SecureJoin (similar to
  filepath.EvalSymlinks's semantics).

• The returned path will always be filepath.Cleaned and thus not contain any
  .. components.

A (trivial) implementation of this function on GNU/Linux systems could be done
with the following (note that this requires root privileges and is far more
opaque than the implementation in this library, and also requires that
readlink is inside the root path and is trustworthy):

package securejoin

import (
	"os/exec"
	"path/filepath"
)

func SecureJoin(root, unsafePath string) (string, error) {
	unsafePath = string(filepath.Separator) + unsafePath
	cmd := exec.Command("chroot", root,
		"readlink", "--canonicalize-missing", "--no-newline", unsafePath)
	output, err := cmd.CombinedOutput()
	if err != nil {
		return "", err
	}
	expanded := string(output)
	return filepath.Join(root, expanded), nil
}

New API Copy Section

While we recommend users switch to libpathrs as soon as it has a
stable release, some methods implemented by libpathrs have been ported to this
library to ease the transition. These APIs are only supported on Linux.

These APIs are implemented such that filepath-securejoin will
opportunistically use certain newer kernel APIs that make these operations far
more secure. In particular:

• All of the lookup operations will use openat2 on new enough
  kernels (Linux 5.6 or later) to restrict lookups through magic-links and
  bind-mounts (for certain operations) and to make use of RESOLVE_IN_ROOT to
  efficiently resolve symlinks within a rootfs.

• The APIs provide hardening against a malicious /proc mount to either detect
  or avoid being tricked by a /proc that is not legitimate. This is done
  using openat2 for all users, and privileged users will also be
  further protected by using fsopen and open_tree
  (Linux 5.2 or later).

`OpenInRoot`

func OpenInRoot(root, unsafePath string) (*os.File, error)
func OpenatInRoot(root *os.File, unsafePath string) (*os.File, error)
func Reopen(handle *os.File, flags int) (*os.File, error)

OpenInRoot is a much safer version of

path, err := securejoin.SecureJoin(root, unsafePath)
file, err := os.OpenFile(path, unix.O_PATH|unix.O_CLOEXEC)

that protects against various race attacks that could lead to serious security
issues, depending on the application. Note that the returned *os.File is an
O_PATH file descriptor, which is quite restricted. Callers will probably need
to use Reopen to get a more usable handle (this split is done to provide
useful features like PTY spawning and to avoid users accidentally opening bad
inodes that could cause a DoS).

Callers need to be careful in how they use the returned *os.File. Usually it
is only safe to operate on the handle directly, and it is very easy to create a
security issue. libpathrs provides far more helpers to make using
these handles safer -- there is currently no plan to port them to
filepath-securejoin.

OpenatInRoot is like OpenInRoot except that the root is provided using an
*os.File. This allows you to ensure that multiple OpenatInRoot (or
MkdirAllHandle) calls are operating on the same rootfs.

NOTE: Unlike SecureJoin, OpenInRoot will error out as soon as it hits
a dangling symlink or non-existent path. This is in contrast to SecureJoin
which treated non-existent components as though they were real directories,
and would allow for partial resolution of dangling symlinks. These behaviours
are at odds with how Linux treats non-existent paths and dangling symlinks,
and so these are no longer allowed.

`MkdirAll`

func MkdirAll(root, unsafePath string, mode int) error
func MkdirAllHandle(root *os.File, unsafePath string, mode int) (*os.File, error)

MkdirAll is a much safer version of

path, err := securejoin.SecureJoin(root, unsafePath)
err = os.MkdirAll(path, mode)

that protects against the same kinds of races that OpenInRoot protects
against.

MkdirAllHandle is like MkdirAll except that the root is provided using an
*os.File (the reason for this is the same as with OpenatInRoot) and an
*os.File of the final created directory is returned (this directory is
guaranteed to be effectively identical to the directory created by
MkdirAllHandle, which is not possible to ensure by just using OpenatInRoot
after MkdirAll).

NOTE: Unlike SecureJoin, MkdirAll will error out as soon as it hits
a dangling symlink or non-existent path. This is in contrast to SecureJoin
which treated non-existent components as though they were real directories,
and would allow for partial resolution of dangling symlinks. These behaviours
are at odds with how Linux treats non-existent paths and dangling symlinks,
and so these are no longer allowed. This means that MkdirAll will not
create non-existent directories referenced by a dangling symlink.

License Copy Section

SPDX-License-Identifier: BSD-3-Clause AND MPL-2.0

Some of the code in this project is derived from Go, and is licensed under a
BSD 3-clause license (available in LICENSE.BSD). Other files (many of which
are derived from libpathrs) are licensed under the Mozilla Public
License version 2.0 (available in LICENSE.MPL-2.0). If you are using the
"New API" described above, you are probably using code from files
released under this license.

Every source file in this project has a copyright header describing its
license. Please check the license headers of each file to see what license
applies to it.

See COPYING.md for some more details.

Overview (`vendor/github.com/distribution/reference/README.md`) Copy Section

Distribution reference

Go library to handle references to container images.

This repository contains a library for handling references to container images held in container registries. Please see godoc for details.

Contribution Copy Chapter

Please see CONTRIBUTING.md for details on how to contribute
issues, fixes, and patches to this project.

Communication Copy Chapter

For async communication and long running discussions please use issues and pull requests on the github repo.
This will be the best place to discuss design and implementation.

For sync communication we have a #distribution channel in the CNCF Slack
that everyone is welcome to join and chat about development.

Licenses Copy Chapter

The distribution codebase is released under the Apache 2.0 license.

Overview (`vendor/github.com/docker/go-units/README.md`) Copy Section

Introduction

go-units is a library to transform human friendly measurements into machine friendly values.

Usage Copy Chapter

See the docs in godoc for examples and documentation.

Copyright and license Copy Chapter

Copyright © 2015 Docker, Inc.

go-units is licensed under the Apache License, Version 2.0.
See LICENSE for the full text of the license.

Overview (`vendor/github.com/felixge/httpsnoop/README.md`) Copy Section

httpsnoop

Package httpsnoop provides an easy way to capture http related metrics (i.e.
response time, bytes written, and http status code) from your application's
http.Handlers.

Doing this requires non-trivial wrapping of the http.ResponseWriter interface,
which is also exposed for users interested in a more low-level API.

Usage Example Copy Chapter

// myH is your app's http handler, perhaps a http.ServeMux or similar.
var myH http.Handler
// wrappedH wraps myH in order to log every request.
wrappedH := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	m := httpsnoop.CaptureMetrics(myH, w, r)
	log.Printf(
		"%s %s (code=%d dt=%s written=%d)",
		r.Method,
		r.URL,
		m.Code,
		m.Duration,
		m.Written,
	)
})
http.ListenAndServe(":8080", wrappedH)

Why this package exists Copy Chapter

Instrumenting an application's http.Handler is surprisingly difficult.

However if you google for e.g. "capture ResponseWriter status code" you'll find
lots of advise and code examples that suggest it to be a fairly trivial
undertaking. Unfortunately everything I've seen so far has a high chance of
breaking your application.

The main problem is that a http.ResponseWriter often implements additional
interfaces such as http.Flusher, http.CloseNotifier, http.Hijacker, http.Pusher, and
io.ReaderFrom. So the naive approach of just wrapping http.ResponseWriter
in your own struct that also implements the http.ResponseWriter interface
will hide the additional interfaces mentioned above. This has a high change of
introducing subtle bugs into any non-trivial application.

Another approach I've seen people take is to return a struct that implements
all of the interfaces above. However, that's also problematic, because it's
difficult to fake some of these interfaces behaviors when the underlying
http.ResponseWriter doesn't have an implementation. It's also dangerous,
because an application may choose to operate differently, merely because it
detects the presence of these additional interfaces.

This package solves this problem by checking which additional interfaces a
http.ResponseWriter implements, returning a wrapped version implementing the
exact same set of interfaces.

Additionally this package properly handles edge cases such as WriteHeader not
being called, or called more than once, as well as concurrent calls to
http.ResponseWriter methods, and even calls happening after the wrapped
ServeHTTP has already returned.

Unfortunately this package is not perfect either. It's possible that it is
still missing some interfaces provided by the go core (let me know if you find
one), and it won't work for applications adding their own interfaces into the
mix. You can however use httpsnoop.Unwrap(w) to access the underlying
http.ResponseWriter and type-assert the result to its other interfaces.

However, hopefully the explanation above has sufficiently scared you of rolling
your own solution to this problem. httpsnoop may still break your application,
but at least it tries to avoid it as much as possible.

Anyway, the real problem here is that smuggling additional interfaces inside
http.ResponseWriter is a problematic design choice, but it probably goes as
deep as the Go language specification itself. But that's okay, I still prefer
Go over the alternatives ;).

Performance Copy Chapter

BenchmarkBaseline-8      	   20000	     94912 ns/op
BenchmarkCaptureMetrics-8	   20000	     95461 ns/op

As you can see, using CaptureMetrics on a vanilla http.Handler introduces an
overhead of ~500 ns per http request on my machine. However, the margin of
error appears to be larger than that, therefor it should be reasonable to
assume that the overhead introduced by CaptureMetrics is absolutely
negligible.

License Copy Chapter

MIT

Overview (`vendor/github.com/go-logr/logr/README.md`) Copy Section

A minimal logging API for Go

logr offers an(other) opinion on how Go programs and libraries can do logging
without becoming coupled to a particular logging implementation. This is not
an implementation of logging - it is an API. In fact it is two APIs with two
different sets of users.

The Logger type is intended for application and library authors. It provides
a relatively small API which can be used everywhere you want to emit logs. It
defers the actual act of writing logs (to files, to stdout, or whatever) to the
LogSink interface.

The LogSink interface is intended for logging library implementers. It is a
pure interface which can be implemented by logging frameworks to provide the actual logging
functionality.

This decoupling allows application and library developers to write code in
terms of logr.Logger (which has very low dependency fan-out) while the
implementation of logging is managed "up stack" (e.g. in or near main().)
Application developers can then switch out implementations as necessary.

Many people assert that libraries should not be logging, and as such efforts
like this are pointless. Those people are welcome to convince the authors of
the tens-of-thousands of libraries that DO write logs that they are all
wrong. In the meantime, logr takes a more practical approach.

Typical usage Copy Chapter

Somewhere, early in an application's life, it will make a decision about which
logging library (implementation) it actually wants to use. Something like:

func main() {
        // ... other setup code ...

        // Create the "root" logger.  We have chosen the "logimpl" implementation,
        // which takes some initial parameters and returns a logr.Logger.
        logger := logimpl.New(param1, param2)

        // ... other setup code ...

Most apps will call into other libraries, create structures to govern the flow,
etc. The logr.Logger object can be passed to these other libraries, stored
in structs, or even used as a package-global variable, if needed. For example:

app := createTheAppObject(logger)
    app.Run()

Outside of this early setup, no other packages need to know about the choice of
implementation. They write logs in terms of the logr.Logger that they
received:

type appObject struct {
        // ... other fields ...
        logger logr.Logger
        // ... other fields ...
    }

    func (app *appObject) Run() {
        app.logger.Info("starting up", "timestamp", time.Now())

        // ... app code ...

Background Copy Chapter

If the Go standard library had defined an interface for logging, this project
probably would not be needed. Alas, here we are.

When the Go developers started developing such an interface with
slog, they adopted some of the
logr design but also left out some parts and changed others:

The high-level slog API is explicitly meant to be one of many different APIs
that can be layered on top of a shared slog.Handler. logr is one such
alternative API, with interoperability provided by
some conversion functions.

Inspiration Copy Section

Before you consider this package, please read this blog post by the
inimitable Dave Cheney. We really appreciate what
he has to say, and it largely aligns with our own experiences.

Differences from Dave's ideas Copy Section

The main differences are:

1. Dave basically proposes doing away with the notion of a logging API in favor
   of fmt.Printf(). We disagree, especially when you consider things like output
   locations, timestamps, file and line decorations, and structured logging. This
   package restricts the logging API to just 2 types of logs: info and error.

Info logs are things you want to tell the user which are not errors. Error
logs are, well, errors. If your code receives an error from a subordinate
function call and is logging that error and not returning it, use error
logs.

2. Verbosity-levels on info logs. This gives developers a chance to indicate
   arbitrary grades of importance for info logs, without assigning names with
   semantic meaning such as "warning", "trace", and "debug." Superficially this
   may feel very similar, but the primary difference is the lack of semantics.
   Because verbosity is a numerical value, it's safe to assume that an app running
   with higher verbosity means more (and less important) logs will be generated.

Implementations (non-exhaustive) Copy Chapter

There are implementations for the following logging libraries:

• a function (can bridge to non-structured libraries): funcr
• a testing.T (for use in Go tests, with JSON-like output): testr
• github.com/google/glog: glogr
• k8s.io/klog (for Kubernetes): klogr
• a testing.T (with klog-like text output): ktesting
• go.uber.org/zap: zapr
• log (the Go standard library logger): stdr
• github.com/sirupsen/logrus: logrusr
• github.com/wojas/genericr: genericr (makes it easy to implement your own backend)
• logfmt (Heroku style logging): logfmtr
• github.com/rs/zerolog: zerologr
• github.com/go-kit/log: gokitlogr (also compatible with github.com/go-kit/kit/log since v0.12.0)
• bytes.Buffer (writing to a buffer): bufrlogr (useful for ensuring values were logged, like during testing)

slog interoperability Copy Chapter

Interoperability goes both ways, using the logr.Logger API with a slog.Handler
and using the slog.Logger API with a logr.LogSink. FromSlogHandler and
ToSlogHandler convert between a logr.Logger and a slog.Handler.
As usual, slog.New can be used to wrap such a slog.Handler in the high-level
slog API.

Using a `logr.LogSink` as backend for slog Copy Section

Ideally, a logr sink implementation should support both logr and slog by
implementing both the normal logr interface(s) and SlogSink. Because
of a conflict in the parameters of the common Enabled method, it is not
possible to implement both slog.Handler and logr.Sink in the same
type.

If both are supported, log calls can go from the high-level APIs to the backend
without the need to convert parameters. FromSlogHandler and ToSlogHandler can
convert back and forth without adding additional wrappers, with one exception:
when Logger.V was used to adjust the verbosity for a slog.Handler, then
ToSlogHandler has to use a wrapper which adjusts the verbosity for future
log calls.

Such an implementation should also support values that implement specific
interfaces from both packages for logging (logr.Marshaler, slog.LogValuer,
slog.GroupValue). logr does not convert those.

Not supporting slog has several drawbacks:

• Recording source code locations works correctly if the handler gets called
  through slog.Logger, but may be wrong in other cases. That's because a
  logr.Sink does its own stack unwinding instead of using the program counter
  provided by the high-level API.
• slog levels <= 0 can be mapped to logr levels by negating the level without a
  loss of information. But all slog levels > 0 (e.g. slog.LevelWarning as
  used by slog.Logger.Warn) must be mapped to 0 before calling the sink
  because logr does not support "more important than info" levels.
• The slog group concept is supported by prefixing each key in a key/value
  pair with the group names, separated by a dot. For structured output like
  JSON it would be better to group the key/value pairs inside an object.
• Special slog values and interfaces don't work as expected.
• The overhead is likely to be higher.

These drawbacks are severe enough that applications using a mixture of slog and
logr should switch to a different backend.

Using a `slog.Handler` as backend for logr Copy Section

Using a plain slog.Handler without support for logr works better than the
other direction:

• All logr verbosity levels can be mapped 1:1 to their corresponding slog level
  by negating them.
• Stack unwinding is done by the SlogSink and the resulting program
  counter is passed to the slog.Handler.
• Names added via Logger.WithName are gathered and recorded in an additional
  attribute with logger as key and the names separated by slash as value.
• Logger.Error is turned into a log record with slog.LevelError as level
  and an additional attribute with err as key, if an error was provided.

The main drawback is that logr.Marshaler will not be supported. Types should
ideally support both logr.Marshaler and slog.Valuer. If compatibility
with logr implementations without slog support is not important, then
slog.Valuer is sufficient.

Context support for slog Copy Section

Storing a logger in a context.Context is not supported by
slog. NewContextWithSlogLogger and FromContextAsSlogLogger can be
used to fill this gap. They store and retrieve a slog.Logger pointer
under the same context key that is also used by NewContext and
FromContext for logr.Logger value.

When NewContextWithSlogLogger is followed by FromContext, the latter will
automatically convert the slog.Logger to a
logr.Logger. FromContextAsSlogLogger does the same for the other direction.

With this approach, binaries which use either slog or logr are as efficient as
possible with no unnecessary allocations. This is also why the API stores a
slog.Logger pointer: when storing a slog.Handler, creating a slog.Logger
on retrieval would need to allocate one.

The downside is that switching back and forth needs more allocations. Because
logr is the API that is already in use by different packages, in particular
Kubernetes, the recommendation is to use the logr.Logger API in code which
uses contextual logging.

An alternative to adding values to a logger and storing that logger in the
context is to store the values in the context and to configure a logging
backend to extract those values when emitting log entries. This only works when
log calls are passed the context, which is not supported by the logr API.

With the slog API, it is possible, but not
required. https://github.com/veqryn/slog-context is a package for slog which
provides additional support code for this approach. It also contains wrappers
for the context functions in logr, so developers who prefer to not use the logr
APIs directly can use those instead and the resulting code will still be
interoperable with logr.

FAQ Copy Chapter

Conceptual Copy Section

Why structured logging?

• Structured logs are more easily queryable: Since you've got
  key-value pairs, it's much easier to query your structured logs for
  particular values by filtering on the contents of a particular key --
  think searching request logs for error codes, Kubernetes reconcilers for
  the name and namespace of the reconciled object, etc.

• Structured logging makes it easier to have cross-referenceable logs:
  Similarly to searchability, if you maintain conventions around your
  keys, it becomes easy to gather all log lines related to a particular
  concept.

• Structured logs allow better dimensions of filtering: if you have
  structure to your logs, you've got more precise control over how much
  information is logged -- you might choose in a particular configuration
  to log certain keys but not others, only log lines where a certain key
  matches a certain value, etc., instead of just having v-levels and names
  to key off of.

• Structured logs better represent structured data: sometimes, the
  data that you want to log is inherently structured (think tuple-link
  objects.) Structured logs allow you to preserve that structure when
  outputting.

Why V-levels?

V-levels give operators an easy way to control the chattiness of log
operations. V-levels provide a way for a given package to distinguish
the relative importance or verbosity of a given log message. Then, if
a particular logger or package is logging too many messages, the user
of the package can simply change the v-levels for that library.

Why not named levels, like Info/Warning/Error?

Read Dave Cheney's post. Then read Differences
from Dave's ideas.

Why not allow format strings, too?

Format strings negate many of the benefits of structured logs:

• They're not easily searchable without resorting to fuzzy searching,
  regular expressions, etc.

• They don't store structured data well, since contents are flattened into
  a string.

• They're not cross-referenceable.

• They don't compress easily, since the message is not constant.

(Unless you turn positional parameters into key-value pairs with numerical
keys, at which point you've gotten key-value logging with meaningless
keys.)

Practical Copy Section

Why key-value pairs, and not a map?

Key-value pairs are much easier to optimize, especially around
allocations. Zap (a structured logger that inspired logr's interface) has
performance measurements
that show this quite nicely.

While the interface ends up being a little less obvious, you get
potentially better performance, plus avoid making users type
map[string]string{} every time they want to log.

What if my V-levels differ between libraries?

That's fine. Control your V-levels on a per-logger basis, and use the
WithName method to pass different loggers to different libraries.

Generally, you should take care to ensure that you have relatively
consistent V-levels within a given logger, however, as this makes deciding
on what verbosity of logs to request easier.

But I really want to use a format string!

That's not actually a question. Assuming your question is "how do
I convert my mental model of logging with format strings to logging with
constant messages":

1. Figure out what the error actually is, as you'd write in a TL;DR style,
   and use that as a message.

2. For every place you'd write a format specifier, look to the word before
   it, and add that as a key value pair.

For instance, consider the following examples (all taken from spots in the
Kubernetes codebase):

• klog.V(4).Infof("Client is returning errors: code %v, error %v", responseCode, err) becomes logger.Error(err, "client returned an error", "code", responseCode)

• klog.V(4).Infof("Got a Retry-After %ds response for attempt %d to %v", seconds, retries, url) becomes logger.V(4).Info("got a retry-after response when requesting url", "attempt", retries, "after seconds", seconds, "url", url)

If you really must use a format string, use it in a key's value, and
call fmt.Sprintf yourself. For instance: log.Printf("unable to reflect over type %T") becomes logger.Info("unable to reflect over type", "type", fmt.Sprintf("%T")). In general though, the cases where
this is necessary should be few and far between.

How do I choose my V-levels?

This is basically the only hard constraint: increase V-levels to denote
more verbose or more debug-y logs.

Otherwise, you can start out with 0 as "you always want to see this",
1 as "common logging that you might possibly want to turn off", and
10 as "I would like to performance-test your log collection stack."

Then gradually choose levels in between as you need them, working your way
down from 10 (for debug and trace style logs) and up from 1 (for chattier
info-type logs). For reference, slog pre-defines -4 for debug logs
(corresponds to 4 in logr), which matches what is
recommended for Kubernetes.

How do I choose my keys?

Keys are fairly flexible, and can hold more or less any string
value. For best compatibility with implementations and consistency
with existing code in other projects, there are a few conventions you
should consider.

• Make your keys human-readable.
• Constant keys are generally a good idea.
• Be consistent across your codebase.
• Keys should naturally match parts of the message string.
• Use lower case for simple keys and
  lowerCamelCase for
  more complex ones. Kubernetes is one example of a project that has
  adopted that
  convention.

While key names are mostly unrestricted (and spaces are acceptable),
it's generally a good idea to stick to printable ascii characters, or at
least match the general character set of your log lines.

Why should keys be constant values?

The point of structured logging is to make later log processing easier. Your
keys are, effectively, the schema of each log message. If you use different
keys across instances of the same log line, you will make your structured logs
much harder to use. Sprintf() is for values, not for keys!

Why is this not a pure interface?

The Logger type is implemented as a struct in order to allow the Go compiler to
optimize things like high-V Info logs that are not triggered. Not all of
these implementations are implemented yet, but this structure was suggested as
a way to ensure they can be implemented. All of the real work is behind the
LogSink interface.

Overview (`vendor/github.com/go-logr/stdr/README.md`) Copy Section

Minimal Go logging using logr and Go's standard library

This package implements the logr interface
in terms of Go's standard log package(https://pkg.go.dev/log).

Overview (`vendor/github.com/google/uuid/README.md`) Copy Section

uuid

The uuid package generates and inspects UUIDs based on
RFC 4122
and DCE 1.1: Authentication and Security Services.

This package is based on the github.com/pborman/uuid package (previously named
code.google.com/p/go-uuid). It differs from these earlier packages in that
a UUID is a 16 byte array rather than a byte slice. One loss due to this
change is the ability to represent an invalid UUID (vs a NIL UUID).

Install

go get github.com/google/uuid

Documentation

Full go doc style documentation for the package can be viewed online without
installing this package by using the GoDoc site here:
http://pkg.go.dev/github.com/google/uuid

Overview (`vendor/github.com/gorilla/mux/README.md`) Copy Section

gorilla/mux

Package gorilla/mux implements a request router and dispatcher for matching incoming requests to
their respective handler.

The name mux stands for "HTTP request multiplexer". Like the standard http.ServeMux, mux.Router matches incoming requests against a list of registered routes and calls a handler for the route that matches the URL or other conditions. The main features are:

• It implements the http.Handler interface so it is compatible with the standard http.ServeMux.
• Requests can be matched based on URL host, path, path prefix, schemes, header and query values, HTTP methods or using custom matchers.
• URL hosts, paths and query values can have variables with an optional regular expression.
• Registered URLs can be built, or "reversed", which helps maintaining references to resources.
• Routes can be used as subrouters: nested routes are only tested if the parent route matches. This is useful to define groups of routes that share common conditions like a host, a path prefix or other repeated attributes. As a bonus, this optimizes request matching.

• Install
• Examples
• Matching Routes
• Static Files
• Serving Single Page Applications (e.g. React, Vue, Ember.js, etc.)
• Registered URLs
• Walking Routes
• Graceful Shutdown
• Middleware
• Handling CORS Requests
• Testing Handlers
• Full Example

Install Copy Chapter

With a correctly configured Go toolchain:

go get -u github.com/gorilla/mux

Examples Copy Chapter

Let's start registering a couple of URL paths and handlers:

func main() {
    r := mux.NewRouter()
    r.HandleFunc("/", HomeHandler)
    r.HandleFunc("/products", ProductsHandler)
    r.HandleFunc("/articles", ArticlesHandler)
    http.Handle("/", r)
}

Here we register three routes mapping URL paths to handlers. This is equivalent to how http.HandleFunc() works: if an incoming request URL matches one of the paths, the corresponding handler is called passing (http.ResponseWriter, *http.Request) as parameters.

Paths can have variables. They are defined using the format {name} or {name:pattern}. If a regular expression pattern is not defined, the matched variable will be anything until the next slash. For example:

r := mux.NewRouter()
r.HandleFunc("/products/{key}", ProductHandler)
r.HandleFunc("/articles/{category}/", ArticlesCategoryHandler)
r.HandleFunc("/articles/{category}/{id:[0-9]+}", ArticleHandler)

The names are used to create a map of route variables which can be retrieved calling mux.Vars():

func ArticlesCategoryHandler(w http.ResponseWriter, r *http.Request) {
    vars := mux.Vars(r)
    w.WriteHeader(http.StatusOK)
    fmt.Fprintf(w, "Category: %v\n", vars["category"])
}

And this is all you need to know about the basic usage. More advanced options are explained below.

Matching Routes Copy Section

Routes can also be restricted to a domain or subdomain. Just define a host pattern to be matched. They can also have variables:

r := mux.NewRouter()
// Only matches if domain is "www.example.com".
r.Host("www.example.com")
// Matches a dynamic subdomain.
r.Host("{subdomain:[a-z]+}.example.com")

There are several other matchers that can be added. To match path prefixes:

r.PathPrefix("/products/")

...or HTTP methods:

r.Methods("GET", "POST")

...or URL schemes:

r.Schemes("https")

...or header values:

r.Headers("X-Requested-With", "XMLHttpRequest")

...or query values:

r.Queries("key", "value")

...or to use a custom matcher function:

r.MatcherFunc(func(r *http.Request, rm *RouteMatch) bool {
    return r.ProtoMajor == 0
})

...and finally, it is possible to combine several matchers in a single route:

r.HandleFunc("/products", ProductsHandler).
  Host("www.example.com").
  Methods("GET").
  Schemes("http")

Routes are tested in the order they were added to the router. If two routes match, the first one wins:

r := mux.NewRouter()
r.HandleFunc("/specific", specificHandler)
r.PathPrefix("/").Handler(catchAllHandler)

Setting the same matching conditions again and again can be boring, so we have a way to group several routes that share the same requirements. We call it "subrouting".

For example, let's say we have several URLs that should only match when the host is www.example.com. Create a route for that host and get a "subrouter" from it:

r := mux.NewRouter()
s := r.Host("www.example.com").Subrouter()

Then register routes in the subrouter:

s.HandleFunc("/products/", ProductsHandler)
s.HandleFunc("/products/{key}", ProductHandler)
s.HandleFunc("/articles/{category}/{id:[0-9]+}", ArticleHandler)

The three URL paths we registered above will only be tested if the domain is www.example.com, because the subrouter is tested first. This is not only convenient, but also optimizes request matching. You can create subrouters combining any attribute matchers accepted by a route.

Subrouters can be used to create domain or path "namespaces": you define subrouters in a central place and then parts of the app can register its paths relatively to a given subrouter.

There's one more thing about subroutes. When a subrouter has a path prefix, the inner routes use it as base for their paths:

r := mux.NewRouter()
s := r.PathPrefix("/products").Subrouter()
// "/products/"
s.HandleFunc("/", ProductsHandler)
// "/products/{key}/"
s.HandleFunc("/{key}/", ProductHandler)
// "/products/{key}/details"
s.HandleFunc("/{key}/details", ProductDetailsHandler)

Static Files Copy Section

Note that the path provided to PathPrefix() represents a "wildcard": calling
PathPrefix("/static/").Handler(...) means that the handler will be passed any
request that matches "/static/*". This makes it easy to serve static files with mux:

func main() {
    var dir string

    flag.StringVar(&dir, "dir", ".", "the directory to serve files from. Defaults to the current dir")
    flag.Parse()
    r := mux.NewRouter()

    // This will serve files under http://localhost:8000/static/<filename>
    r.PathPrefix("/static/").Handler(http.StripPrefix("/static/", http.FileServer(http.Dir(dir))))

    srv := &http.Server{
        Handler:      r,
        Addr:         "127.0.0.1:8000",
        // Good practice: enforce timeouts for servers you create!
        WriteTimeout: 15 * time.Second,
        ReadTimeout:  15 * time.Second,
    }

    log.Fatal(srv.ListenAndServe())
}

Serving Single Page Applications Copy Section

Most of the time it makes sense to serve your SPA on a separate web server from your API,
but sometimes it's desirable to serve them both from one place. It's possible to write a simple
handler for serving your SPA (for use with React Router's BrowserRouter for example), and leverage
mux's powerful routing for your API endpoints.

/* Detailed source-code truncated for AI context efficiency. */

Registered URLs Copy Section

Now let's see how to build registered URLs.

Routes can be named. All routes that define a name can have their URLs built, or "reversed". We define a name calling Name() on a route. For example:

r := mux.NewRouter()
r.HandleFunc("/articles/{category}/{id:[0-9]+}", ArticleHandler).
  Name("article")

To build a URL, get the route and call the URL() method, passing a sequence of key/value pairs for the route variables. For the previous route, we would do:

url, err := r.Get("article").URL("category", "technology", "id", "42")

...and the result will be a url.URL with the following path:

"/articles/technology/42"

This also works for host and query value variables:

r := mux.NewRouter()
r.Host("{subdomain}.example.com").
  Path("/articles/{category}/{id:[0-9]+}").
  Queries("filter", "{filter}").
  HandlerFunc(ArticleHandler).
  Name("article")

// url.String() will be "http://news.example.com/articles/technology/42?filter=gorilla"
url, err := r.Get("article").URL("subdomain", "news",
                                 "category", "technology",
                                 "id", "42",
                                 "filter", "gorilla")

All variables defined in the route are required, and their values must conform to the corresponding patterns. These requirements guarantee that a generated URL will always match a registered route -- the only exception is for explicitly defined "build-only" routes which never match.

Regex support also exists for matching Headers within a route. For example, we could do:

r.HeadersRegexp("Content-Type", "application/(text|json)")

...and the route will match both requests with a Content-Type of application/json as well as application/text

There's also a way to build only the URL host or path for a route: use the methods URLHost() or URLPath() instead. For the previous route, we would do:

// "http://news.example.com/"
host, err := r.Get("article").URLHost("subdomain", "news")

// "/articles/technology/42"
path, err := r.Get("article").URLPath("category", "technology", "id", "42")

And if you use subrouters, host and path defined separately can be built as well:

r := mux.NewRouter()
s := r.Host("{subdomain}.example.com").Subrouter()
s.Path("/articles/{category}/{id:[0-9]+}").
  HandlerFunc(ArticleHandler).
  Name("article")

// "http://news.example.com/articles/technology/42"
url, err := r.Get("article").URL("subdomain", "news",
                                 "category", "technology",
                                 "id", "42")

To find all the required variables for a given route when calling URL(), the method GetVarNames() is available:

r := mux.NewRouter()
r.Host("{domain}").
    Path("/{group}/{item_id}").
    Queries("some_data1", "{some_data1}").
    Queries("some_data2", "{some_data2}").
    Name("article")

// Will print [domain group item_id some_data1 some_data2] <nil>
fmt.Println(r.Get("article").GetVarNames())

Walking Routes Copy Section

The Walk function on mux.Router can be used to visit all of the routes that are registered on a router. For example,
the following prints all of the registered routes:

package main

import (
	"fmt"
	"net/http"
	"strings"

	"github.com/gorilla/mux"
)

func handler(w http.ResponseWriter, r *http.Request) {
	return
}

func main() {
	r := mux.NewRouter()
	r.HandleFunc("/", handler)
	r.HandleFunc("/products", handler).Methods("POST")
	r.HandleFunc("/articles", handler).Methods("GET")
	r.HandleFunc("/articles/{id}", handler).Methods("GET", "PUT")
	r.HandleFunc("/authors", handler).Queries("surname", "{surname}")
	err := r.Walk(func(route *mux.Route, router *mux.Router, ancestors []*mux.Route) error {
		pathTemplate, err := route.GetPathTemplate()
		if err == nil {
			fmt.Println("ROUTE:", pathTemplate)
		}
		pathRegexp, err := route.GetPathRegexp()
		if err == nil {
			fmt.Println("Path regexp:", pathRegexp)
		}
		queriesTemplates, err := route.GetQueriesTemplates()
		if err == nil {
			fmt.Println("Queries templates:", strings.Join(queriesTemplates, ","))
		}
		queriesRegexps, err := route.GetQueriesRegexp()
		if err == nil {
			fmt.Println("Queries regexps:", strings.Join(queriesRegexps, ","))
		}
		methods, err := route.GetMethods()
		if err == nil {
			fmt.Println("Methods:", strings.Join(methods, ","))
		}
		fmt.Println()
		return nil
	})

	if err != nil {
		fmt.Println(err)
	}

	http.Handle("/", r)
}

Graceful Shutdown Copy Section

Go 1.8 introduced the ability to gracefully shutdown a *http.Server. Here's how to do that alongside mux:

/* Detailed source-code truncated for AI context efficiency. */

Middleware Copy Section

Mux supports the addition of middlewares to a Router, which are executed in the order they are added if a match is found, including its subrouters.
Middlewares are (typically) small pieces of code which take one request, do something with it, and pass it down to another middleware or the final handler. Some common use cases for middleware are request logging, header manipulation, or ResponseWriter hijacking.

Mux middlewares are defined using the de facto standard type:

type MiddlewareFunc func(http.Handler) http.Handler

Typically, the returned handler is a closure which does something with the http.ResponseWriter and http.Request passed to it, and then calls the handler passed as parameter to the MiddlewareFunc. This takes advantage of closures being able access variables from the context where they are created, while retaining the signature enforced by the receivers.

A very basic middleware which logs the URI of the request being handled could be written as:

func loggingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Do stuff here
        log.Println(r.RequestURI)
        // Call the next handler, which can be another middleware in the chain, or the final handler.
        next.ServeHTTP(w, r)
    })
}

Middlewares can be added to a router using Router.Use():

r := mux.NewRouter()
r.HandleFunc("/", handler)
r.Use(loggingMiddleware)

A more complex authentication middleware, which maps session token to users, could be written as:

// Define our struct
type authenticationMiddleware struct {
	tokenUsers map[string]string
}

// Initialize it somewhere
func (amw *authenticationMiddleware) Populate() {
	amw.tokenUsers["00000000"] = "user0"
	amw.tokenUsers["aaaaaaaa"] = "userA"
	amw.tokenUsers["05f717e5"] = "randomUser"
	amw.tokenUsers["deadbeef"] = "user0"
}

// Middleware function, which will be called for each request
func (amw *authenticationMiddleware) Middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        token := r.Header.Get("X-Session-Token")

        if user, found := amw.tokenUsers[token]; found {
        	// We found the token in our map
        	log.Printf("Authenticated user %s\n", user)
        	// Pass down the request to the next middleware (or final handler)
        	next.ServeHTTP(w, r)
        } else {
        	// Write an error and stop the handler chain
        	http.Error(w, "Forbidden", http.StatusForbidden)
        }
    })
}

r := mux.NewRouter()
r.HandleFunc("/", handler)

amw := authenticationMiddleware{tokenUsers: make(map[string]string)}
amw.Populate()

r.Use(amw.Middleware)

Note: The handler chain will be stopped if your middleware doesn't call next.ServeHTTP() with the corresponding parameters. This can be used to abort a request if the middleware writer wants to. Middlewares should write to ResponseWriter if they are going to terminate the request, and they should not write to ResponseWriter if they are not going to terminate it.

Handling CORS Requests Copy Section

CORSMethodMiddleware intends to make it easier to strictly set the Access-Control-Allow-Methods response header.

• You will still need to use your own CORS handler to set the other CORS headers such as Access-Control-Allow-Origin
• The middleware will set the Access-Control-Allow-Methods header to all the method matchers (e.g. r.Methods(http.MethodGet, http.MethodPut, http.MethodOptions) -> Access-Control-Allow-Methods: GET,PUT,OPTIONS) on a route
• If you do not specify any methods, then:

Important: there must be an OPTIONS method matcher for the middleware to set the headers.

Here is an example of using CORSMethodMiddleware along with a custom OPTIONS handler to set all the required CORS headers:

package main

import (
	"net/http"
	"github.com/gorilla/mux"
)

func main() {
    r := mux.NewRouter()

    // IMPORTANT: you must specify an OPTIONS method matcher for the middleware to set CORS headers
    r.HandleFunc("/foo", fooHandler).Methods(http.MethodGet, http.MethodPut, http.MethodPatch, http.MethodOptions)
    r.Use(mux.CORSMethodMiddleware(r))
    
    http.ListenAndServe(":8080", r)
}

func fooHandler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Access-Control-Allow-Origin", "*")
    if r.Method == http.MethodOptions {
        return
    }

    w.Write([]byte("foo"))
}

And an request to /foo using something like:

curl localhost:8080/foo -v

Would look like:

*   Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 8080 (#0)
> GET /foo HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.59.0
> Accept: */*
> 
< HTTP/1.1 200 OK
< Access-Control-Allow-Methods: GET,PUT,PATCH,OPTIONS
< Access-Control-Allow-Origin: *
< Date: Fri, 28 Jun 2019 20:13:30 GMT
< Content-Length: 3
< Content-Type: text/plain; charset=utf-8
< 
* Connection #0 to host localhost left intact
foo

Testing Handlers Copy Section

Testing handlers in a Go web application is straightforward, and mux doesn't complicate this any further. Given two files: endpoints.go and endpoints_test.go, here's how we'd test an application using mux.

First, our simple HTTP handler:

// endpoints.go
package main

func HealthCheckHandler(w http.ResponseWriter, r *http.Request) {
    // A very simple health check.
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusOK)

    // In the future we could report back on the status of our DB, or our cache
    // (e.g. Redis) by performing a simple PING, and include them in the response.
    io.WriteString(w, `{"alive": true}`)
}

func main() {
    r := mux.NewRouter()
    r.HandleFunc("/health", HealthCheckHandler)

    log.Fatal(http.ListenAndServe("localhost:8080", r))
}

Our test code:

// endpoints_test.go
package main

import (
    "net/http"
    "net/http/httptest"
    "testing"
)

func TestHealthCheckHandler(t *testing.T) {
    // Create a request to pass to our handler. We don't have any query parameters for now, so we'll
    // pass 'nil' as the third parameter.
    req, err := http.NewRequest("GET", "/health", nil)
    if err != nil {
        t.Fatal(err)
    }

    // We create a ResponseRecorder (which satisfies http.ResponseWriter) to record the response.
    rr := httptest.NewRecorder()
    handler := http.HandlerFunc(HealthCheckHandler)

    // Our handlers satisfy http.Handler, so we can call their ServeHTTP method
    // directly and pass in our Request and ResponseRecorder.
    handler.ServeHTTP(rr, req)

    // Check the status code is what we expect.
    if status := rr.Code; status != http.StatusOK {
        t.Errorf("handler returned wrong status code: got %v want %v",
            status, http.StatusOK)
    }

    // Check the response body is what we expect.
    expected := `{"alive": true}`
    if rr.Body.String() != expected {
        t.Errorf("handler returned unexpected body: got %v want %v",
            rr.Body.String(), expected)
    }
}

In the case that our routes have variables, we can pass those in the request. We could write
table-driven tests to test multiple
possible route variables as needed.

// endpoints.go
func main() {
    r := mux.NewRouter()
    // A route with a route variable:
    r.HandleFunc("/metrics/{type}", MetricsHandler)

    log.Fatal(http.ListenAndServe("localhost:8080", r))
}

Our test file, with a table-driven test of routeVariables:

// endpoints_test.go
func TestMetricsHandler(t *testing.T) {
    tt := []struct{
        routeVariable string
        shouldPass bool
    }{
        {"goroutines", true},
        {"heap", true},
        {"counters", true},
        {"queries", true},
        {"adhadaeqm3k", false},
    }

    for _, tc := range tt {
        path := fmt.Sprintf("/metrics/%s", tc.routeVariable)
        req, err := http.NewRequest("GET", path, nil)
        if err != nil {
            t.Fatal(err)
        }

        rr := httptest.NewRecorder()
	
	// To add the vars to the context, 
	// we need to create a router through which we can pass the request.
	router := mux.NewRouter()
        router.HandleFunc("/metrics/{type}", MetricsHandler)
        router.ServeHTTP(rr, req)

        // In this case, our MetricsHandler returns a non-200 response
        // for a route variable it doesn't know about.
        if rr.Code == http.StatusOK && !tc.shouldPass {
            t.Errorf("handler should have failed on routeVariable %s: got %v want %v",
                tc.routeVariable, rr.Code, http.StatusOK)
        }
    }
}

Full Example Copy Chapter

Here's a complete, runnable example of a small mux based server:

package main

import (
    "net/http"
    "log"
    "github.com/gorilla/mux"
)

func YourHandler(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("Gorilla!\n"))
}

func main() {
    r := mux.NewRouter()
    // Routes consist of a path and a handler function.
    r.HandleFunc("/", YourHandler)

    // Bind to a port and pass our router in
    log.Fatal(http.ListenAndServe(":8000", r))
}

License Copy Chapter

BSD licensed. See the LICENSE file for details.

Overview (`vendor/github.com/hashicorp/go-cleanhttp/README.md`) Copy Section

cleanhttp

Functions for accessing "clean" Go http.Client values

The Go standard library contains a default http.Client called
http.DefaultClient. It is a common idiom in Go code to start with
http.DefaultClient and tweak it as necessary, and in fact, this is
encouraged; from the http package documentation:

The Client's Transport typically has internal state (cached TCP connections),
so Clients should be reused instead of created as needed. Clients are safe for
concurrent use by multiple goroutines.

Unfortunately, this is a shared value, and it is not uncommon for libraries to
assume that they are free to modify it at will. With enough dependencies, it
can be very easy to encounter strange problems and race conditions due to
manipulation of this shared value across libraries and goroutines (clients are
safe for concurrent use, but writing values to the client struct itself is not
protected).

Making things worse is the fact that a bare http.Client will use a default
http.Transport called http.DefaultTransport, which is another global value
that behaves the same way. So it is not simply enough to replace
http.DefaultClient with &http.Client{}.

This repository provides some simple functions to get a "clean" http.Client
-- one that uses the same default values as the Go standard library, but
returns a client that does not share any state with other clients.

Overview (`vendor/github.com/hashicorp/go-multierror/README.md`) Copy Section

go-multierror

go-multierror is a package for Go that provides a mechanism for
representing a list of error values as a single error.

This allows a function in Go to return an error that might actually
be a list of errors. If the caller knows this, they can unwrap the
list and access the errors. If the caller doesn't know, the error
formats to a nice human-readable format.

go-multierror is fully compatible with the Go standard library
errors package, including the
functions As, Is, and Unwrap. This provides a standardized approach
for introspecting on error values.

Installation and Docs Copy Chapter

Install using go get github.com/hashicorp/go-multierror.

Full documentation is available at
https://pkg.go.dev/github.com/hashicorp/go-multierror

Requires go version 1.13 or newer Copy Section

go-multierror requires go version 1.13 or newer. Go 1.13 introduced
error wrapping, which
this library takes advantage of.

If you need to use an earlier version of go, you can use the
v1.0.0
tag, which doesn't rely on features in go 1.13.

If you see compile errors that look like the below, it's likely that
you're on an older version of go:

/go/src/github.com/hashicorp/go-multierror/multierror.go:112:9: undefined: errors.As
/go/src/github.com/hashicorp/go-multierror/multierror.go:117:9: undefined: errors.Is

Usage Copy Chapter

go-multierror is easy to use and purposely built to be unobtrusive in
existing Go applications/libraries that may not be aware of it.

Building a list of errors

The Append function is used to create a list of errors. This function
behaves a lot like the Go built-in append function: it doesn't matter
if the first argument is nil, a multierror.Error, or any other error,
the function behaves as you would expect.

var result error

if err := step1(); err != nil {
	result = multierror.Append(result, err)
}
if err := step2(); err != nil {
	result = multierror.Append(result, err)
}

return result

Customizing the formatting of the errors

By specifying a custom ErrorFormat, you can customize the format
of the Error() string function:

var result *multierror.Error

// ... accumulate errors here, maybe using Append

if result != nil {
	result.ErrorFormat = func([]error) string {
		return "errors!"
	}
}

Accessing the list of errors

multierror.Error implements error so if the caller doesn't know about
multierror, it will work just fine. But if you're aware a multierror might
be returned, you can use type switches to access the list of errors:

if err := something(); err != nil {
	if merr, ok := err.(*multierror.Error); ok {
		// Use merr.Errors
	}
}

You can also use the standard errors.Unwrap
function. This will continue to unwrap into subsequent errors until none exist.

Extracting an error

The standard library errors.As
function can be used directly with a multierror to extract a specific error:

// Assume err is a multierror value
err := somefunc()

// We want to know if "err" has a "RichErrorType" in it and extract it.
var errRich RichErrorType
if errors.As(err, &errRich) {
	// It has it, and now errRich is populated.
}

Checking for an exact error value

Some errors are returned as exact errors such as the ErrNotExist
error in the os package. You can check if this error is present by using
the standard errors.Is function.

// Assume err is a multierror value
err := somefunc()
if errors.Is(err, os.ErrNotExist) {
	// err contains os.ErrNotExist
}

Returning a multierror only if there are errors

If you build a multierror.Error, you can use the ErrorOrNil function
to return an error implementation only if there are errors to return:

var result *multierror.Error

// ... accumulate errors here

// Return the `error` only if errors were added to the multierror, otherwise
// return nil since there are no errors.
return result.ErrorOrNil()

Overview (`vendor/github.com/hashicorp/go-retryablehttp/README.md`) Copy Section

go-retryablehttp

The retryablehttp package provides a familiar HTTP client interface with
automatic retries and exponential backoff. It is a thin wrapper over the
standard net/http client library and exposes nearly the same public API. This
makes retryablehttp very easy to drop into existing programs.

retryablehttp performs automatic retries under certain conditions. Mainly, if
an error is returned by the client (connection errors, etc.), or if a 500-range
response code is received (except 501), then a retry is invoked after a wait
period. Otherwise, the response is returned and left to the caller to
interpret.

The main difference from net/http is that requests which take a request body
(POST/PUT et. al) can have the body provided in a number of ways (some more or
less efficient) that allow "rewinding" the request body if the initial request
fails so that the full request can be attempted again. See the
godoc for more
details.

Version 0.6.0 and before are compatible with Go prior to 1.12. From 0.6.1 onward, Go 1.12+ is required.
From 0.6.7 onward, Go 1.13+ is required.

Example Use

Using this library should look almost identical to what you would do with
net/http. The most simple example of a GET request is shown below:

resp, err := retryablehttp.Get("/foo")
if err != nil {
    panic(err)
}

The returned response object is an *http.Response, the same thing you would
usually get from net/http. Had the request failed one or more times, the above
call would block and retry with exponential backoff.

Getting a stdlib `*http.Client` with retries Copy Chapter

It's possible to convert a *retryablehttp.Client directly to a *http.Client.
This makes use of retryablehttp broadly applicable with minimal effort. Simply
configure a *retryablehttp.Client as you wish, and then call StandardClient():

retryClient := retryablehttp.NewClient()
retryClient.RetryMax = 10

standardClient := retryClient.StandardClient() // *http.Client

For more usage and examples see the
pkg.go.dev.

Overview (`vendor/github.com/inconshreveable/mousetrap/README.md`) Copy Section

mousetrap

mousetrap is a tiny library that answers a single question.

On a Windows machine, was the process invoked by someone double clicking on
the executable file while browsing in explorer?

Motivation Copy Section

Windows developers unfamiliar with command line tools will often "double-click"
the executable for a tool. Because most CLI tools print the help and then exit
when invoked without arguments, this is often very frustrating for those users.

mousetrap provides a way to detect these invocations so that you can provide
more helpful behavior and instructions on how to run the CLI tool. To see what
this looks like, both from an organizational and a technical perspective, see
https://inconshreveable.com/09-09-2014/sweat-the-small-stuff/

The interface Copy Section

The library exposes a single interface:

func StartedByExplorer() (bool)

Overview (`vendor/github.com/json-iterator/go/README.md`) Copy Section

A high-performance 100% compatible drop-in replacement of "encoding/json"

Benchmark

Source code: https://github.com/json-iterator/go-benchmark/blob/master/src/github.com/json-iterator/go-benchmark/benchmark_medium_payload_test.go

Raw Result (easyjson requires static code generation)

Always benchmark with your own workload.
The result depends heavily on the data input.

Usage

100% compatibility with standard lib

Replace

import "encoding/json"
json.Marshal(&data)

with

import jsoniter "github.com/json-iterator/go"

var json = jsoniter.ConfigCompatibleWithStandardLibrary
json.Marshal(&data)

Replace

import "encoding/json"
json.Unmarshal(input, &data)

with

import jsoniter "github.com/json-iterator/go"

var json = jsoniter.ConfigCompatibleWithStandardLibrary
json.Unmarshal(input, &data)

More documentation

How to get

go get github.com/json-iterator/go

Contribution Welcomed !

Contributors

• thockin
• mattn
• cch123
• Oleg Shaldybin
• Jason Toffaletti

Report issue or pull request, or email [email protected], or

Overview (`vendor/github.com/klauspost/compress/README.md`) Copy Section

compress

This package provides various compression algorithms.

• zstandard compression and decompression in pure Go.
• S2 is a high performance replacement for Snappy.
• Optimized deflate packages which can be used as a dropin replacement for gzip, zip and zlib.
• snappy is a drop-in replacement for github.com/golang/snappy offering better compression and concurrent streams.
• huff0 and FSE implementations for raw entropy encoding.
• gzhttp Provides client and server wrappers for handling gzipped/zstd HTTP requests efficiently.
• pgzip is a separate package that provides a very fast parallel gzip implementation.

package usage

Use go get github.com/klauspost/compress@latest to add it to your project.

This package will support the current Go version and 2 versions back.

• Use the nounsafe tag to disable all use of the "unsafe" package.
• Use the noasm tag to disable all assembly across packages.

Use the links above for more information on each.

changelog

• Jul 1st, 2026 1.19.0

  • zstd: Add true concurrent stream encodingin https://github.com/klauspost/compress/pull/1136
  • zstd: arm64 decoder asm by @lizthegrey in https://github.com/klauspost/compress/pull/1160
  • flate: Add inflate checkpoints in https://github.com/klauspost/compress/pull/1154
  • zstd: avoid unused BuildDict encoder allocation by @snissn in https://github.com/klauspost/compress/pull/1147
  • snappy/s2: Limit length of varint in decodedLen by @eustas in https://github.com/klauspost/compress/pull/1148
  • gzhttp: match qvalue parameter case-insensitively (RFC 7231) by @z9z in https://github.com/klauspost/compress/pull/1149
  • zip: add NameDecoder callback for legacy encoding rewrite by @SAY-5 in https://github.com/klauspost/compress/pull/1150
  • huff0: Allow building tables from histogram in https://github.com/klauspost/compress/pull/1155
  • huff0: Allow building table from oversized histogram in https://github.com/klauspost/compress/pull/1156
  • s2sx: Clean symlink targets in https://github.com/klauspost/compress/pull/1163

• Feb 9th, 2026 1.18.4

  • gzhttp: Add zstandard to server handler wrapper https://github.com/klauspost/compress/pull/1121
  • zstd: Add ResetWithOptions to encoder/decoder https://github.com/klauspost/compress/pull/1122
  • gzhttp: preserve qvalue when extra parameters follow in Accept-Encoding by @analytically in https://github.com/klauspost/compress/pull/1116

• Jan 16th, 2026 1.18.3

  • Downstream CVE-2025-61728. See golang/go#77102.

• Dec 1st, 2025 - 1.18.2

  • flate: Fix invalid encoding on level 9 with single value input in https://github.com/klauspost/compress/pull/1115
  • flate: reduce stateless allocations by @RXamzin in https://github.com/klauspost/compress/pull/1106

• Oct 20, 2025 - 1.18.1 - RETRACTED

  • zstd: Add simple zstd EncodeTo/DecodeTo functions https://github.com/klauspost/compress/pull/1079
  • zstd: Fix incorrect buffer size in dictionary encodes https://github.com/klauspost/compress/pull/1059
  • s2: check for cap, not len of buffer in EncodeBetter/Best by @vdarulis in https://github.com/klauspost/compress/pull/1080
  • zlib: Avoiding extra allocation in zlib.reader.Reset by @travelpolicy in https://github.com/klauspost/compress/pull/1086
  • gzhttp: remove redundant err check in zstdReader by @ryanfowler in https://github.com/klauspost/compress/pull/1090
  • flate: Faster load+store https://github.com/klauspost/compress/pull/1104
  • flate: Simplify matchlen https://github.com/klauspost/compress/pull/1101
  • flate: Use exact sizes for huffman tables https://github.com/klauspost/compress/pull/1103

• Feb 19th, 2025 - 1.18.0

  • Add unsafe little endian loaders https://github.com/klauspost/compress/pull/1036

  • fix: check r.err != nil but return a nil value error err by @alingse in https://github.com/klauspost/compress/pull/1028

  • flate: Simplify L4-6 loading https://github.com/klauspost/compress/pull/1043

  • flate: Simplify matchlen (remove asm) https://github.com/klauspost/compress/pull/1045

  • s2: Improve small block compression speed w/o asm https://github.com/klauspost/compress/pull/1048

  • flate: Fix matchlen L5+L6 https://github.com/klauspost/compress/pull/1049

  • flate: Cleanup & reduce casts https://github.com/klauspost/compress/pull/1050

    See changes to v1.17.x

• Oct 11th, 2024 - 1.17.11

  • zstd: Fix extra CRC written with multiple Close calls https://github.com/klauspost/compress/pull/1017
  • s2: Don't use stack for index tables https://github.com/klauspost/compress/pull/1014
  • gzhttp: No content-type on no body response code by @juliens in https://github.com/klauspost/compress/pull/1011
  • gzhttp: Do not set the content-type when response has no body by @kevinpollet in https://github.com/klauspost/compress/pull/1013

• Sep 23rd, 2024 - 1.17.10

  • gzhttp: Add TransportAlwaysDecompress option. https://github.com/klauspost/compress/pull/978
  • gzhttp: Add supported decompress request body by @mirecl in https://github.com/klauspost/compress/pull/1002
  • s2: Add EncodeBuffer buffer recycling callback https://github.com/klauspost/compress/pull/982
  • zstd: Improve memory usage on small streaming encodes https://github.com/klauspost/compress/pull/1007
  • flate: read data written with partial flush by @vajexal in https://github.com/klauspost/compress/pull/996

• Jun 12th, 2024 - 1.17.9

  • s2: Reduce ReadFrom temporary allocations https://github.com/klauspost/compress/pull/949
  • flate, zstd: Shave some bytes off amd64 matchLen by @greatroar in https://github.com/klauspost/compress/pull/963
  • Upgrade zip/zlib to 1.22.4 upstream https://github.com/klauspost/compress/pull/970 https://github.com/klauspost/compress/pull/971
  • zstd: BuildDict fails with RLE table https://github.com/klauspost/compress/pull/951

• Apr 9th, 2024 - 1.17.8

  • zstd: Reject blocks where reserved values are not 0 https://github.com/klauspost/compress/pull/885
  • zstd: Add RLE detection+encoding https://github.com/klauspost/compress/pull/938

• Feb 21st, 2024 - 1.17.7

  • s2: Add AsyncFlush method: Complete the block without flushing by @Jille in https://github.com/klauspost/compress/pull/927
  • s2: Fix literal+repeat exceeds dst crash https://github.com/klauspost/compress/pull/930

• Feb 5th, 2024 - 1.17.6

  • zstd: Fix incorrect repeat coding in best mode https://github.com/klauspost/compress/pull/923
  • s2: Fix DecodeConcurrent deadlock on errors https://github.com/klauspost/compress/pull/925

• Jan 26th, 2024 - v1.17.5

  • flate: Fix reset with dictionary on custom window encodes https://github.com/klauspost/compress/pull/912
  • zstd: Add Frame header encoding and stripping https://github.com/klauspost/compress/pull/908
  • zstd: Limit better/best default window to 8MB https://github.com/klauspost/compress/pull/913
  • zstd: Speed improvements by @greatroar in https://github.com/klauspost/compress/pull/896 https://github.com/klauspost/compress/pull/910
  • s2: Fix callbacks for skippable blocks and disallow 0xfe (Padding) by @Jille in https://github.com/klauspost/compress/pull/916 https://github.com/klauspost/compress/pull/917
    https://github.com/klauspost/compress/pull/919 https://github.com/klauspost/compress/pull/918

• Dec 1st, 2023 - v1.17.4

  • huff0: Speed up symbol counting by @greatroar in https://github.com/klauspost/compress/pull/887
  • huff0: Remove byteReader by @greatroar in https://github.com/klauspost/compress/pull/886
  • gzhttp: Allow overriding decompression on transport https://github.com/klauspost/compress/pull/892
  • gzhttp: Clamp compression level https://github.com/klauspost/compress/pull/890
  • gzip: Error out if reserved bits are set https://github.com/klauspost/compress/pull/891

• Nov 15th, 2023 - v1.17.3

  • fse: Fix max header size https://github.com/klauspost/compress/pull/881
  • zstd: Improve better/best compression https://github.com/klauspost/compress/pull/877
  • gzhttp: Fix missing content type on Close https://github.com/klauspost/compress/pull/883

• Oct 22nd, 2023 - v1.17.2

  • zstd: Fix rare CORRUPTION output in "best" mode. See https://github.com/klauspost/compress/pull/876

• Oct 14th, 2023 - v1.17.1

  • s2: Fix S2 "best" dictionary wrong encoding https://github.com/klauspost/compress/pull/871
  • flate: Reduce allocations in decompressor and minor code improvements by @fakefloordiv in https://github.com/klauspost/compress/pull/869
  • s2: Fix EstimateBlockSize on 6&7 length input https://github.com/klauspost/compress/pull/867

• Sept 19th, 2023 - v1.17.0

  • Add experimental dictionary builder https://github.com/klauspost/compress/pull/853
  • Add xerial snappy read/writer https://github.com/klauspost/compress/pull/838
  • flate: Add limited window compression https://github.com/klauspost/compress/pull/843
  • s2: Do 2 overlapping match checks https://github.com/klauspost/compress/pull/839
  • flate: Add amd64 assembly matchlen https://github.com/klauspost/compress/pull/837
  • gzip: Copy bufio.Reader on Reset by @thatguystone in https://github.com/klauspost/compress/pull/860

  See changes to v1.16.x

• July 1st, 2023 - v1.16.7

  • zstd: Fix default level first dictionary encode https://github.com/klauspost/compress/pull/829
  • s2: add GetBufferCapacity() method by @GiedriusS in https://github.com/klauspost/compress/pull/832

• June 13, 2023 - v1.16.6

  • zstd: correctly ignore WithEncoderPadding(1) by @ianlancetaylor in https://github.com/klauspost/compress/pull/806
  • zstd: Add amd64 match length assembly https://github.com/klauspost/compress/pull/824
  • gzhttp: Handle informational headers by @rtribotte in https://github.com/klauspost/compress/pull/815
  • s2: Improve Better compression slightly https://github.com/klauspost/compress/pull/663

• Apr 16, 2023 - v1.16.5

  • zstd: readByte needs to use io.ReadFull by @jnoxon in https://github.com/klauspost/compress/pull/802
  • gzip: Fix WriterTo after initial read https://github.com/klauspost/compress/pull/804

• Apr 5, 2023 - v1.16.4

  • zstd: Improve zstd best efficiency by @greatroar and @klauspost in https://github.com/klauspost/compress/pull/784
  • zstd: Respect WithAllLitEntropyCompression https://github.com/klauspost/compress/pull/792
  • zstd: Fix amd64 not always detecting corrupt data https://github.com/klauspost/compress/pull/785
  • zstd: Various minor improvements by @greatroar in https://github.com/klauspost/compress/pull/788 https://github.com/klauspost/compress/pull/794 https://github.com/klauspost/compress/pull/795
  • s2: Fix huge block overflow https://github.com/klauspost/compress/pull/779
  • s2: Allow CustomEncoder fallback https://github.com/klauspost/compress/pull/780
  • gzhttp: Support ResponseWriter Unwrap() in gzhttp handler by @jgimenez in https://github.com/klauspost/compress/pull/799

• Mar 13, 2023 - v1.16.1

  • zstd: Speed up + improve best encoder by @greatroar in https://github.com/klauspost/compress/pull/776
  • gzhttp: Add optional BREACH mitigation. https://github.com/klauspost/compress/pull/762 https://github.com/klauspost/compress/pull/768 https://github.com/klauspost/compress/pull/769 https://github.com/klauspost/compress/pull/770 https://github.com/klauspost/compress/pull/767
  • s2: Add Intel LZ4s converter https://github.com/klauspost/compress/pull/766
  • zstd: Minor bug fixes https://github.com/klauspost/compress/pull/771 https://github.com/klauspost/compress/pull/772 https://github.com/klauspost/compress/pull/773
  • huff0: Speed up compress1xDo by @greatroar in https://github.com/klauspost/compress/pull/774

• Feb 26, 2023 - v1.16.0

  • s2: Add Dictionary support. https://github.com/klauspost/compress/pull/685
  • s2: Add Compression Size Estimate. https://github.com/klauspost/compress/pull/752
  • s2: Add support for custom stream encoder. https://github.com/klauspost/compress/pull/755
  • s2: Add LZ4 block converter. https://github.com/klauspost/compress/pull/748
  • s2: Support io.ReaderAt in ReadSeeker. https://github.com/klauspost/compress/pull/747
  • s2c/s2sx: Use concurrent decoding. https://github.com/klauspost/compress/pull/746

  See changes to v1.15.x

• Jan 21st, 2023 (v1.15.15)

  • deflate: Improve level 7-9 https://github.com/klauspost/compress/pull/739
  • zstd: Add delta encoding support by @greatroar in https://github.com/klauspost/compress/pull/728
  • zstd: Various speed improvements by @greatroar https://github.com/klauspost/compress/pull/741 https://github.com/klauspost/compress/pull/734 https://github.com/klauspost/compress/pull/736 https://github.com/klauspost/compress/pull/744 https://github.com/klauspost/compress/pull/743 https://github.com/klauspost/compress/pull/745
  • gzhttp: Add SuffixETag() and DropETag() options to prevent ETag collisions on compressed responses by @willbicks in https://github.com/klauspost/compress/pull/740

• Jan 3rd, 2023 (v1.15.14)

  • flate: Improve speed in big stateless blocks https://github.com/klauspost/compress/pull/718
  • zstd: Minor speed tweaks by @greatroar in https://github.com/klauspost/compress/pull/716 https://github.com/klauspost/compress/pull/720
  • export NoGzipResponseWriter for custom ResponseWriter wrappers by @harshavardhana in https://github.com/klauspost/compress/pull/722
  • s2: Add example for indexing and existing stream https://github.com/klauspost/compress/pull/723

• Dec 11, 2022 (v1.15.13)

  • zstd: Add MaxEncodedSize to encoder https://github.com/klauspost/compress/pull/691
  • zstd: Various tweaks and improvements https://github.com/klauspost/compress/pull/693 https://github.com/klauspost/compress/pull/695 https://github.com/klauspost/compress/pull/696 https://github.com/klauspost/compress/pull/701 https://github.com/klauspost/compress/pull/702 https://github.com/klauspost/compress/pull/703 https://github.com/klauspost/compress/pull/704 https://github.com/klauspost/compress/pull/705 https://github.com/klauspost/compress/pull/706 https://github.com/klauspost/compress/pull/707 https://github.com/klauspost/compress/pull/708

• Oct 26, 2022 (v1.15.12)

  • zstd: Tweak decoder allocs. https://github.com/klauspost/compress/pull/680
  • gzhttp: Always delete HeaderNoCompression https://github.com/klauspost/compress/pull/683

• Sept 26, 2022 (v1.15.11)

  • flate: Improve level 1-3 compression https://github.com/klauspost/compress/pull/678
  • zstd: Improve "best" compression by @nightwolfz in https://github.com/klauspost/compress/pull/677
  • zstd: Fix+reduce decompression allocations https://github.com/klauspost/compress/pull/668
  • zstd: Fix non-effective noescape tag https://github.com/klauspost/compress/pull/667

• Sept 16, 2022 (v1.15.10)

  • zstd: Add WithDecodeAllCapLimit https://github.com/klauspost/compress/pull/649
  • Add Go 1.19 - deprecate Go 1.16 https://github.com/klauspost/compress/pull/651
  • flate: Improve level 5+6 compression https://github.com/klauspost/compress/pull/656
  • zstd: Improve "better" compression https://github.com/klauspost/compress/pull/657
  • s2: Improve "best" compression https://github.com/klauspost/compress/pull/658
  • s2: Improve "better" compression. https://github.com/klauspost/compress/pull/635
  • s2: Slightly faster non-assembly decompression https://github.com/klauspost/compress/pull/646
  • Use arrays for constant size copies https://github.com/klauspost/compress/pull/659

• July 21, 2022 (v1.15.9)

  • zstd: Fix decoder crash on amd64 (no BMI) on invalid input https://github.com/klauspost/compress/pull/645
  • zstd: Disable decoder extended memory copies (amd64) due to possible crashes https://github.com/klauspost/compress/pull/644
  • zstd: Allow single segments up to "max decoded size" https://github.com/klauspost/compress/pull/643

• July 13, 2022 (v1.15.8)

  • gzip: fix stack exhaustion bug in Reader.Read https://github.com/klauspost/compress/pull/641
  • s2: Add Index header trim/restore https://github.com/klauspost/compress/pull/638
  • zstd: Optimize seqdeq amd64 asm by @greatroar in https://github.com/klauspost/compress/pull/636
  • zstd: Improve decoder memcopy https://github.com/klauspost/compress/pull/637
  • huff0: Pass a single bitReader pointer to asm by @greatroar in https://github.com/klauspost/compress/pull/634
  • zstd: Branchless getBits for amd64 w/o BMI2 by @greatroar in https://github.com/klauspost/compress/pull/640
  • gzhttp: Remove header before writing https://github.com/klauspost/compress/pull/639

• June 29, 2022 (v1.15.7)

  • s2: Fix absolute forward seeks https://github.com/klauspost/compress/pull/633
  • zip: Merge upstream https://github.com/klauspost/compress/pull/631
  • zip: Re-add zip64 fix https://github.com/klauspost/compress/pull/624
  • zstd: translate fseDecoder.buildDtable into asm by @WojciechMula in https://github.com/klauspost/compress/pull/598
  • flate: Faster histograms https://github.com/klauspost/compress/pull/620
  • deflate: Use compound hcode https://github.com/klauspost/compress/pull/622

• June 3, 2022 (v1.15.6)

  • s2: Improve coding for long, close matches https://github.com/klauspost/compress/pull/613
  • s2c: Add Snappy/S2 stream recompression https://github.com/klauspost/compress/pull/611
  • zstd: Always use configured block size https://github.com/klauspost/compress/pull/605
  • zstd: Fix incorrect hash table placement for dict encoding in default https://github.com/klauspost/compress/pull/606
  • zstd: Apply default config to ZipDecompressor without options https://github.com/klauspost/compress/pull/608
  • gzhttp: Exclude more common archive formats https://github.com/klauspost/compress/pull/612
  • s2: Add ReaderIgnoreCRC https://github.com/klauspost/compress/pull/609
  • s2: Remove sanity load on index creation https://github.com/klauspost/compress/pull/607
  • snappy: Use dedicated function for scoring https://github.com/klauspost/compress/pull/614
  • s2c+s2d: Use official snappy framed extension https://github.com/klauspost/compress/pull/610

• May 25, 2022 (v1.15.5)

  • s2: Add concurrent stream decompression https://github.com/klauspost/compress/pull/602
  • s2: Fix final emit oob read crash on amd64 https://github.com/klauspost/compress/pull/601
  • huff0: asm implementation of Decompress1X by @WojciechMula https://github.com/klauspost/compress/pull/596
  • zstd: Use 1 less goroutine for stream decoding https://github.com/klauspost/compress/pull/588
  • zstd: Copy literal in 16 byte blocks when possible https://github.com/klauspost/compress/pull/592
  • zstd: Speed up when WithDecoderLowmem(false) https://github.com/klauspost/compress/pull/599
  • zstd: faster next state update in BMI2 version of decode by @WojciechMula in https://github.com/klauspost/compress/pull/593
  • huff0: Do not check max size when reading table. https://github.com/klauspost/compress/pull/586
  • flate: Inplace hashing for level 7-9 https://github.com/klauspost/compress/pull/590

• May 11, 2022 (v1.15.4)

  • huff0: decompress directly into output by @WojciechMula in #577
  • inflate: Keep dict on stack #581
  • zstd: Faster decoding memcopy in asm #583
  • zstd: Fix ignored crc #580

• May 5, 2022 (v1.15.3)

  • zstd: Allow to ignore checksum checking by @WojciechMula #572
  • s2: Fix incorrect seek for io.SeekEnd in #575

• Apr 26, 2022 (v1.15.2)

  • zstd: Add x86-64 assembly for decompression on streams and blocks. Contributed by @WojciechMula. Typically 2x faster. #528 #531 #545 #537
  • zstd: Add options to ZipDecompressor and fixes #539
  • s2: Use sorted search for index #555
  • Minimum version is Go 1.16, added CI test on 1.18.

• Mar 11, 2022 (v1.15.1)

  • huff0: Add x86 assembly of Decode4X by @WojciechMula in #512
  • zstd: Reuse zip decoders in #514
  • zstd: Detect extra block data and report as corrupted in #520
  • zstd: Handle zero sized frame content size stricter in #521
  • zstd: Add stricter block size checks in #523

• Mar 3, 2022 (v1.15.0)

  • zstd: Refactor decoder #498
  • zstd: Add stream encoding without goroutines #505
  • huff0: Prevent single blocks exceeding 16 bits by @klauspost in#507
  • flate: Inline literal emission #509
  • gzhttp: Add zstd to transport #400
  • gzhttp: Make content-type optional #510

Both compression and decompression now supports "synchronous" stream operations. This means that whenever "concurrency" is set to 1, they will operate without spawning goroutines.

Stream decompression is now faster on asynchronous, since the goroutine allocation much more effectively splits the workload. On typical streams this will typically use 2 cores fully for decompression. When a stream has finished decoding no goroutines will be left over, so decoders can now safely be pooled and still be garbage collected.

While the release has been extensively tested, it is recommended to testing when upgrading.

See changes to v1.14.x

• Feb 22, 2022 (v1.14.4)

  • flate: Fix rare huffman only (-2) corruption. #503
  • zip: Update deprecated CreateHeaderRaw to correctly call CreateRaw by @saracen in #502
  • zip: don't read data descriptor early by @saracen in #501 #501
  • huff0: Use static decompression buffer up to 30% faster #499 #500

• Feb 17, 2022 (v1.14.3)

  • flate: Improve fastest levels compression speed ~10% more throughput. #482 #489 #490 #491 #494 #478
  • flate: Faster decompression speed, ~5-10%. #483
  • s2: Faster compression with Go v1.18 and amd64 microarch level 3+. #484 #486

• Jan 25, 2022 (v1.14.2)

  • zstd: improve header decoder by @dsnet #476
  • zstd: Add bigger default blocks #469
  • zstd: Remove unused decompression buffer #470
  • zstd: Fix logically dead code by @ningmingxiao #472
  • flate: Improve level 7-9 #471 #473
  • zstd: Add noasm tag for xxhash #475

• Jan 11, 2022 (v1.14.1)

  • s2: Add stream index in #462
  • flate: Speed and efficiency improvements in #439 #461 #455 #452 #458
  • zstd: Performance improvement in #420 #456 #437 #467 #468
  • zstd: add arm64 xxhash assembly in #464
  • Add garbled for binaries for s2 in #445

  See changes to v1.13.x

• Aug 30, 2021 (v1.13.5)

  • gz/zlib/flate: Alias stdlib errors #425
  • s2: Add block support to commandline tools #413
  • zstd: pooledZipWriter should return Writers to the same pool #426
  • Removed golang/snappy as external dependency for tests #421

• Aug 12, 2021 (v1.13.4)

  • Add snappy replacement package.
  • zstd: Fix incorrect encoding in "best" mode #415

• Aug 3, 2021 (v1.13.3)

  • zstd: Improve Best compression #404
  • zstd: Fix WriteTo error forwarding #411
  • gzhttp: Return http.HandlerFunc instead of http.Handler. Unlikely breaking change. #406
  • s2sx: Fix max size error #399
  • zstd: Add optional stream content size on reset #401
  • zstd: use SpeedBestCompression for level >= 10 #410

• Jun 14, 2021 (v1.13.1)

  • s2: Add full Snappy output support #396
  • zstd: Add configurable Decoder window size #394
  • gzhttp: Add header to skip compression #389
  • s2: Improve speed with bigger output margin #395

• Jun 3, 2021 (v1.13.0)

  • Added gzhttp which allows wrapping HTTP servers and clients with GZIP compressors.
  • zstd: Detect short invalid signatures #382
  • zstd: Spawn decoder goroutine only if needed. #380

  See changes to v1.12.x

• May 25, 2021 (v1.12.3)

  • deflate: Better/faster Huffman encoding #374
  • deflate: Allocate less for history. #375
  • zstd: Forward read errors #373

• Apr 27, 2021 (v1.12.2)

  • zstd: Improve better/best compression #360 #364 #365
  • zstd: Add helpers to compress/decompress zstd inside zip files #363
  • deflate: Improve level 5+6 compression #367
  • s2: Improve better/best compression #358 #359
  • s2: Load after checking src limit on amd64. #362
  • s2sx: Limit max executable size #368

• Apr 14, 2021 (v1.12.1)

  • snappy package removed. Upstream added as dependency.
  • s2: Better compression in "best" mode #353
  • s2sx: Add stdin input and detect pre-compressed from signature #352
  • s2c/s2d: Add http as possible input #348
  • s2c/s2d/s2sx: Always truncate when writing files #352
  • zstd: Reduce memory usage further when using WithLowerEncoderMem #346
  • s2: Fix potential problem with amd64 assembly and profilers #349

  See changes to v1.11.x

• Mar 26, 2021 (v1.11.13)

  • zstd: Big speedup on small dictionary encodes #344 #345
  • zstd: Add WithLowerEncoderMem encoder option #336
  • deflate: Improve entropy compression #338
  • s2: Clean up and minor performance improvement in best #341

• Mar 5, 2021 (v1.11.12)

  • s2: Add s2sx binary that creates self extracting archives.
  • s2: Speed up decompression on non-assembly platforms #328

• Mar 1, 2021 (v1.11.9)

  • s2: Add ARM64 decompression assembly. Around 2x output speed. #324
  • s2: Improve "better" speed and efficiency. #325
  • s2: Fix binaries.

• Feb 25, 2021 (v1.11.8)

  • s2: Fixed occasional out-of-bounds write on amd64. Upgrade recommended.
  • s2: Add AMD64 assembly for better mode. 25-50% faster. #315
  • s2: Less upfront decoder allocation. #322
  • zstd: Faster "compression" of incompressible data. #314
  • zip: Fix zip64 headers. #313

• Jan 14, 2021 (v1.11.7)

  • Use Bytes() interface to get bytes across packages. #309
  • s2: Add 'best' compression option. #310
  • s2: Add ReaderMaxBlockSize, changes s2.NewReader signature to include varargs. #311
  • s2: Fix crash on small better buffers. #308
  • s2: Clean up decoder. #312

• Jan 7, 2021 (v1.11.6)

  • zstd: Make decoder allocations smaller #306
  • zstd: Free Decoder resources when Reset is called with a nil io.Reader #305

• Dec 20, 2020 (v1.11.4)

  • zstd: Add Best compression mode #304
  • Add header decoder #299
  • s2: Add uncompressed stream option #297
  • Simplify/speed up small blocks with known max size. #300
  • zstd: Always reset literal dict encoder #303

• Nov 15, 2020 (v1.11.3)

  • inflate: 10-15% faster decompression #293
  • zstd: Tweak DecodeAll default allocation #295

• Oct 11, 2020 (v1.11.2)

  • s2: Fix out of bounds read in "better" block compression #291

• Oct 1, 2020 (v1.11.1)

  • zstd: Set allLitEntropy true in default configuration #286

• Sept 8, 2020 (v1.11.0)

  • zstd: Add experimental compression dictionaries #281
  • zstd: Fix mixed Write and ReadFrom calls #282
  • inflate/gz: Limit variable shifts, ~5% faster decompression #274

  See changes to v1.10.x

• July 8, 2020 (v1.10.11)

  • zstd: Fix extra block when compressing with ReadFrom. #278
  • huff0: Also populate compression table when reading decoding table. #275

• June 23, 2020 (v1.10.10)

  • zstd: Skip entropy compression in fastest mode when no matches. #270

• June 16, 2020 (v1.10.9):

  • zstd: API change for specifying dictionaries. See #268
  • zip: update CreateHeaderRaw to handle zip64 fields. #266
  • Fuzzit tests removed. The service has been purchased and is no longer available.

• June 5, 2020 (v1.10.8):

  • 1.15x faster zstd block decompression. #265

• June 1, 2020 (v1.10.7):

  • Added zstd decompression dictionary support
  • Increase zstd decompression speed up to 1.19x. #259
  • Remove internal reset call in zstd compression and reduce allocations. #263

• May 21, 2020: (v1.10.6)

  • zstd: Reduce allocations while decoding. #258, #252
  • zstd: Stricter decompression checks.

• April 12, 2020: (v1.10.5)

  • s2-commands: Flush output when receiving SIGINT. #239

• Apr 8, 2020: (v1.10.4)

  • zstd: Minor/special case optimizations. #251, #250, #249, #247

• Mar 11, 2020: (v1.10.3)

  • s2: Use S2 encoder in pure Go mode for Snappy output as well. #245
  • s2: Fix pure Go block encoder. #244
  • zstd: Added "better compression" mode. #240
  • zstd: Improve speed of fastest compression mode by 5-10% #241
  • zstd: Skip creating encoders when not needed. #238

• Feb 27, 2020: (v1.10.2)

  • Close to 50% speedup in inflate (gzip/zip decompression). #236 #234 #232
  • Reduce deflate level 1-6 memory usage up to 59%. #227

• Feb 18, 2020: (v1.10.1)

  • Fix zstd crash when resetting multiple times without sending data. #226
  • deflate: Fix dictionary use on level 1-6. #224
  • Remove deflate writer reference when closing. #224

• Feb 4, 2020: (v1.10.0)

  • Add optional dictionary to stateless deflate. Breaking change, send nil for previous behaviour. #216
  • Fix buffer overflow on repeated small block deflate. #218
  • Allow copying content from an existing ZIP file without decompressing+compressing. #214
  • Added S2 AMD64 assembler and various optimizations. Stream speed >10GB/s. #186

  See changes prior to v1.10.0

• Jan 20,2020 (v1.9.8) Optimize gzip/deflate with better size estimates and faster table generation. #207 by luyu6056, #206.

• Jan 11, 2020: S2 Encode/Decode will use provided buffer if capacity is big enough. #204

• Jan 5, 2020: (v1.9.7) Fix another zstd regression in v1.9.5 - v1.9.6 removed.

• Jan 4, 2020: (v1.9.6) Regression in v1.9.5 fixed causing corrupt zstd encodes in rare cases.

• Jan 4, 2020: Faster IO in s2c + s2d commandline tools compression/decompression. #192

• Dec 29, 2019: Removed v1.9.5 since fuzz tests showed a compatibility problem with the reference zstandard decoder.

• Dec 29, 2019: (v1.9.5) zstd: 10-20% faster block compression. #199

• Dec 29, 2019: zip package updated with latest Go features

• Dec 29, 2019: zstd: Single segment flag condintions tweaked. #197

• Dec 18, 2019: s2: Faster compression when ReadFrom is used. #198

• Dec 10, 2019: s2: Fix repeat length output when just above at 16MB limit.

• Dec 10, 2019: zstd: Add function to get decoder as io.ReadCloser. #191

• Dec 3, 2019: (v1.9.4) S2: limit max repeat length. #188

• Dec 3, 2019: Add WithNoEntropyCompression to zstd #187

• Dec 3, 2019: Reduce memory use for tests. Check for leaked goroutines.

• Nov 28, 2019 (v1.9.3) Less allocations in stateless deflate.

• Nov 28, 2019: 5-20% Faster huff0 decode. Impacts zstd as well. #184

• Nov 12, 2019 (v1.9.2) Added Stateless Compression for gzip/deflate.

• Nov 12, 2019: Fixed zstd decompression of large single blocks. #180

• Nov 11, 2019: Set default s2c block size to 4MB.

• Nov 11, 2019: Reduce inflate memory use by 1KB.

• Nov 10, 2019: Less allocations in deflate bit writer.

• Nov 10, 2019: Fix inconsistent error returned by zstd decoder.

• Oct 28, 2019 (v1.9.1) ztsd: Fix crash when compressing blocks. #174

• Oct 24, 2019 (v1.9.0) zstd: Fix rare data corruption #173

• Oct 24, 2019 zstd: Fix huff0 out of buffer write #171 and always return errors #172

• Oct 10, 2019: Big deflate rewrite, 30-40% faster with better compression #105

  See changes prior to v1.9.0

• Oct 10, 2019: (v1.8.6) zstd: Allow partial reads to get flushed data. #169

• Oct 3, 2019: Fix inconsistent results on broken zstd streams.

• Sep 25, 2019: Added -rm (remove source files) and -q (no output except errors) to s2c and s2d commands

• Sep 16, 2019: (v1.8.4) Add s2c and s2d commandline tools.

• Sep 10, 2019: (v1.8.3) Fix s2 decoder Skip.

• Sep 7, 2019: zstd: Added WithWindowSize, contributed by ianwilkes.

• Sep 5, 2019: (v1.8.2) Add WithZeroFrames which adds full zero payload block encoding option.

• Sep 5, 2019: Lazy initialization of zstandard predefined en/decoder tables.

• Aug 26, 2019: (v1.8.1) S2: 1-2% compression increase in "better" compression mode.

• Aug 26, 2019: zstd: Check maximum size of Huffman 1X compressed literals while decoding.

• Aug 24, 2019: (v1.8.0) Added S2 compression, a high performance replacement for Snappy.

• Aug 21, 2019: (v1.7.6) Fixed minor issues found by fuzzer. One could lead to zstd not decompressing.

• Aug 18, 2019: Add fuzzit continuous fuzzing.

• Aug 14, 2019: zstd: Skip incompressible data 2x faster. #147

• Aug 4, 2019 (v1.7.5): Better literal compression. #146

• Aug 4, 2019: Faster zstd compression. #143 #144

• Aug 4, 2019: Faster zstd decompression. #145 #143 #142

• July 15, 2019 (v1.7.4): Fix double EOF block in rare cases on zstd encoder.

• July 15, 2019 (v1.7.3): Minor speedup/compression increase in default zstd encoder.

• July 14, 2019: zstd decoder: Fix decompression error on multiple uses with mixed content.

• July 7, 2019 (v1.7.2): Snappy update, zstd decoder potential race fix.

• June 17, 2019: zstd decompression bugfix.

• June 17, 2019: fix 32 bit builds.

• June 17, 2019: Easier use in modules (less dependencies).

• June 9, 2019: New stronger "default" zstd compression mode. Matches zstd default compression ratio.

• June 5, 2019: 20-40% throughput in zstandard compression and better compression.

• June 5, 2019: deflate/gzip compression: Reduce memory usage of lower compression levels.

• June 2, 2019: Added zstandard compression!

• May 25, 2019: deflate/gzip: 10% faster bit writer, mostly visible in lower levels.

• Apr 22, 2019: zstd decompression added.

• Aug 1, 2018: Added huff0 README.

• Jul 8, 2018: Added Performance Update 2018 below.

• Jun 23, 2018: Merged Go 1.11 inflate optimizations. Go 1.9 is now required. Backwards compatible version tagged with v1.3.0.

• Apr 2, 2018: Added huff0 en/decoder. Experimental for now, API may change.

• Mar 4, 2018: Added FSE Entropy en/decoder. Experimental for now, API may change.

• Nov 3, 2017: Add compression Estimate function.

• May 28, 2017: Reduce allocations when resetting decoder.

• Apr 02, 2017: Change back to official crc32, since changes were merged in Go 1.7.

• Jan 14, 2017: Reduce stack pressure due to array copies. See Issue #18625.

• Oct 25, 2016: Level 2-4 have been rewritten and now offers significantly better performance than before.

• Oct 20, 2016: Port zlib changes from Go 1.7 to fix zlib writer issue. Please update.

• Oct 16, 2016: Go 1.7 changes merged. Apples to apples this package is a few percent faster, but has a significantly better balance between speed and compression per level.

• Mar 24, 2016: Always attempt Huffman encoding on level 4-7. This improves base 64 encoded data compression.

• Mar 24, 2016: Small speedup for level 1-3.

• Feb 19, 2016: Faster bit writer, level -2 is 15% faster, level 1 is 4% faster.

• Feb 19, 2016: Handle small payloads faster in level 1-3.

• Feb 19, 2016: Added faster level 2 + 3 compression modes.

• Feb 19, 2016: Rebalanced compression levels, so there is a more even progression in terms of compression. New default level is 5.

• Feb 14, 2016: Snappy: Merge upstream changes.

• Feb 14, 2016: Snappy: Fix aggressive skipping.

• Feb 14, 2016: Snappy: Update benchmark.

• Feb 13, 2016: Deflate: Fixed assembler problem that could lead to sub-optimal compression.

• Feb 12, 2016: Snappy: Added AMD64 SSE 4.2 optimizations to matching, which makes easy to compress material run faster. Typical speedup is around 25%.

• Feb 9, 2016: Added Snappy package fork. This version is 5-7% faster, much more on hard to compress content.

• Jan 30, 2016: Optimize level 1 to 3 by not considering static dictionary or storing uncompressed. ~4-5% speedup.

• Jan 16, 2016: Optimization on deflate level 1,2,3 compression.

• Jan 8 2016: Merge CL 18317: fix reading, writing of zip64 archives.

• Dec 8 2015: Make level 1 and -2 deterministic even if write size differs.

• Dec 8 2015: Split encoding functions, so hashing and matching can potentially be inlined. 1-3% faster on AMD64. 5% faster on other platforms.

• Dec 8 2015: Fixed rare one byte out-of bounds read. Please update!

• Nov 23 2015: Optimization on token writer. ~2-4% faster. Contributed by @dsnet.

• Nov 20 2015: Small optimization to bit writer on 64 bit systems.

• Nov 17 2015: Fixed out-of-bound errors if the underlying Writer returned an error. See #15.

• Nov 12 2015: Added io.WriterTo support to gzip/inflate.

• Nov 11 2015: Merged CL 16669: archive/zip: enable overriding (de)compressors per file

• Oct 15 2015: Added skipping on uncompressible data. Random data speed up >5x.

deflate usage

The packages are drop-in replacements for standard library deflate, gzip, zip, and zlib. Simply replace the import path to use them:

Typical speed is about 2x of the standard library packages.

You may also be interested in pgzip, which is a drop-in replacement for gzip, which support multithreaded compression on big files and the optimized crc32 package used by these packages.

The packages implement the same API as the standard library, so you can use the original godoc documentation: gzip, zip, zlib, flate.

Currently there is only minor speedup on decompression (mostly CRC32 calculation).

Memory usage is typically 1MB for a Writer. stdlib is in the same range.
If you expect to have a lot of concurrently allocated Writers consider using
the stateless compression described below.

For compression performance, see: this spreadsheet.

To disable all assembly add -tags=noasm. This works across all packages.

Stateless compression

This package offers stateless compression as a special option for gzip/deflate.
It will do compression but without maintaining any state between Write calls.

This means there will be no memory kept between Write calls, but compression and speed will be suboptimal.

This is only relevant in cases where you expect to run many thousands of compressors concurrently,
but with very little activity. This is not intended for regular web servers serving individual requests.

Because of this, the size of actual Write calls will affect output size.

In gzip, specify level -3 / gzip.StatelessCompression to enable.

For direct deflate use, NewStatelessWriter and StatelessDeflate are available. See documentation

A bufio.Writer can of course be used to control write sizes. For example, to use a 4KB buffer:

// replace 'ioutil.Discard' with your output.
	gzw, err := gzip.NewWriterLevel(ioutil.Discard, gzip.StatelessCompression)
	if err != nil {
		return err
	}
	defer gzw.Close()

	w := bufio.NewWriterSize(gzw, 4096)
	defer w.Flush()
	
	// Write to 'w'

This will only use up to 4KB in memory when the writer is idle.

Compression is almost always worse than the fastest compression level
and each write will allocate (a little) memory.

Other packages

Here are other packages of good quality and pure Go (no cgo wrappers or autoconverted code):

• github.com/pierrec/lz4 - strong multithreaded LZ4 compression.
• github.com/cosnicolaou/pbzip2 - multithreaded bzip2 decompression.
• github.com/dsnet/compress - brotli decompression, bzip2 writer.
• github.com/ronanh/intcomp - Integer compression.
• github.com/spenczar/fpc - Float compression.
• github.com/minio/zipindex - External ZIP directory index.
• github.com/ybirader/pzip - Fast concurrent zip archiver and extractor.

license

This code is licensed under the same conditions as the original Go code. See LICENSE file.

Overview (`vendor/github.com/klauspost/pgzip/README.md`) Copy Section

pgzip

Go parallel gzip compression/decompression. This is a fully gzip compatible drop in replacement for "compress/gzip".

This will split compression into blocks that are compressed in parallel.
This can be useful for compressing big amounts of data. The output is a standard gzip file.

The gzip decompression is modified so it decompresses ahead of the current reader.
This means that reads will be non-blocking if the decompressor can keep ahead of your code reading from it.
CRC calculation also takes place in a separate goroutine.

You should only use this if you are (de)compressing big amounts of data,
say more than 1MB at the time, otherwise you will not see any benefit,
and it will likely be faster to use the internal gzip library
or this package.

It is important to note that this library creates and reads standard gzip files.
You do not have to match the compressor/decompressor to get the described speedups,
and the gzip files are fully compatible with other gzip readers/writers.

A golang variant of this is bgzf,
which has the same feature, as well as seeking in the resulting file.
The only drawback is a slightly bigger overhead compared to this and pure gzip.
See a comparison below.

Installation

go get github.com/klauspost/pgzip/...

You might need to get/update the dependencies:

go get -u github.com/klauspost/compress

Usage

Godoc Doumentation

To use as a replacement for gzip, exchange

import "compress/gzip"
with
import gzip "github.com/klauspost/pgzip".

Changes

• Oct 6, 2016: Fixed an issue if the destination writer returned an error.
• Oct 6, 2016: Better buffer reuse, should now generate less garbage.
• Oct 6, 2016: Output does not change based on write sizes.
• Dec 8, 2015: Decoder now supports the io.WriterTo interface, giving a speedup and less GC pressure.
• Oct 9, 2015: Reduced allocations by ~35 by using sync.Pool. ~15% overall speedup.

Changes in github.com/klauspost/compress are also carried over, so see that for more changes.

Compression Copy Chapter

The simplest way to use this is to simply do the same as you would when using compress/gzip.

To change the block size, use the added (*pgzip.Writer).SetConcurrency(blockSize, blocks int) function. With this you can control the approximate size of your blocks, as well as how many you want to be processing in parallel. Default values for this is SetConcurrency(1MB, runtime.GOMAXPROCS(0)), meaning blocks are split at 1 MB and up to the number of CPU threads blocks can be processing at once before the writer blocks.

Example:

var b bytes.Buffer
w := gzip.NewWriter(&b)
w.SetConcurrency(100000, 10)
w.Write([]byte("hello, world\n"))
w.Close()

To get any performance gains, you should at least be compressing more than 1 megabyte of data at the time.

You should at least have a block size of 100k and at least a number of blocks that match the number of cores your would like to utilize, but about twice the number of blocks would be the best.

Another side effect of this is, that it is likely to speed up your other code, since writes to the compressor only blocks if the compressor is already compressing the number of blocks you have specified. This also means you don't have worry about buffering input to the compressor.

Decompression Copy Chapter

Decompression works similar to compression. That means that you simply call pgzip the same way as you would call compress/gzip.

The only difference is that if you want to specify your own readahead, you have to use pgzip.NewReaderN(r io.Reader, blockSize, blocks int) to get a reader with your custom blocksizes. The blockSize is the size of each block decoded, and blocks is the maximum number of blocks that is decoded ahead.

See Example on playground

Performance

Compression Copy Chapter

See my blog post in Benchmarks of Golang Gzip.

Compression cost is usually about 0.2% with default settings with a block size of 250k.

Example with GOMAXPROC set to 32 (16 core CPU)

Content is Matt Mahoneys 10GB corpus. Compression level 6.

pgzip also contains a huffman only compression mode, that will allow compression at ~450MB per core per second, largely independent of the content.

See the complete sheet for different content types and compression settings.

Decompression Copy Chapter

The decompression speedup is there because it allows you to do other work while the decompression is taking place.

In the example above, the numbers are as follows on a 4 CPU machine:

But wait, since gzip decompression is inherently singlethreaded (aside from CRC calculation) how can it be more than 100% faster? Because pgzip due to its design also acts as a buffer. When using unbuffered gzip, you are also waiting for io when you are decompressing. If the gzip decoder can keep up, it will always have data ready for your reader, and you will not be waiting for input to the gzip decompressor to complete.

This is pretty much an optimal situation for pgzip, but it reflects most common usecases for CPU intensive gzip usage.

I haven't included bgzf in this comparison, since it only can decompress files created by a compatible encoder, and therefore cannot be considered a generic gzip decompressor. But if you are able to compress your files with a bgzf compatible program, you can expect it to scale beyond 100%.

License

This contains large portions of code from the go repository - see GO_LICENSE for more information. The changes are released under MIT License. See LICENSE for more information.

Overview (`vendor/github.com/mattn/go-runewidth/README.md`) Copy Section

go-runewidth

Provides functions to get fixed width of the character or string.

Usage Copy Chapter

runewidth.StringWidth("つのだ☆HIRO") == 12

Author Copy Chapter

Yasuhiro Matsumoto

License Copy Chapter

under the MIT License: http://mattn.mit-license.org/2013

Overview (`vendor/github.com/mattn/go-sqlite3/README.md`) Copy Section

go-sqlite3

Sponsors Copy Chapter

This project is proudly sponsored by:

Latest stable version is v1.14 or later, not v2.

Description

A sqlite3 driver that conforms to the built-in database/sql interface.

Supported Golang version: See .github/workflows/go.yaml.

This package follows the official Golang Release Policy.

Overview Copy Section

• go-sqlite3
• Description
  • Overview
• Installation
• API Reference
• Connection String
  • DSN Examples
• Features
  • Usage
  • Feature / Extension List
• Compilation
  • Android
• ARM
• Cross Compile
• Compiling
  • Linux
    • Alpine
    • Fedora
    • Ubuntu
  • macOS
  • Windows
  • Errors
• User Authentication
  • Compile
  • Usage
    • Create protected database
    • Password Encoding
      • Available Encoders
    • Restrictions
    • Support
    • User Management
      • SQL
        • Examples
      • *SQLiteConn
    • Attached database
• Extensions
  • Spatialite
• FAQ
• License
• Author

Installation

This package can be installed with the go get command:

go get github.com/mattn/go-sqlite3

go-sqlite3 is cgo package.
If you want to build your app using go-sqlite3, you need gcc.

Important: because this is a CGO enabled package, you are required to set the environment variable CGO_ENABLED=1 and have a gcc compiler present within your path.

API Reference

API documentation can be found here.

Examples can be found under the examples directory.

Connection String

When creating a new SQLite database or connection to an existing one, with the file name additional options can be given.
This is also known as a DSN (Data Source Name) string.

Options are append after the filename of the SQLite database.
The database filename and options are separated by an ? (Question Mark).
Options should be URL-encoded (see url.QueryEscape).

This also applies when using an in-memory database instead of a file.

Options can be given using the following format: KEYWORD=VALUE and multiple options can be combined with the & ampersand.

This library supports DSN options of SQLite itself and provides additional options.

Boolean values can be one of:

• 0 no false off
• 1 yes true on

DSN Examples Copy Chapter

file:test.db?cache=shared&mode=memory

Features

This package allows additional configuration of features available within SQLite3 to be enabled or disabled by golang build constraints also known as build tags.

Click here for more information about build tags / constraints.

Usage Copy Section

If you wish to build this library with additional extensions / features, use the following command:

go build -tags "<FEATURE>"

For available features, see the extension list.
When using multiple build tags, all the different tags should be space delimited.

Example:

go build -tags "icu json1 fts5 secure_delete"

Feature / Extension List Copy Section

Compilation

This package requires the CGO_ENABLED=1 environment variable if not set by default, and the presence of the gcc compiler.

If you need to add additional CFLAGS or LDFLAGS to the build command, and do not want to modify this package, then this can be achieved by using the CGO_CFLAGS and CGO_LDFLAGS environment variables.

Android Copy Chapter

This package can be compiled for android.
Compile with:

go build -tags "android"

For more information see #201

ARM

To compile for ARM use the following environment:

env CC=arm-linux-gnueabihf-gcc CXX=arm-linux-gnueabihf-g++ \
    CGO_ENABLED=1 GOOS=linux GOARCH=arm GOARM=7 \
    go build -v

Additional information:

• #242
• #504

Cross Compile

This library can be cross-compiled.

In some cases you are required to the CC environment variable with the cross compiler.

Cross Compiling from macOS Copy Chapter

The simplest way to cross compile from macOS is to use xgo.

Steps:

• Install musl-cross (brew install FiloSottile/musl-cross/musl-cross).
• Run CC=x86_64-linux-musl-gcc CXX=x86_64-linux-musl-g++ GOARCH=amd64 GOOS=linux CGO_ENABLED=1 go build -ldflags "-linkmode external -extldflags -static".

Please refer to the project's README for further information.

Compiling

Linux Copy Chapter

To compile this package on Linux, you must install the development tools for your linux distribution.

To compile under linux use the build tag linux.

go build -tags "linux"

If you wish to link directly to libsqlite3 then you can use the libsqlite3 build tag.

go build -tags "libsqlite3 linux"

Alpine Copy Section

When building in an alpine container run the following command before building:

apk add --update gcc musl-dev

Fedora Copy Section

sudo yum groupinstall "Development Tools" "Development Libraries"

Ubuntu Copy Section

sudo apt-get install build-essential

macOS Copy Chapter

macOS should have all the tools present to compile this package. If not, install XCode to add all the developers tools.

Required dependency:

brew install sqlite3

For macOS, there is an additional package to install which is required if you wish to build the icu extension.

This additional package can be installed with homebrew:

brew upgrade icu4c

To compile for macOS on x86:

go build -tags "darwin amd64"

To compile for macOS on ARM chips:

go build -tags "darwin arm64"

If you wish to link directly to libsqlite3, use the libsqlite3 build tag:

# x86 
go build -tags "libsqlite3 darwin amd64"
# ARM
go build -tags "libsqlite3 darwin arm64"

Additional information:

• #206
• #404

Windows Copy Chapter

To compile this package on Windows, you must have the gcc compiler installed.

1. Install a Windows gcc toolchain.
2. Add the bin folder to the Windows path, if the installer did not do this by default.
3. Open a terminal for the TDM-GCC toolchain, which can be found in the Windows Start menu.
4. Navigate to your project folder and run the go build ... command for this package.

For example the TDM-GCC Toolchain can be found here.

Errors Copy Chapter

• Compile error: can not be used when making a shared object; recompile with -fPIC

  When receiving a compile time error referencing recompile with -FPIC then you
  are probably using a hardend system.

  You can compile the library on a hardend system with the following command.

  bash Copy

  go build -ldflags '-extldflags=-fno-PIC'

  More details see #120

• Can't build go-sqlite3 on windows 64bit.

  Probably, you are using go 1.0, go1.0 has a problem when it comes to compiling/linking on windows 64bit.
  See: #27

• go get github.com/mattn/go-sqlite3 throws compilation error.

  gcc throws: internal compiler error

  Remove the download repository from your disk and try re-install with:

  bash Copy

  go install github.com/mattn/go-sqlite3

User Authentication

This is deprecated

This package supports the SQLite User Authentication module.

Compile Copy Chapter

To use the User authentication module, the package has to be compiled with the tag sqlite_userauth. See Features.

Usage Copy Chapter

Create protected database Copy Section

To create a database protected by user authentication, provide the following argument to the connection string _auth.
This will enable user authentication within the database. This option however requires two additional arguments:

• _auth_user
• _auth_pass

When _auth is present in the connection string user authentication will be enabled and the provided user will be created
as an admin user. After initial creation, the parameter _auth has no effect anymore and can be omitted from the connection string.

Example connection strings:

Create an user authentication database with user admin and password admin:

file:test.s3db?_auth&_auth_user=admin&_auth_pass=admin

Create an user authentication database with user admin and password admin and use SHA1 for the password encoding:

file:test.s3db?_auth&_auth_user=admin&_auth_pass=admin&_auth_crypt=sha1

Password Encoding Copy Section

The passwords within the user authentication module of SQLite are encoded with the SQLite function sqlite_cryp.
This function uses a ceasar-cypher which is quite insecure.
This library provides several additional password encoders which can be configured through the connection string.

The password cypher can be configured with the key _auth_crypt. And if the configured password encoder also requires an
salt this can be configured with _auth_salt.

Available Encoders

• SHA1
• SSHA1 (Salted SHA1)
• SHA256
• SSHA256 (salted SHA256)
• SHA384
• SSHA384 (salted SHA384)
• SHA512
• SSHA512 (salted SHA512)

Restrictions Copy Section

Operations on the database regarding user management can only be preformed by an administrator user.

Support Copy Section

The user authentication supports two kinds of users:

• administrators
• regular users

User Management Copy Section

User management can be done by directly using the *SQLiteConn or by SQL.

SQL

The following sql functions are available for user management:

These functions will return an integer:

• 0 (SQLITE_OK)
• 23 (SQLITE_AUTH) Failed to perform due to authentication or insufficient privileges

Examples

// Autheticate user
// Create Admin User
SELECT auth_user_add('admin2', 'admin2', 1);

// Change password for user
SELECT auth_user_change('user', 'userpassword', 0);

// Delete user
SELECT user_delete('user');

*SQLiteConn

The following functions are available for User authentication from the *SQLiteConn:

Attached database Copy Section

When using attached databases, SQLite will use the authentication from the main database for the attached database(s).

Extensions

If you want your own extension to be listed here, or you want to add a reference to an extension; please submit an Issue for this.

Spatialite Copy Chapter

Spatialite is available as an extension to SQLite, and can be used in combination with this repository.
For an example, see shaxbee/go-spatialite.

extension-functions.c from SQLite3 Contrib Copy Chapter

extension-functions.c is available as an extension to SQLite, and provides the following functions:

• Math: acos, asin, atan, atn2, atan2, acosh, asinh, atanh, difference, degrees, radians, cos, sin, tan, cot, cosh, sinh, tanh, coth, exp, log, log10, power, sign, sqrt, square, ceil, floor, pi.
• String: replicate, charindex, leftstr, rightstr, ltrim, rtrim, trim, replace, reverse, proper, padl, padr, padc, strfilter.
• Aggregate: stdev, variance, mode, median, lower_quartile, upper_quartile

For an example, see dinedal/go-sqlite3-extension-functions.

FAQ

• Getting insert error while query is opened.

  You can pass some arguments into the connection string, for example, a URI.
  See: #39

• Do you want to cross compile? mingw on Linux or Mac?

  See: #106
  See also: http://www.limitlessfx.com/cross-compile-golang-app-for-windows-from-linux.html

• Want to get time.Time with current locale

  Use _loc=auto in SQLite3 filename schema like file:foo.db?_loc=auto.

• Can I use this in multiple routines concurrently?

  Yes for readonly. But not for writable. See #50, #51, #209, #274.

• Why I'm getting no such table error?

  Why is it racy if I use a sql.Open("sqlite3", ":memory:") database?

  Each connection to ":memory:" opens a brand new in-memory sql database, so if
  the stdlib's sql engine happens to open another connection and you've only
  specified ":memory:", that connection will see a brand new database. A
  workaround is to use "file::memory:?cache=shared" (or "file:foobar?mode=memory&cache=shared"). Every
  connection to this string will point to the same in-memory database.

  Note that if the last database connection in the pool closes, the in-memory database is deleted. Make sure the max idle connection limit is > 0, and the connection lifetime is infinite.

  For more information see:

  • #204
  • #511
  • https://www.sqlite.org/sharedcache.html#shared_cache_and_in_memory_databases
  • https://www.sqlite.org/inmemorydb.html#sharedmemdb

• Reading from database with large amount of goroutines fails on OSX.

  OS X limits OS-wide to not have more than 1000 files open simultaneously by default.

  For more information, see #289

• Trying to execute a . (dot) command throws an error.

  Error: Error: near ".": syntax error
  Dot command are part of SQLite3 CLI, not of this library.

  You need to implement the feature or call the sqlite3 cli.

  More information see #305.

• Error: database is locked

  When you get a database is locked, please use the following options.

  Add to DSN: cache=shared

  Example:

  go Copy

  db, err := sql.Open("sqlite3", "file:locked.sqlite?cache=shared")

  Next, please set the database connections of the SQL package to 1:

  go Copy

  db.SetMaxOpenConns(1)

  For more information, see #209.

Contributors Copy Chapter

Code Contributors Copy Section

This project exists thanks to all the people who [contribute].

Financial Contributors Copy Section

Become a financial contributor and help us sustain our community. [Contribute here].

Individuals

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]

License

MIT: http://mattn.mit-license.org/2018

sqlite3-binding.c, sqlite3-binding.h, sqlite3ext.h

The -binding suffix was added to avoid build failures under gccgo.

In this repository, those files are an amalgamation of code that was copied from SQLite3. The license of that code is the same as the license of SQLite3.

Author

Yasuhiro Matsumoto (a.k.a mattn)

G.J.R. Timmer

Overview (`vendor/github.com/miekg/pkcs11/README.md`) Copy Section

PKCS#11

This is a Go implementation of the PKCS#11 API. It wraps the library closely, but uses Go idiom where
it makes sense. It has been tested with SoftHSM.

SoftHSM Copy Chapter

• Make it use a custom configuration file export SOFTHSM_CONF=$PWD/softhsm.conf

• Then use softhsm to init it

  text Copy

  softhsm --init-token --slot 0 --label test --pin 1234

• Then use libsofthsm2.so as the pkcs11 module:

  go Copy

  p := pkcs11.New("/usr/lib/softhsm/libsofthsm2.so")

Examples Copy Chapter

A skeleton program would look somewhat like this (yes, pkcs#11 is verbose):

p := pkcs11.New("/usr/lib/softhsm/libsofthsm2.so")
err := p.Initialize()
if err != nil {
    panic(err)
}

defer p.Destroy()
defer p.Finalize()

slots, err := p.GetSlotList(true)
if err != nil {
    panic(err)
}

session, err := p.OpenSession(slots[0], pkcs11.CKF_SERIAL_SESSION|pkcs11.CKF_RW_SESSION)
if err != nil {
    panic(err)
}
defer p.CloseSession(session)

err = p.Login(session, pkcs11.CKU_USER, "1234")
if err != nil {
    panic(err)
}
defer p.Logout(session)

p.DigestInit(session, []*pkcs11.Mechanism{pkcs11.NewMechanism(pkcs11.CKM_SHA_1, nil)})
hash, err := p.Digest(session, []byte("this is a string"))
if err != nil {
    panic(err)
}

for _, d := range hash {
        fmt.Printf("%x", d)
}
fmt.Println()

Further examples are included in the tests.

To expose PKCS#11 keys using the crypto.Signer interface,
please see github.com/thalesignite/crypto11.

Overview (`vendor/github.com/modern-go/concurrent/README.md`) Copy Section

concurrent

• concurrent.Map: backport sync.Map for go below 1.9
• concurrent.Executor: goroutine with explicit ownership and cancellable

concurrent.Map

because sync.Map is only available in go 1.9, we can use concurrent.Map to make code portable

m := concurrent.NewMap()
m.Store("hello", "world")
elem, found := m.Load("hello")
// elem will be "world"
// found will be true

concurrent.Executor

executor := concurrent.NewUnboundedExecutor()
executor.Go(func(ctx context.Context) {
    everyMillisecond := time.NewTicker(time.Millisecond)
    for {
        select {
        case <-ctx.Done():
            fmt.Println("goroutine exited")
            return
        case <-everyMillisecond.C:
            // do something
        }
    }
})
time.Sleep(time.Second)
executor.StopAndWaitForever()
fmt.Println("executor stopped")

attach goroutine to executor instance, so that we can

• cancel it by stop the executor with Stop/StopAndWait/StopAndWaitForever
• handle panic by callback: the default behavior will no longer crash your application

Overview (`vendor/github.com/modern-go/reflect2/README.md`) Copy Section

reflect2

reflect api that avoids runtime reflect.Value cost

• reflect get/set interface{}, with type checking
• reflect get/set unsafe.Pointer, without type checking
• reflect2.TypeByName works like Class.forName found in java

json-iterator use this package to save runtime dispatching cost.
This package is designed for low level libraries to optimize reflection performance.
General application should still use reflect standard library.

reflect2.TypeByName

// given package is github.com/your/awesome-package
type MyStruct struct {
	// ...
}

// will return the type
reflect2.TypeByName("awesome-package.MyStruct")
// however, if the type has not been used
// it will be eliminated by compiler, so we can not get it in runtime

reflect2 get/set interface{}

valType := reflect2.TypeOf(1)
i := 1
j := 10
valType.Set(&i, &j)
// i will be 10

to get set type, always use its pointer *type

reflect2 get/set unsafe.Pointer

valType := reflect2.TypeOf(1)
i := 1
j := 10
valType.UnsafeSet(unsafe.Pointer(&i), unsafe.Pointer(&j))
// i will be 10

to get set type, always use its pointer *type

benchmark

Benchmark is not necessary for this package. It does nothing actually.
As it is just a thin wrapper to make go runtime public.
Both reflect2 and reflect call same function
provided by runtime package exposed by go language.

unsafe safety

Instead of casting []byte to sliceHeader in your application using unsafe.
We can use reflect2 instead. This way, if sliceHeader changes in the future,
only reflect2 need to be upgraded.

reflect2 tries its best to keep the implementation same as reflect (by testing).

Overview (`vendor/github.com/opencontainers/go-digest/README.md`) Copy Section

go-digest

Common digest package used across the container ecosystem.

Please see the godoc for more information.

What is a digest?

A digest is just a hash.

The most common use case for a digest is to create a content identifier for use in Content Addressable Storage systems:

id := digest.FromBytes([]byte("my content"))

In the example above, the id can be used to uniquely identify the byte slice "my content".
This allows two disparate applications to agree on a verifiable identifier without having to trust one another.

An identifying digest can be verified, as follows:

if id != digest.FromBytes([]byte("my content")) {
  return errors.New("the content has changed!")
}

A Verifier type can be used to handle cases where an io.Reader makes more sense:

rd := getContent()
verifier := id.Verifier()
io.Copy(verifier, rd)

if !verifier.Verified() {
  return errors.New("the content has changed!")
}

Using Merkle DAGs, this can power a rich, safe, content distribution system.

Usage

While the godoc is considered the best resource, a few important items need to be called out when using this package.

1. Make sure to import the hash implementations into your application or the package will panic.
   You should have something like the following in the main (or other entrypoint) of your application:

   go Copy

   import (
       _ "crypto/sha256"
       _ "crypto/sha512"
   )

   This may seem inconvenient but it allows you replace the hash
   implementations with others, such as https://github.com/stevvooe/resumable.

2. Even though digest.Digest may be assemblable as a string, always verify your input with digest.Parse or use Digest.Validate when accepting untrusted input.
   While there are measures to avoid common problems, this will ensure you have valid digests in the rest of your application.

3. While alternative encodings of hash values (digests) are possible (for example, base64), this package deals exclusively with hex-encoded digests.

Stability

The Go API, at this stage, is considered stable, unless otherwise noted.

As always, before using a package export, read the godoc.

Contributing

This package is considered fairly complete.
It has been in production in thousands (millions?) of deployments and is fairly battle-hardened.
New additions will be met with skepticism.
If you think there is a missing feature, please file a bug clearly describing the problem and the alternatives you tried before submitting a PR.

Code of Conduct Copy Chapter

Participation in the OpenContainers community is governed by OpenContainer's Code of Conduct.

Security Copy Chapter

If you find an issue, please follow the security protocol to report it.

Copyright and license

Copyright © 2019, 2020 OCI Contributors
Copyright © 2016 Docker, Inc.
All rights reserved, except as follows.
Code is released under the Apache 2.0 license.
This README.md file and the CONTRIBUTING.md file are licensed under the Creative Commons Attribution 4.0 International License under the terms and conditions set forth in the file LICENSE.docs.
You may obtain a duplicate copy of the same license, titled CC BY-SA 4.0, at http://creativecommons.org/licenses/by-sa/4.0/.

Overview (`vendor/github.com/pkg/browser/README.md`) Copy Section

browser

import "github.com/pkg/browser"

Package browser provides helpers to open files, readers, and urls in a browser window.

The choice of which browser is started is entirely client dependant.

Variables Copy Chapter

var Stderr io.Writer = os.Stderr

Stderr is the io.Writer to which executed commands write standard error.

var Stdout io.Writer = os.Stdout

Stdout is the io.Writer to which executed commands write standard output.

func OpenFile Copy Chapter

func OpenFile(path string) error

OpenFile opens new browser window for the file path.

func OpenReader Copy Chapter

func OpenReader(r io.Reader) error

OpenReader consumes the contents of r and presents the
results in a new browser window.

func OpenURL Copy Chapter

func OpenURL(url string) error

OpenURL opens a new browser window pointing to url.

Generated by godoc2md

Overview (`vendor/github.com/pkg/errors/README.md`) Copy Section

errors [](https://travis-ci.org/pkg/errors) [](https://ci.appveyor.com/project/davecheney/errors/branch/master) [](http://godoc.org/github.com/pkg/errors) [](https://goreportcard.com/report/github.com/pkg/errors) [](https://sourcegraph.com/github.com/pkg/errors?badge)

Package errors provides simple error handling primitives.

go get github.com/pkg/errors

The traditional error handling idiom in Go is roughly akin to

if err != nil {
        return err
}

which applied recursively up the call stack results in error reports without context or debugging information. The errors package allows programmers to add context to the failure path in their code in a way that does not destroy the original value of the error.

Adding context to an error Copy Chapter

The errors.Wrap function returns a new error that adds context to the original error. For example

_, err := ioutil.ReadAll(r)
if err != nil {
        return errors.Wrap(err, "read failed")
}

Retrieving the cause of an error Copy Chapter

Using errors.Wrap constructs a stack of errors, adding context to the preceding error. Depending on the nature of the error it may be necessary to reverse the operation of errors.Wrap to retrieve the original error for inspection. Any error value which implements this interface can be inspected by errors.Cause.

type causer interface {
        Cause() error
}

errors.Cause will recursively retrieve the topmost error which does not implement causer, which is assumed to be the original cause. For example:

switch err := errors.Cause(err).(type) {
case *MyError:
        // handle specifically
default:
        // unknown error
}

Read the package documentation for more information.

Roadmap Copy Chapter

With the upcoming Go2 error proposals this package is moving into maintenance mode. The roadmap for a 1.0 release is as follows:

• 0.9. Remove pre Go 1.9 and Go 1.10 support, address outstanding pull requests (if possible)
• 1.0. Final release.

Contributing Copy Chapter

Because of the Go2 errors changes, this package is not accepting proposals for new functionality. With that said, we welcome pull requests, bug fixes and issue reports.

Before sending a PR, please discuss your change by raising an issue.

License Copy Chapter

BSD-2-Clause

Overview (`vendor/github.com/proglottis/gpgme/README.md`) Copy Section

GPGME (golang)

Go wrapper for the GPGME library.

This library is intended for use with desktop applications. If you are looking to add OpenPGP support to a server application I suggest you first look at golang.org/x/crypto/openpgp.

Installation Copy Chapter

go get -u github.com/proglottis/gpgme

Documentation Copy Chapter

• godoc

Overview (`vendor/github.com/sirupsen/logrus/README.md`) Copy Section

Logrus [](https://github.com/sirupsen/logrus/actions?query=workflow%3ACI) [](https://pkg.go.dev/github.com/sirupsen/logrus)

Logrus is a structured logger for Go (golang), completely API compatible with
the standard library logger.

Logrus is in maintenance mode. The project focuses on security, bug fixes,
and performance improvements. New features are not planned, aside from changes
required to provide interoperability with other logging ecosystems (e.g., Go's
log/slog).

I believe Logrus' biggest contribution is to have played a part in today's
widespread use of structured logging in Golang. There doesn't seem to be a
reason to do a major, breaking iteration into Logrus V2, since the fantastic Go
community has built those independently. Many fantastic alternatives have sprung
up. Logrus would look like those, had it been re-designed with what we know
about structured logging in Go today. Check out, for example,
Zerolog, Zap, and Apex.

Nicely color-coded in development (when a TTY is attached, otherwise just
plain text):

With logrus.SetFormatter(&logrus.JSONFormatter{}), for easy parsing by logstash
or Splunk:

{"animal":"walrus","level":"info","msg":"A group of walrus emerges from the ocean","size":10,"time":"2014-03-10 19:57:38.562264131 -0400 EDT"}
{"level":"warning","msg":"The group's number increased tremendously!","number":122,"omg":true,"time":"2014-03-10 19:57:38.562471297 -0400 EDT"}
{"animal":"walrus","level":"info","msg":"A giant walrus appears!","size":10,"time":"2014-03-10 19:57:38.562500591 -0400 EDT"}
{"animal":"walrus","level":"info","msg":"Tremendously sized cow enters the ocean.","size":9,"time":"2014-03-10 19:57:38.562527896 -0400 EDT"}
{"level":"fatal","msg":"The ice breaks!","number":100,"omg":true,"time":"2014-03-10 19:57:38.562543128 -0400 EDT"}

With the default logrus.SetFormatter(&logrus.TextFormatter{}) when a TTY is not
attached, the output is compatible with the
logfmt format:

time="2015-03-26T01:27:38-04:00" level=debug msg="Started observing beach" animal=walrus number=8
time="2015-03-26T01:27:38-04:00" level=info msg="A group of walrus emerges from the ocean" animal=walrus size=10
time="2015-03-26T01:27:38-04:00" level=warning msg="The group's number increased tremendously!" number=122 omg=true
time="2015-03-26T01:27:38-04:00" level=debug msg="Temperature changes" temperature=-4
time="2015-03-26T01:27:38-04:00" level=panic msg="It's over 9000!" animal=orca size=9009
time="2015-03-26T01:27:38-04:00" level=fatal msg="The ice breaks!" animal=orca err="It's over 9000!" number=100 omg=true size=9009

To ensure this behaviour even if a TTY is attached, set your formatter as follows:

logrus.SetFormatter(&logrus.TextFormatter{
    DisableColors: true,
    FullTimestamp: true,
})

Logging Method Name

If you wish to add the calling method as a field, instruct the logger via:

logrus.SetReportCaller(true)

This adds the caller as 'method' like so:

{"animal":"penguin","level":"fatal","method":"github.com/sirupsen/arcticcreatures.migrate","msg":"a penguin swims by","time":"2014-03-10 19:57:38.562543129 -0400 EDT"}

time="2015-03-26T01:27:38-04:00" level=fatal method=github.com/sirupsen/arcticcreatures.migrate msg="a penguin swims by" animal=penguin

Note that this does add measurable overhead - the cost will depend on the version of Go, but is
between 20 and 40% in recent tests with 1.6 and 1.7. You can validate this in your
environment via benchmarks:

go test -bench=ReportCaller

Case-sensitivity

The organization's name was changed to lower-case. If you are getting import
conflicts due to case sensitivity, please use the lower-case import:
github.com/sirupsen/logrus.

Example

The simplest way to use Logrus is simply the package-level exported logger:

package main

import "github.com/sirupsen/logrus"

func main() {
  logrus.WithFields(logrus.Fields{
    "animal": "walrus",
  }).Info("A walrus appears")
}

Note that it's completely api-compatible with the stdlib logger, so you can
replace your log imports everywhere with log "github.com/sirupsen/logrus"
and you'll now have the flexibility of Logrus. You can customize it all you
want:

package main

import (
  "os"

  log "github.com/sirupsen/logrus"
)

func init() {
  // Log as JSON instead of the default ASCII formatter.
  log.SetFormatter(&log.JSONFormatter{})

  // Output to stdout instead of the default stderr
  // Can be any io.Writer, see below for File example
  log.SetOutput(os.Stdout)

  // Only log the warning severity or above.
  log.SetLevel(log.WarnLevel)
}

func main() {
  log.WithFields(log.Fields{
    "animal": "walrus",
    "size":   10,
  }).Info("A group of walrus emerges from the ocean")

  log.WithFields(log.Fields{
    "omg":    true,
    "number": 122,
  }).Warn("The group's number increased tremendously!")

  log.WithFields(log.Fields{
    "omg":    true,
    "number": 100,
  }).Fatal("The ice breaks!")

  // A common pattern is to re-use fields between logging statements by re-using
  // the logrus.Entry returned from WithFields()
  contextLogger := log.WithFields(log.Fields{
    "common": "this is a common field",
    "other": "I also should be logged always",
  })

  contextLogger.Info("I'll be logged with common and other field")
  contextLogger.Info("Me too")
}

For more advanced usage such as logging to multiple locations from the same
application, you can also create an instance of the logrus Logger:

package main

import (
  "os"

  "github.com/sirupsen/logrus"
)

// Create a new instance of the logger. You can have any number of instances.
var logger = logrus.New()

func main() {
  // The API for setting attributes is a little different than the package level
  // exported logger. See Godoc. 
  logger.Out = os.Stdout

  // You could set this to any `io.Writer` such as a file
  // file, err := os.OpenFile("logrus.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
  // if err == nil {
  //  logger.Out = file
  // } else {
  //  logger.Info("Failed to log to file, using default stderr")
  // }

  logger.WithFields(logrus.Fields{
    "animal": "walrus",
    "size":   10,
  }).Info("A group of walrus emerges from the ocean")
}

Fields

Logrus encourages careful, structured logging through logging fields instead of
long, unparseable error messages. For example, instead of: logrus.Fatalf("Failed to send event %s to topic %s with key %d"), you should log the much more
discoverable:

logrus.WithFields(logrus.Fields{
  "event": event,
  "topic": topic,
  "key": key,
}).Fatal("Failed to send event")

We've found this API forces you to think about logging in a way that produces
much more useful logging messages. We've been in countless situations where just
a single added field to a log statement that was already there would've saved us
hours. The WithFields call is optional.

In general, with Logrus using any of the printf-family functions should be
seen as a hint you should add a field, however, you can still use the
printf-family functions with Logrus.

Default Fields

Often it's helpful to have fields always attached to log statements in an
application or parts of one. For example, you may want to always log the
request_id and user_ip in the context of a request. Instead of writing
logger.WithFields(logrus.Fields{"request_id": request_id, "user_ip": user_ip}) on
every line, you can create a logrus.Entry to pass around instead:

requestLogger := logger.WithFields(logrus.Fields{"request_id": request_id, "user_ip": user_ip})
requestLogger.Info("something happened on that request") // will log request_id and user_ip
requestLogger.Warn("something not great happened")

Hooks

You can add hooks for logging levels. For example to send errors to an exception
tracking service on Error, Fatal and Panic, info to StatsD or log to
multiple places simultaneously, e.g. syslog.

Logrus comes with built-in hooks. Add those, or your custom hook, in
init:

package main

import (
  "log/syslog"

  "github.com/sirupsen/logrus"
  airbrake "gopkg.in/gemnasium/logrus-airbrake-hook.v2"
  logrus_syslog "github.com/sirupsen/logrus/hooks/syslog"
)

func init() {

  // Use the Airbrake hook to report errors that have Error severity or above to
  // an exception tracker. You can create custom hooks, see the Hooks section.
  logrus.AddHook(airbrake.NewHook(123, "xyz", "production"))

  hook, err := logrus_syslog.NewSyslogHook("udp", "localhost:514", syslog.LOG_INFO, "")
  if err != nil {
    logrus.Error("Unable to connect to local syslog daemon")
  } else {
    logrus.AddHook(hook)
  }
}

Note: Syslog hooks also support connecting to local syslog (Ex. "/dev/log" or "/var/run/syslog" or "/var/run/log"). For the detail, please check the syslog hook README.

A list of currently known service hooks can be found in this wiki page

Level logging

Logrus has seven logging levels: Trace, Debug, Info, Warning, Error, Fatal and Panic.

logrus.Trace("Something very low level.")
logrus.Debug("Useful debugging information.")
logrus.Info("Something noteworthy happened!")
logrus.Warn("You should probably take a look at this.")
logrus.Error("Something failed but I'm not quitting.")
// Calls os.Exit(1) after logging
logrus.Fatal("Bye.")
// Calls panic() after logging
logrus.Panic("I'm bailing.")

You can set the logging level on a Logger, then it will only log entries with
that severity or anything above it:

// Will log anything that is info or above (warn, error, fatal, panic). Default.
logrus.SetLevel(logrus.InfoLevel)

It may be useful to set logrus.Level = logrus.DebugLevel in a debug or verbose
environment if your application has that.

Note: If you want different log levels for global (logrus.SetLevel(...)) and syslog logging, please check the syslog hook README.

Entries

Besides the fields added with WithField or WithFields some fields are
automatically added to all logging events:

1. time. The timestamp when the entry was created.
2. msg. The logging message passed to {Info,Warn,Error,Fatal,Panic} after
   the AddFields call. E.g. Failed to send event.
3. level. The logging level. E.g. info.

Environments

Logrus has no notion of environment.

If you wish for hooks and formatters to only be used in specific environments,
you should handle that yourself. For example, if your application has a global
variable Environment, which is a string representation of the environment you
could do:

import (
  "github.com/sirupsen/logrus"
)

func init() {
  // do something here to set environment depending on an environment variable
  // or command-line flag
  if Environment == "production" {
    logrus.SetFormatter(&logrus.JSONFormatter{})
  } else {
    // The TextFormatter is default, you don't actually have to do this.
    logrus.SetFormatter(&logrus.TextFormatter{})
  }
}

This configuration is how logrus was intended to be used, but JSON in
production is mostly only useful if you do log aggregation with tools like
Splunk or Logstash.

Formatters

The built-in logging formatters are:

• logrus.TextFormatter
  logs the event in colors if the logger output is a TTY, otherwise without colors.
  • To force colored output when there is no TTY, set the ForceColors
    field to true. To force no colored output even if there is a TTY set the
    DisableColors field to true.
  • On modern Windows terminals with ANSI (Virtual Terminal) support, TextFormatter
    automatically enables colored output.
  • If your environment does not support ANSI escape sequences, wrap the logger output
    using github.com/mattn/go-colorable
    and set ForceColors (or CLICOLOR_FORCE=1) to enable colors through the wrapper.
  • When colors are enabled, levels are truncated to 4 characters by default. To disable
    truncation set the DisableLevelTruncation field to true.
  • When outputting to a TTY, it's often helpful to visually scan down a column where all the levels are the same width. Setting the PadLevelText field to true enables this behavior, by adding padding to the level text.
• logrus.JSONFormatter
  logs fields as JSON.

Third-party logging formatters:

• FluentdFormatter. Formats entries that can be parsed by Kubernetes and Google Container Engine.
• GELF. Formats entries so they comply to Graylog's GELF 1.1 specification.
• logstash. Logs fields as Logstash Events.
• prefixed. Displays log entry source along with alternative layout.
• zalgo. Invoking the Power of Zalgo.
• nested-logrus-formatter. Converts logrus fields to a nested structure.
• powerful-logrus-formatter. get fileName, log's line number and the latest function's name when print log; Save log to files.
• caption-json-formatter. logrus's message json formatter with human-readable caption added.
• easy-logrus-formatter. Provide a user-friendly formatter for logrus.
• redactrus. Redacts sensitive information like password, apikeys, email, etc. from logs.

You can define your formatter by implementing the Formatter interface,
requiring a Format method. Format takes an *Entry. entry.Data is a
Fields type (map[string]any) with all your fields as well as the
default ones (see Entries section above):

type MyJSONFormatter struct{}

logrus.SetFormatter(new(MyJSONFormatter))

func (f *MyJSONFormatter) Format(entry *Entry) ([]byte, error) {
  // Note this doesn't include Time, Level and Message which are available on
  // the Entry. Consult `godoc` on information about those fields or read the
  // source of the official loggers.
  serialized, err := json.Marshal(entry.Data)
    if err != nil {
      return nil, fmt.Errorf("Failed to marshal fields to JSON, %w", err)
    }
  return append(serialized, '\n'), nil
}

Logger as an `io.Writer`

Logrus can be transformed into an io.Writer. That writer is the end of an io.Pipe and it is your responsibility to close it.

w := logger.Writer()
defer w.Close()

srv := http.Server{
    // create a stdlib log.Logger that writes to
    // logrus.Logger.
    ErrorLog: log.New(w, "", 0),
}

Each line written to that writer will be printed the usual way, using formatters
and hooks. The level for those entries is info.

This means that we can override the standard library logger easily:

logger := logrus.New()
logger.Formatter = &logrus.JSONFormatter{}

// Use logrus for standard log output
// Note that `log` here references stdlib's log
// Not logrus imported under the name `log`.
log.SetOutput(logger.Writer())

Rotation

Log rotation is not provided with Logrus. Log rotation should be done by an
external program (like logrotate(8)) that can compress and delete old log
entries. It should not be a feature of the application-level logger.

Tools

Testing

Logrus has a built-in facility for asserting the presence of log messages. This is implemented through the test hook and provides:

• decorators for existing logger (test.NewLocal and test.NewGlobal) which basically just adds the test hook
• a test logger (test.NewNullLogger) that just records log messages (and does not output any):

import(
  "testing"

  "github.com/sirupsen/logrus"
  "github.com/sirupsen/logrus/hooks/test"
  "github.com/stretchr/testify/assert"
)

func TestSomething(t*testing.T){
  logger, hook := test.NewNullLogger()
  logger.Error("Helloerror")

  assert.Equal(t, 1, len(hook.Entries))
  assert.Equal(t, logrus.ErrorLevel, hook.LastEntry().Level)
  assert.Equal(t, "Helloerror", hook.LastEntry().Message)

  hook.Reset()
  assert.Nil(t, hook.LastEntry())
}

Fatal handlers

Logrus can register one or more functions that will be called when any fatal
level message is logged. The registered handlers will be executed before
logrus performs an os.Exit(1). This behavior may be helpful if callers need
to gracefully shut down. Unlike a panic("Something went wrong...") call which can be intercepted with a deferred recover a call to os.Exit(1) can not be intercepted.

// ...
handler := func() {
  // gracefully shut down something...
}
logrus.RegisterExitHandler(handler)
// ...

Thread safety

By default, Logger is protected by a mutex for concurrent writes. The mutex is held when calling hooks and writing logs.
If you are sure such locking is not needed, you can call logger.SetNoLock() to disable the locking.

Situations when locking is not needed include:

• You have no hooks registered, or hooks calling is already thread-safe.

• Writing to logger.Out is already thread-safe, for example:

  1. logger.Out is protected by locks.

  2. logger.Out is an os.File handler opened with O_APPEND flag, and every write is smaller than 4k. (This allows multi-thread/multi-process writing)

     (Refer to http://www.notthewizard.com/2014/06/17/are-files-appends-really-atomic/)

Overview (`vendor/github.com/smallstep/pkcs7/README.md`) Copy Section

pkcs7

pkcs7 implements parsing and creating signed and enveloped messages.

package main

import (
	"bytes"
	"crypto/rsa"
	"crypto/x509"
	"encoding/pem"
	"fmt"
	"os"

    "github.com/smallstep/pkcs7"
)

func SignAndDetach(content []byte, cert *x509.Certificate, privkey *rsa.PrivateKey) (signed []byte, err error) {
	toBeSigned, err := NewSignedData(content)
	if err != nil {
		return fmt.Errorf("Cannot initialize signed data: %w", err)
	}
	if err = toBeSigned.AddSigner(cert, privkey, SignerInfoConfig{}); err != nil {
		return fmt.Errorf("Cannot add signer: %w", err)
	}

	// Detach signature, omit if you want an embedded signature
	toBeSigned.Detach()

	signed, err = toBeSigned.Finish()
	if err != nil {
		return fmt.Errorf("Cannot finish signing data: %w", err)
	}

	// Verify the signature
	pem.Encode(os.Stdout, &pem.Block{Type: "PKCS7", Bytes: signed})
	p7, err := pkcs7.Parse(signed)
	if err != nil {
		return fmt.Errorf("Cannot parse our signed data: %w", err)
	}

	// since the signature was detached, reattach the content here
	p7.Content = content

	if bytes.Compare(content, p7.Content) != 0 {
		return fmt.Errorf("Our content was not in the parsed data:\n\tExpected: %s\n\tActual: %s", content, p7.Content)
	}
	if err = p7.Verify(); err != nil {
		return fmt.Errorf("Cannot verify our signed data: %w", err)
	}

	return signed, nil
}

Credits Copy Chapter

This is a fork of mozilla-services/pkcs7 which, itself, was a fork of fullsailor/pkcs7.

Overview (`vendor/github.com/spf13/cobra/README.md`) Copy Section

Cobra is a library for creating powerful modern CLI applications.

Visit Cobra.dev for extensive documentation

Cobra is used in many Go projects such as Kubernetes,
Hugo, and GitHub CLI to
name a few. This list contains a more extensive list of projects using Cobra.

Overview

Cobra is a library providing a simple interface to create powerful modern CLI
interfaces similar to git & go tools.

Cobra provides:

• Easy subcommand-based CLIs: app server, app fetch, etc.
• Fully POSIX-compliant flags (including short & long versions)
• Nested subcommands
• Global, local and cascading flags
• Intelligent suggestions (app srver... did you mean app server?)
• Automatic help generation for commands and flags
• Grouping help for subcommands
• Automatic help flag recognition of -h, --help, etc.
• Automatically generated shell autocomplete for your application (bash, zsh, fish, powershell)
• Automatically generated man pages for your application
• Command aliases so you can change things without breaking them
• The flexibility to define your own help, usage, etc.
• Optional seamless integration with viper for 12-factor apps

Concepts

Cobra is built on a structure of commands, arguments & flags.

Commands represent actions, Args are things and Flags are modifiers for those actions.

The best applications read like sentences when used, and as a result, users
intuitively know how to interact with them.

The pattern to follow is
APPNAME VERB NOUN --ADJECTIVE
or
APPNAME COMMAND ARG --FLAG.

A few good real world examples may better illustrate this point.

In the following example, 'server' is a command, and 'port' is a flag:

hugo server --port=1313

In this command we are telling Git to clone the url bare.

git clone URL --bare

Commands Copy Chapter

Command is the central point of the application. Each interaction that
the application supports will be contained in a Command. A command can
have children commands and optionally run an action.

In the example above, 'server' is the command.

More about cobra.Command

Flags Copy Chapter

A flag is a way to modify the behavior of a command. Cobra supports
fully POSIX-compliant flags as well as the Go flag package.
A Cobra command can define flags that persist through to children commands
and flags that are only available to that command.

In the example above, 'port' is the flag.

Flag functionality is provided by the pflag
library, a fork of the flag standard library
which maintains the same interface while adding POSIX compliance.

Installing

Using Cobra is easy. First, use go get to install the latest version
of the library.

go get -u github.com/spf13/cobra@latest

Next, include Cobra in your application:

import "github.com/spf13/cobra"

Usage

cobra-cli is a command line program to generate cobra applications and command files.
It will bootstrap your application scaffolding to rapidly
develop a Cobra-based application. It is the easiest way to incorporate Cobra into your application.

It can be installed by running:

go install github.com/spf13/cobra-cli@latest

For complete details on using the Cobra-CLI generator, please read The Cobra Generator README

For complete details on using the Cobra library, please read The Cobra User Guide.

License

Cobra is released under the Apache 2.0 license. See LICENSE.txt

Overview (`vendor/github.com/spf13/pflag/README.md`) Copy Section

Description Copy Chapter

pflag is a drop-in replacement for Go's flag package, implementing
POSIX/GNU-style --flags.

pflag is compatible with the GNU extensions to the POSIX recommendations
for command-line options. For a more precise description, see the
"Command-line flag syntax" section below.

pflag is available under the same style of BSD license as the Go language,
which can be found in the LICENSE file.

Installation Copy Chapter

pflag is available using the standard go get command.

Install by running:

go get github.com/spf13/pflag

Run tests by running:

go test github.com/spf13/pflag

Usage Copy Chapter

pflag is a drop-in replacement of Go's native flag package. If you import
pflag under the name "flag" then all code should continue to function
with no changes.

import flag "github.com/spf13/pflag"

There is one exception to this: if you directly instantiate the Flag struct
there is one more field "Shorthand" that you will need to set.
Most code never instantiates this struct directly, and instead uses
functions such as String(), BoolVar(), and Var(), and is therefore
unaffected.

Define flags using flag.String(), Bool(), Int(), etc.

This declares an integer flag, -flagname, stored in the pointer ip, with type *int.

var ip *int = flag.Int("flagname", 1234, "help message for flagname")

If you like, you can bind the flag to a variable using the Var() functions.

var flagvar int
func init() {
    flag.IntVar(&flagvar, "flagname", 1234, "help message for flagname")
}

Or you can create custom flags that satisfy the Value interface (with
pointer receivers) and couple them to flag parsing by

flag.Var(&flagVal, "name", "help message for flagname")

For such flags, the default value is just the initial value of the variable.

After all flags are defined, call

flag.Parse()

to parse the command line into the defined flags.

Flags may then be used directly. If you're using the flags themselves,
they are all pointers; if you bind to variables, they're values.

fmt.Println("ip has value ", *ip)
fmt.Println("flagvar has value ", flagvar)

There are helper functions available to get the value stored in a Flag if you have a FlagSet but find
it difficult to keep up with all of the pointers in your code.
If you have a pflag.FlagSet with a flag called 'flagname' of type int you
can use GetInt() to get the int value. But notice that 'flagname' must exist
and it must be an int. GetString("flagname") will fail.

i, err := flagset.GetInt("flagname")

After parsing, the arguments after the flag are available as the
slice flag.Args() or individually as flag.Arg(i).
The arguments are indexed from 0 through flag.NArg()-1.

The pflag package also defines some new functions that are not in flag,
that give one-letter shorthands for flags. You can use these by appending
'P' to the name of any function that defines a flag.

var ip = flag.IntP("flagname", "f", 1234, "help message")
var flagvar bool
func init() {
	flag.BoolVarP(&flagvar, "boolname", "b", true, "help message")
}
flag.VarP(&flagVal, "varname", "v", "help message")

Shorthand letters can be used with single dashes on the command line.
Boolean shorthand flags can be combined with other shorthand flags.

The default set of command-line flags is controlled by
top-level functions. The FlagSet type allows one to define
independent sets of flags, such as to implement subcommands
in a command-line interface. The methods of FlagSet are
analogous to the top-level functions for the command-line
flag set.

Setting no option default values for flags Copy Chapter

After you create a flag it is possible to set the pflag.NoOptDefVal for
the given flag. Doing this changes the meaning of the flag slightly. If
a flag has a NoOptDefVal and the flag is set on the command line without
an option the flag will be set to the NoOptDefVal. For example given:

var ip = flag.IntP("flagname", "f", 1234, "help message")
flag.Lookup("flagname").NoOptDefVal = "4321"

Would result in something like

Command line flag syntax Copy Chapter

--flag    // boolean flags, or flags with no option default values
--flag x  // only on flags without a default value
--flag=x

Unlike the flag package, a single dash before an option means something
different than a double dash. Single dashes signify a series of shorthand
letters for flags. All but the last shorthand letter must be boolean flags
or a flag with a default value

// boolean or flags where the 'no option default value' is set
-f
-f=true
-abc
but
-b true is INVALID

// non-boolean and flags without a 'no option default value'
-n 1234
-n=1234
-n1234

// mixed
-abcs "hello"
-absd="hello"
-abcs1234

Flag parsing stops after the terminator "--". Unlike the flag package,
flags can be interspersed with arguments anywhere on the command line
before this terminator.

Integer flags accept 1234, 0664, 0x1234 and may be negative.
Boolean flags (in their long form) accept 1, 0, t, f, true, false,
TRUE, FALSE, True, False.
Duration flags accept any input valid for time.ParseDuration.

Mutating or "Normalizing" Flag names Copy Chapter

It is possible to set a custom flag name 'normalization function.' It allows flag names to be mutated both when created in the code and when used on the command line to some 'normalized' form. The 'normalized' form is used for comparison. Two examples of using the custom normalization func follow.

Example #1: You want -, _, and . in flags to compare the same. aka --my-flag == --my_flag == --my.flag

func wordSepNormalizeFunc(f *pflag.FlagSet, name string) pflag.NormalizedName {
	from := []string{"-", "_"}
	to := "."
	for _, sep := range from {
		name = strings.Replace(name, sep, to, -1)
	}
	return pflag.NormalizedName(name)
}

myFlagSet.SetNormalizeFunc(wordSepNormalizeFunc)

Example #2: You want to alias two flags. aka --old-flag-name == --new-flag-name

func aliasNormalizeFunc(f *pflag.FlagSet, name string) pflag.NormalizedName {
	switch name {
	case "old-flag-name":
		name = "new-flag-name"
		break
	}
	return pflag.NormalizedName(name)
}

myFlagSet.SetNormalizeFunc(aliasNormalizeFunc)

Deprecating a flag or its shorthand Copy Chapter

It is possible to deprecate a flag, or just its shorthand. Deprecating a flag/shorthand hides it from help text and prints a usage message when the deprecated flag/shorthand is used.

Example #1: You want to deprecate a flag named "badflag" as well as inform the users what flag they should use instead.

// deprecate a flag by specifying its name and a usage message
flags.MarkDeprecated("badflag", "please use --good-flag instead")

This hides "badflag" from help text, and prints Flag --badflag has been deprecated, please use --good-flag instead when "badflag" is used.

Example #2: You want to keep a flag name "noshorthandflag" but deprecate its shortname "n".

// deprecate a flag shorthand by specifying its flag name and a usage message
flags.MarkShorthandDeprecated("noshorthandflag", "please use --noshorthandflag only")

This hides the shortname "n" from help text, and prints Flag shorthand -n has been deprecated, please use --noshorthandflag only when the shorthand "n" is used.

Note that usage message is essential here, and it should not be empty.

Hidden flags Copy Chapter

It is possible to mark a flag as hidden, meaning it will still function as normal, however will not show up in usage/help text.

Example: You have a flag named "secretFlag" that you need for internal use only and don't want it showing up in help text, or for its usage text to be available.

// hide a flag by specifying its name
flags.MarkHidden("secretFlag")

Disable sorting of flags Copy Chapter

pflag allows you to disable sorting of flags for help and usage message.

Example:

flags.BoolP("verbose", "v", false, "verbose output")
flags.String("coolflag", "yeaah", "it's really cool flag")
flags.Int("usefulflag", 777, "sometimes it's very useful")
flags.SortFlags = false
flags.PrintDefaults()

Output:

-v, --verbose           verbose output
      --coolflag string   it's really cool flag (default "yeaah")
      --usefulflag int    sometimes it's very useful (default 777)

Supporting Go flags when using pflag Copy Chapter

In order to support flags defined using Go's flag package, they must be added to the pflag flagset. This is usually necessary
to support flags defined by third-party dependencies (e.g. golang/glog).

Example: You want to add the Go flags to the CommandLine flagset

import (
	goflag "flag"
	flag "github.com/spf13/pflag"
)

var ip *int = flag.Int("flagname", 1234, "help message for flagname")

func main() {
	flag.CommandLine.AddGoFlagSet(goflag.CommandLine)
	flag.Parse()
}

Using pflag with go test Copy Section

pflag does not parse the shorthand versions of go test's built-in flags (i.e., those starting with -test.).
For more context, see issues #63 and #238 for more details.

For example, if you use pflag in your TestMain function and call pflag.Parse() after defining your custom flags, running a test like this:

go test /your/tests -run ^YourTest -v --your-test-pflags

will result in the -v flag being ignored. This happens because of the way pflag handles flag parsing, skipping over go test's built-in shorthand flags.
To work around this, you can use the ParseSkippedFlags function, which ensures that go test's flags are parsed separately using the standard flag package.

Example: You want to parse go test flags that are otherwise ignore by pflag.Parse()

import (
	goflag "flag"
	flag "github.com/spf13/pflag"
)

var ip *int = flag.Int("flagname", 1234, "help message for flagname")

func main() {
	flag.CommandLine.AddGoFlagSet(goflag.CommandLine)
    flag.ParseSkippedFlags(os.Args[1:], goflag.CommandLine)
	flag.Parse()
}

More info Copy Chapter

You can see the full reference documentation of the pflag package
at godoc.org, or through go's standard documentation system by
running godoc -http=:6060 and browsing to
http://localhost:6060/pkg/github.com/spf13/pflag after
installation.

Overview (`vendor/github.com/stefanberger/go-pkcs11uri/README.md`) Copy Section

go-pkcs11uri

Welcome to the go-pkcs11uri library. The implementation follows RFC 7512 and this errata.

Exampe usage:

The following example builds on this library here and are using softhsm2 on Fedora.

Example Copy Chapter

This example program extending the one found here:

package main

import (
	"fmt"
	"os"
	"strconv"

	"github.com/miekg/pkcs11"
	pkcs11uri "github.com/stefanberger/go-pkcs11uri"
)

func main() {
	if len(os.Args) < 2 {
		panic("Missing pkcs11 URI argument")
	}
	uristr := os.Args[1]

	uri, err := pkcs11uri.New()
	if err != nil {
		panic(err)
	}
	err = uri.Parse(uristr)
	if err != nil {
		panic(err)
	}

	module, err := uri.GetModule()
	if err != nil {
		panic(err)
	}

	slot, ok := uri.GetPathAttribute("slot-id", false)
	if !ok {
		panic("No slot-id in pkcs11 URI")
	}
	slotid, err := strconv.Atoi(slot)
	if err != nil {
		panic(err)
	}

	pin, err := uri.GetPIN()
	if err != nil {
		panic(err)
	}

	p := pkcs11.New(module)
	err = p.Initialize()
	if err != nil {
		panic(err)
	}

	defer p.Destroy()
	defer p.Finalize()

	session, err := p.OpenSession(uint(slotid), pkcs11.CKF_SERIAL_SESSION|pkcs11.CKF_RW_SESSION)
	if err != nil {
		panic(err)
	}
	defer p.CloseSession(session)

	err = p.Login(session, pkcs11.CKU_USER, pin)
	if err != nil {
		panic(err)
	}
	defer p.Logout(session)

	p.DigestInit(session, []*pkcs11.Mechanism{pkcs11.NewMechanism(pkcs11.CKM_SHA_1, nil)})
	hash, err := p.Digest(session, []byte("this is a string"))
	if err != nil {
		panic(err)
	}

	for _, d := range hash {
		fmt.Printf("%x", d)
	}
	fmt.Println()
}

Exampe Usage Copy Chapter

$ sudo softhsm2-util --init-token --slot 1 --label test --pin 1234 --so-pin 1234
The token has been initialized and is reassigned to slot 2053753261
$ go build ./...
$ sudo ./pkcs11-example 'pkcs11:slot-id=2053753261?module-path=/usr/lib64/pkcs11/libsofthsm2.so&pin-value=1234'
517592df8fec3ad146a79a9af153db2a4d784ec5

Overview (`vendor/github.com/ulikunitz/xz/README.md`) Copy Section

Package xz

This Go language package supports the reading and writing of xz
compressed streams. It includes also a gxz command for compressing and
decompressing data. The package is completely written in Go and doesn't
have any dependency on any C code.

The package is currently under development. There might be bugs and APIs
are not considered stable. At this time the package cannot compete with
the xz tool regarding compression speed and size. The algorithms there
have been developed over a long time and are highly optimized. However
there are a number of improvements planned and I'm very optimistic about
parallel compression and decompression. Stay tuned!

Using the API Copy Chapter

The following example program shows how to use the API.

package main

import (
    "bytes"
    "io"
    "log"
    "os"

    "github.com/ulikunitz/xz"
)

func main() {
    const text = "The quick brown fox jumps over the lazy dog.\n"
    var buf bytes.Buffer
    // compress text
    w, err := xz.NewWriter(&buf)
    if err != nil {
        log.Fatalf("xz.NewWriter error %s", err)
    }
    if _, err := io.WriteString(w, text); err != nil {
        log.Fatalf("WriteString error %s", err)
    }
    if err := w.Close(); err != nil {
        log.Fatalf("w.Close error %s", err)
    }
    // decompress buffer and write output to stdout
    r, err := xz.NewReader(&buf)
    if err != nil {
        log.Fatalf("NewReader error %s", err)
    }
    if _, err = io.Copy(os.Stdout, r); err != nil {
        log.Fatalf("io.Copy error %s", err)
    }
}

Documentation Copy Chapter

You can find the full documentation at pkg.go.dev.

Using the gxz compression tool Copy Chapter

The package includes a gxz command line utility for compression and
decompression.

Use following command for installation:

$ go get github.com/ulikunitz/xz/cmd/gxz

To test it call the following command.

$ gxz bigfile

After some time a much smaller file bigfile.xz will replace bigfile.
To decompress it use the following command.

$ gxz -d bigfile.xz

Security & Vulnerabilities Copy Chapter

The security policy is documented in SECURITY.md.

The software is not affected by the supply chain attack on the original xz
implementation, CVE-2024-3094.
This implementation doesn't share any files with the original xz implementation
and no patches or pull requests are accepted without a review.

All security advisories for this project are published under
github.com/ulikunitz/xz/security/advisories.

Overview (`vendor/github.com/vbauerster/cupwriter/README.md`) Copy Section

cupwriter

cupwriter is a cross platform buffered io.Writer which abstracts writing multi lines to a fixed position within a terminal.
It's used by mpb under the hood which means it's quite battle tested in spite of v0.0.x.

Overview (`vendor/github.com/youmark/pkcs8/README.md`) Copy Section

pkcs8

OpenSSL can generate private keys in both "traditional format" and PKCS#8 format. Newer applications are advised to use more secure PKCS#8 format. Go standard crypto package provides a function to parse private key in PKCS#8 format. There is a limitation to this function. It can only handle unencrypted PKCS#8 private keys. To use this function, the user has to save the private key in file without encryption, which is a bad practice to leave private keys unprotected on file systems. In addition, Go standard package lacks the functions to convert RSA/ECDSA private keys into PKCS#8 format.

pkcs8 package fills the gap here. It implements functions to process private keys in PKCS#8 format, as defined in RFC5208 and RFC5958. It can handle both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo format with PKCS#5 (v2.0) algorithms.

Godoc

Installation Copy Chapter

Supports Go 1.10+. Release v1.1 is the last release supporting Go 1.9

go get github.com/youmark/pkcs8

dependency Copy Chapter

This package depends on golang.org/x/crypto/pbkdf2 and golang.org/x/crypto/scrypt packages. Use the following command to retrieve them

go get golang.org/x/crypto/pbkdf2
go get golang.org/x/crypto/scrypt

Overview (`vendor/go.opentelemetry.io/otel/attribute/README.md`) Copy Section

Attribute

Overview (`vendor/go.opentelemetry.io/otel/baggage/README.md`) Copy Section

Baggage

Overview (`vendor/go.opentelemetry.io/otel/codes/README.md`) Copy Section

Codes

Overview (`vendor/go.opentelemetry.io/otel/metric/README.md`) Copy Section

Metric API

Overview (`vendor/go.opentelemetry.io/otel/propagation/README.md`) Copy Section

Propagation

Overview (`vendor/go.opentelemetry.io/otel/trace/README.md`) Copy Section

Trace API

Overview (`vendor/go.yaml.in/yaml/v3/README.md`) Copy Section

go.yaml.in/yaml

YAML Support for the Go Language

Introduction Copy Chapter

The yaml package enables Go programs to comfortably encode
and decode YAML values.

It was originally developed within Canonical as
part of the juju project, and is based on a pure Go
port of the well-known libyaml C library to
parse and generate YAML data quickly and reliably.

Project Status Copy Chapter

This project started as a fork of the extremely popular go-yaml
project, and is being maintained by the official YAML organization.

The YAML team took over ongoing maintenance and development of the project after
discussion with go-yaml's author, @niemeyer, following his decision to
label the project repository as "unmaintained" in April 2025.

We have put together a team of dedicated maintainers including representatives
of go-yaml's most important downstream projects.

We will strive to earn the trust of the various go-yaml forks to switch back to
this repository as their upstream.

Please contact us if you
would like to contribute or be involved.

Compatibility Copy Chapter

The yaml package supports most of YAML 1.2, but preserves some behavior from
1.1 for backwards compatibility.

Specifically, v3 of the yaml package:

• Supports YAML 1.1 bools (yes/no, on/off) as long as they are being
  decoded into a typed bool value.
  Otherwise they behave as a string.
  Booleans in YAML 1.2 are true/false only.
• Supports octals encoded and decoded as 0777 per YAML 1.1, rather than
  0o777 as specified in YAML 1.2, because most parsers still use the old
  format.
  Octals in the 0o777 format are supported though, so new files work.
• Does not support base-60 floats.
  These are gone from YAML 1.2, and were actually never supported by this
  package as it's clearly a poor choice.

Installation and Usage Copy Chapter

The import path for the package is go.yaml.in/yaml/v3.

To install it, run:

go get go.yaml.in/yaml/v3

API Documentation Copy Chapter

See: https://pkg.go.dev/go.yaml.in/yaml/v3

API Stability Copy Chapter

The package API for yaml v3 will remain stable as described in gopkg.in.

Example Copy Chapter

package main

import (
	"fmt"
	"log"

	"go.yaml.in/yaml/v3"
)

var data = `
a: Easy!
b:
  c: 2
  d: [3, 4]
`

// Note: struct fields must be public in order for unmarshal to
// correctly populate the data.
type T struct {
	A string
	B struct {
		RenamedC int   `yaml:"c"`
		D	[]int `yaml:",flow"`
	}
}

func main() {
	t := T{}

	err := yaml.Unmarshal([]byte(data), &t)
	if err != nil {
		log.Fatalf("error: %v", err)
	}
	fmt.Printf("--- t:\n%v\n\n", t)

	d, err := yaml.Marshal(&t)
	if err != nil {
		log.Fatalf("error: %v", err)
	}
	fmt.Printf("--- t dump:\n%s\n\n", string(d))

	m := make(map[interface{}]interface{})

	err = yaml.Unmarshal([]byte(data), &m)
	if err != nil {
		log.Fatalf("error: %v", err)
	}
	fmt.Printf("--- m:\n%v\n\n", m)

	d, err = yaml.Marshal(&m)
	if err != nil {
		log.Fatalf("error: %v", err)
	}
	fmt.Printf("--- m dump:\n%s\n\n", string(d))
}

This example will generate the following output:

--- t:
{Easy! {2 [3 4]}}

--- t dump:
a: Easy!
b:
  c: 2
  d: [3, 4]


--- m:
map[a:Easy! b:map[c:2 d:[3 4]]]

--- m dump:
a: Easy!
b:
  c: 2
  d:
  - 3
  - 4

License Copy Chapter

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

Overview (`vendor/golang.org/x/oauth2/README.md`) Copy Section

OAuth2 for Go

oauth2 package contains a client implementation for OAuth 2.0 spec.

See pkg.go.dev for further documentation and examples.

• pkg.go.dev/golang.org/x/oauth2
• pkg.go.dev/golang.org/x/oauth2/google

Policy for new endpoints Copy Chapter

We no longer accept new provider-specific packages in this repo if all
they do is add a single endpoint variable. If you just want to add a
single endpoint, add it to the
pkg.go.dev/golang.org/x/oauth2/endpoints
package.

Report Issues / Send Patches Copy Chapter

The main issue tracker for the oauth2 repository is located at
https://github.com/golang/oauth2/issues.

This repository uses Gerrit for code changes. To learn how to submit changes to
this repository, see https://go.dev/doc/contribute.

The git repository is https://go.googlesource.com/oauth2.

Note:

• Excluding trivial changes, all contributions should be connected to an existing issue.
• API changes must go through the change proposal process before they can be accepted.
• The code owners are listed at dev.golang.org/owners.

Overview (`vendor/golang.org/x/term/README.md`) Copy Section

Go terminal/console support

This repository provides Go terminal and console support packages.

Report Issues / Send Patches Copy Chapter

This repository uses Gerrit for code changes. To learn how to submit changes to
this repository, see https://go.dev/doc/contribute.

The git repository is https://go.googlesource.com/term.

The main issue tracker for the term repository is located at
https://go.dev/issues. Prefix your issue with "x/term:" in the
subject line, so it is easy to find.

Overview (`vendor/github.com/Masterminds/semver/v3/README.md`) Copy Section

SemVer

The semver package provides the ability to work with Semantic Versions in Go. Specifically it provides the ability to:

• Parse semantic versions
• Sort semantic versions
• Check if a semantic version fits within a set of constraints
• Optionally work with a v prefix

Package Versions Copy Chapter

Note, import github.com/Masterminds/semver/v3 to use the latest version.

There are three major versions fo the semver package.

• 3.x.x is the stable and active version. This version is focused on constraint
  compatibility for range handling in other tools from other languages. It has
  a similar API to the v1 releases. The development of this version is on the master
  branch. The documentation for this version is below.
• 2.x was developed primarily for dep. There are
  no tagged releases and the development was performed by @sdboyer.
  There are API breaking changes from v1. This version lives on the 2.x branch.
• 1.x.x is the original release. It is no longer maintained. You should use the
  v3 release instead. You can read the documentation for the 1.x.x release
  here.

Parsing Semantic Versions Copy Chapter

There are two functions that can parse semantic versions. The StrictNewVersion
function only parses valid version 2 semantic versions as outlined in the
specification. The NewVersion function attempts to coerce a version into a
semantic version and parse it. For example, if there is a leading v or a version
listed without all 3 parts (e.g. v1.2) it will attempt to coerce it into a valid
semantic version (e.g., 1.2.0). In both cases a Version object is returned
that can be sorted, compared, and used in constraints.

When parsing a version an error is returned if there is an issue parsing the
version. For example,

v, err := semver.NewVersion("1.2.3-beta.1+build345")

The version object has methods to get the parts of the version, compare it to
other versions, convert the version back into a string, and get the original
string. Getting the original string is useful if the semantic version was coerced
into a valid form.

There are package level variables that affect how NewVersion handles parsing.

• CoerceNewVersion is true by default. When set to true it coerces non-compliant
  versions into SemVer. For example, allowing a leading 0 in a major, minor, or patch
  part. This enables the use of CalVer in versions even when not compliant with SemVer.
  When set to false less coercion work is done.
• DetailedNewVersionErrors provides more detailed errors. It only has an affect when
  CoerceNewVersion is set to false. When DetailedNewVersionErrors is set to true
  it can provide some more insight into why a version is invalid. Setting
  DetailedNewVersionErrors to false is faster on performance but provides less
  detailed error messages if a version fails to parse.

Sorting Semantic Versions Copy Chapter

A set of versions can be sorted using the sort package from the standard library.
For example,

raw := []string{"1.2.3", "1.0", "1.3", "2", "0.4.2",}
vs := make([]*semver.Version, len(raw))
for i, r := range raw {
    v, err := semver.NewVersion(r)
    if err != nil {
        t.Errorf("Error parsing version: %s", err)
    }

    vs[i] = v
}

sort.Sort(semver.Collection(vs))

Checking Version Constraints Copy Chapter

There are two methods for comparing versions. One uses comparison methods on
Version instances and the other uses Constraints. There are some important
differences to notes between these two methods of comparison.

1. When two versions are compared using functions such as Compare, LessThan,
   and others it will follow the specification and always include pre-releases
   within the comparison. It will provide an answer that is valid with the
   comparison section of the spec at https://semver.org/#spec-item-11
2. When constraint checking is used for checks or validation it will follow a
   different set of rules that are common for ranges with tools like npm/js
   and Rust/Cargo. This includes considering pre-releases to be invalid if the
   ranges does not include one. If you want to have it include pre-releases a
   simple solution is to include -0 in your range.
3. Constraint ranges can have some complex rules including the shorthand use of
   ~ and ^. For more details on those see the options below.

There are differences between the two methods or checking versions because the
comparison methods on Version follow the specification while comparison ranges
are not part of the specification. Different packages and tools have taken it
upon themselves to come up with range rules. This has resulted in differences.
For example, npm/js and Cargo/Rust follow similar patterns while PHP has a
different pattern for ^. The comparison features in this package follow the
npm/js and Cargo/Rust lead because applications using it have followed similar
patters with their versions.