Merge pull request #1152 from architkulkarni/status-codes

Add error codes for STATUS verb to `types.go` and `SPEC.md`

.gitattributes

@@ -0,0 +1,2 @@
+# Don't rewrite line endings
+*.go -text

.github/actions/retest-action/Dockerfile

@@ -0,0 +1,7 @@
+FROM alpine:3.20
+
+RUN apk add --no-cache curl jq
+
+COPY entrypoint.sh /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]

.github/actions/retest-action/action.yml

@@ -0,0 +1,11 @@
+name: 'Re-Test'
+description: 'Re-Runs the last workflow for a PR'
+inputs:
+  token:
+    description: 'GitHub API Token'
+    required: true
+runs:
+  using: 'docker'
+  image: 'Dockerfile'
+  env:
+    GITHUB_TOKEN: ${{ inputs.token }}

.github/actions/retest-action/entrypoint.sh

@@ -0,0 +1,45 @@
+#!/bin/sh
+
+set -ex
+
+if ! jq -e '.issue.pull_request' ${GITHUB_EVENT_PATH}; then
+    echo "Not a PR... Exiting."
+    exit 0
+fi
+
+if [ "$(jq -r '.comment.body' ${GITHUB_EVENT_PATH})" != "/retest" ]; then
+    echo "Nothing to do... Exiting."
+    exit 0
+fi
+
+PR_URL=$(jq -r '.issue.pull_request.url' ${GITHUB_EVENT_PATH})
+
+curl --request GET \
+    --url "${PR_URL}" \
+    --header "authorization: Bearer ${GITHUB_TOKEN}" \
+    --header "content-type: application/json" > pr.json
+
+ACTOR=$(jq -r '.user.login' pr.json)
+BRANCH=$(jq -r '.head.ref' pr.json)
+
+curl --request GET \
+    --url "https://api.github.com/repos/${GITHUB_REPOSITORY}/actions/runs?event=pull_request&actor=${ACTOR}&branch=${BRANCH}" \
+    --header "authorization: Bearer ${GITHUB_TOKEN}" \
+    --header "content-type: application/json" | jq '.workflow_runs | max_by(.run_number)' > run.json
+
+RERUN_URL=$(jq -r '.rerun_url' run.json)
+
+curl --request POST \
+    --url "${RERUN_URL}" \
+    --header "authorization: Bearer ${GITHUB_TOKEN}" \
+    --header "content-type: application/json"
+
+
+REACTION_URL="$(jq -r '.comment.url' ${GITHUB_EVENT_PATH})/reactions"
+
+curl --request POST \
+    --url "${REACTION_URL}" \
+    --header "authorization: Bearer ${GITHUB_TOKEN}" \
+    --header "accept: application/vnd.github.squirrel-girl-preview+json" \
+    --header "content-type: application/json" \
+    --data '{ "content" : "rocket" }'

.github/dependabot.yml

@@ -0,0 +1,27 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "docker"
+    directory: "/.github/actions/retest-action"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "gomod"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      golang:
+        patterns:
+          - "*"
+  - package-ecosystem: "gomod"
+    directory: "/plugins/debug"
+    schedule:
+      interval: "weekly"

.github/workflows/commands.yml

@@ -0,0 +1,17 @@
+name: commands
+on:
+  issue_comment:
+    types: [created]
+
+jobs:
+  retest:
+    if: github.repository == 'containernetworking/cni'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332  # v4.1.7
+
+      - name: Re-Test Action
+        uses: ./.github/actions/retest-action
+        with:
+          token: ${{ secrets.REPO_ACCESS_TOKEN }}

.github/workflows/scorecard.yml

@@ -0,0 +1,40 @@
+name: Scorecard supply-chain security
+on:
+  branch_protection_rule:
+  push:
+    branches:
+      - main
+  schedule:
+    - cron: 29 15 * * 0
+permissions: read-all
+jobs:
+  analysis:
+    name: Scorecard analysis
+    permissions:
+      id-token: write
+      security-events: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1
+        with:
+          persist-credentials: false
+
+      - name: Run analysis
+        uses: ossf/scorecard-action@0864cf19026789058feabb7e87baa5f140aac736  # v2.3.1
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@97a0fba1372883ab732affbe8f94b823f91727db  # v3.pre.node20
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5
+
+      - name: Upload to code-scanning
+        uses: github/codeql-action/upload-sarif@8214744c546c1e5c8f03dde8fab3a7353211988d  # v3.26.7
+        with:
+          sarif_file: results.sarif

.github/workflows/test.yaml

@@ -0,0 +1,96 @@
+---
+name: test
+
+on: ["push", "pull_request"]
+
+env:
+  GO_VERSION: "1.22"
+  LINUX_ARCHES: "amd64 386 arm arm64 s390x mips64le ppc64le"
+
+jobs:
+  lint:
+    name: Lint
+    permissions:
+      contents: read
+      pull-requests: read
+    runs-on: ubuntu-latest
+    steps:
+      - name: setup go
+        uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32  # v5.0.2
+        with:
+          go-version: ${{ env.GO_VERSION }}
+
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332  # v4.1.7
+
+      - uses: ibiqlik/action-yamllint@2576378a8e339169678f9939646ee3ee325e845c  # v3.1.1
+        with:
+          format: auto
+          config_file: .yamllint.yaml
+
+      - uses: golangci/golangci-lint-action@aaa42aa0628b4ae2578232a66b541047968fac86  # v6.1.0
+        with:
+          args: --verbose
+          version: v1.57.1
+
+  build:
+    name: Build all linux architectures
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: setup go
+        uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32  # v5.0.2
+        with:
+          go-version: ${{ env.GO_VERSION }}
+
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332  # v4.1.7
+
+      - name: Build on all supported architectures
+        run: |
+          set -e
+          for arch in ${LINUX_ARCHES}; do
+            echo "Building for arch $arch"
+            GOARCH=$arch go build ./...
+          done
+
+  test-linux:
+    name: Run tests on Linux amd64
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: setup go
+        uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32  # v5.0.2
+        with:
+          go-version: ${{ env.GO_VERSION }}
+
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332  # v4.1.7
+
+      - name: Install test binaries
+        run: |
+          go install github.com/mattn/goveralls@v0.0.12
+          go install github.com/modocache/gover@latest
+
+      - name: test
+        run: COVERALLS=1 ./test.sh
+
+      - env:
+          COVERALLS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        name: Send coverage to coveralls
+        run: |
+          PATH=$PATH:$(go env GOPATH)/bin
+          gover
+          goveralls -coverprofile=gover.coverprofile -service=github
+
+  test-win:
+    name: Build and run tests on Windows
+    needs: build
+    runs-on: windows-latest
+    steps:
+      - name: setup go
+        uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32  # v5.0.2
+        with:
+          go-version: ${{ env.GO_VERSION }}
+
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332  # v4.1.7
+
+      - name: test
+        run: bash ./test.sh

.gitignore

@@ -1,3 +1,5 @@
-bin/
-gopath/
+.idea/
 *.sw[ponm]
+.vagrant
+release-*
+cnitool/cnitool

.golangci.yml

@@ -0,0 +1,30 @@
+linters:
+  enable:
+    - contextcheck
+    - errcheck
+    - errorlint
+    - gci
+    - ginkgolinter
+    - gocritic
+    - gofumpt
+    - govet
+    - ineffassign
+    - misspell
+    - nolintlint
+    - nonamedreturns
+    - predeclared
+    - staticcheck
+    - typecheck
+    - unconvert
+    - unused
+    - whitespace
+
+linters-settings:
+  gci:
+    sections:
+      - standard
+      - default
+      - prefix(github.com/containernetworking)
+
+run:
+  timeout: 5m

.travis.yml

@@ -1,29 +0,0 @@
-language: go
-sudo: required
-dist: trusty
-
-go:
-  - 1.5.3
-  - 1.6
-  - tip
-
-matrix:
-  allow_failures:
-    - go: tip
-
-env:
-  global:
-    - TOOLS_CMD=golang.org/x/tools/cmd
-    - PATH=$GOROOT/bin:$PATH
-    - GO15VENDOREXPERIMENT=1
-
-install:
- - go get ${TOOLS_CMD}/cover
- - go get github.com/modocache/gover
- - go get github.com/mattn/goveralls
-
-script:
- - ./test
-
-notifications:
-  email: false

.yamllint.yaml

@@ -0,0 +1,10 @@
+---
+extends: default
+
+rules:
+  document-start: disable
+  line-length: disable
+  truthy:
+    ignore: |
+      .github/workflows/*.yml
+      .github/workflows/*.yaml

CODE-OF-CONDUCT.md

@@ -0,0 +1,3 @@
+# Community Code of Conduct
+
+CNI follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md).

CONTRIBUTING.md

@@ -1,24 +1,25 @@
 # How to Contribute
 
-cni is [Apache 2.0 licensed](LICENSE) and accepts contributions via GitHub
+CNI is [Apache 2.0 licensed](LICENSE) and accepts contributions via GitHub
 pull requests. This document outlines some of the conventions on development
 workflow, commit message formatting, contact points and other resources to make
 it easier to get your contribution accepted.
 
-We welcome improvements to documentation as well as to code.
+We gratefully welcome improvements to documentation as well as to code.
 
-# Certificate of Origin
+## Certificate of Origin
 
 By contributing to this project you agree to the Developer Certificate of
 Origin (DCO). This document was created by the Linux Kernel community and is a
 simple statement that you, as a contributor, have the legal right to make the
 contribution. See the [DCO](DCO) file for details.
 
-# Email and Chat
+## Email and Chat
 
-The project uses the the cni-dev email list and IRC chat:
+The project uses the cni-dev email list, IRC chat, and Slack:
 - Email: [cni-dev](https://groups.google.com/forum/#!forum/cni-dev)
-- IRC: #[containernetworking](irc://irc.freenode.org:6667/#containernetworking) channel on freenode.org
+- IRC: #[containernetworking](irc://irc.freenode.net:6667/#containernetworking) channel on [freenode.net](https://freenode.net/)
+- Slack: #cni on the [CNCF slack](https://slack.cncf.io/).  NOTE: the previous CNI Slack (containernetworking.slack.com) has been sunsetted.
 
 Please avoid emailing maintainers found in the MAINTAINERS file directly. They
 are very busy and read the mailing lists.
@@ -33,15 +34,53 @@ are very busy and read the mailing lists.
 
 This is a rough outline of how to prepare a contribution:
 
-- Create a topic branch from where you want to base your work (usually branched from master).
+- Create a topic branch from where you want to base your work (usually branched from main).
 - Make commits of logical units.
 - Make sure your commit messages are in the proper format (see below).
 - Push your changes to a topic branch in your fork of the repository.
-- If you changed code, make sure the tests pass, and add any new tests as appropriate.
-- Make sure any new code files have a license header.
+- If you changed code:
+  - add automated tests to cover your changes, using the [Ginkgo](https://onsi.github.io/ginkgo/) & [Gomega](https://onsi.github.io/gomega/) style
+  - if the package did not previously have any test coverage, add it to the list
+   of `TESTABLE` packages in the `test.sh` script.
+  - run the full test script and ensure it passes
+- Make sure any new code files have a license header (this is now enforced by automated tests)
 - Submit a pull request to the original repository.
 
-Thanks for your contributions!
+## How to run the test suite
+
+We generally require test coverage of any new features or bug fixes.
+
+Here's how you can run the test suite on any system (even Mac or Windows) using
+ [Vagrant](https://www.vagrantup.com/) and a hypervisor of your choice:
+
+```bash
+vagrant up
+vagrant ssh
+# you're now in a shell in a virtual machine
+sudo su
+cd /go/src/github.com/containernetworking/cni
+
+# to run the full test suite
+./test.sh
+
+# to focus on a particular test suite
+cd libcni
+go test
+```
+
+## Acceptance policy
+
+These things will make a PR more likely to be accepted:
+
+- a well-described requirement
+- tests for new code
+- tests for old code!
+- new code and tests follow the conventions in old code and tests
+- a good commit message (see below)
+
+In general, we will merge a PR once two maintainers have endorsed it.
+Trivial changes (e.g., corrections to spelling) may get waved through.
+For substantial changes, more people may become involved, and you might get asked to resubmit the PR or divide the changes into more than one PR.
 
 ### Format of the Commit Message
 
@@ -49,7 +88,7 @@ We follow a rough convention for commit messages that is designed to answer two
 questions: what changed and why. The subject line should feature the what and
 the body of the commit should describe the why.
 
-```
+```md
 scripts: add the test-cluster command
 
 this uses tmux to setup a test cluster that you can easily kill and
@@ -60,7 +99,7 @@ Fixes #38
 
 The format can be described more formally as follows:
 
-```
+```md
 <subsystem>: <what changed>
 <BLANK LINE>
 <why this change was made>
@@ -72,3 +111,18 @@ The first line is the subject and should be no longer than 70 characters, the
 second line is always blank, and other lines should be wrapped at 80 characters.
 This allows the message to be easier to read on GitHub as well as in various
 git tools.
+
+## 3rd party plugins
+
+So you've built a CNI plugin.  Where should it live?
+
+Short answer: We'd be happy to link to it from our [list of 3rd party plugins](README.md#3rd-party-plugins).
+But we'd rather you kept the code in your own repo.
+
+Long answer: An advantage of the CNI model is that independent plugins can be
+built, distributed and used without any code changes to this repository.  While
+some widely used plugins (and a few less-popular legacy ones) live in this repo,
+we're reluctant to add more.
+
+If you have a good reason why the CNI maintainers should take custody of your
+plugin, please open an issue or PR.

CONVENTIONS.md

@@ -0,0 +1,120 @@
+# Extension conventions                                                        
+                                                                                 
+There are three ways of passing information to plugins using the Container Network Interface (CNI), none of which require the [spec](SPEC.md) to be updated. These are 
+- plugin specific fields in the JSON config
+- `args` field in the JSON config
+- `CNI_ARGS` environment variable 
+
+This document aims to provide guidance on which method should be used and to provide a convention for how common information should be passed.
+Establishing these conventions allows plugins to work across multiple runtimes. This helps both plugins and the runtimes.
+
+## Plugins
+* Plugin authors should aim to support these conventions where it makes sense for their plugin. This means they are more likely to "just work" with a wider range of runtimes.
+* Plugins should accept arguments according to these conventions if they implement the same basic functionality as other plugins. If plugins have shared functionality that isn't covered by these conventions then a PR should be opened against this document.
+
+## Runtimes
+* Runtime authors should follow these conventions if they want to pass additional information to plugins. This will allow the extra information to be consumed by the widest range of plugins.
+* These conventions serve as an abstraction for the runtime. For example, port forwarding is highly implementation specific, but users should be able to select the plugin of their choice without changing the runtime.
+
+# Current conventions
+Additional conventions can be created by creating PRs which modify this document.
+
+## Dynamic Plugin specific fields (Capabilities / Runtime Configuration)
+[Plugin specific fields](SPEC.md#network-configuration) formed part of the original CNI spec and have been present since the initial release.
+> Plugins may define additional fields that they accept and may generate an error if called with unknown fields. The exception to this is the args field may be used to pass arbitrary data which may be ignored by plugins.
+
+A plugin can define any additional fields it needs to work properly. It should return an error if it can't act on fields that were expected or where the field values were malformed.
+
+This method of passing information to a plugin is recommended when the following conditions hold:
+* The configuration has specific meaning to the plugin (i.e. it's not just general meta data)
+* the plugin is expected to act on the configuration or return an error if it can't
+
+Dynamic information (i.e. data that a runtime fills out) should be placed in a `runtimeConfig` section. Plugins can request
+that the runtime insert this dynamic configuration by explicitly listing their `capabilities` in the network configuration.
+
+For example, the configuration for a port mapping plugin might look like this to an operator (it should be included as part of a [network configuration list](SPEC.md#network-configuration-lists).
+```json
+{
+  "name" : "ExamplePlugin",
+  "type" : "port-mapper",
+  "capabilities": {"portMappings": true}
+}
+```
+
+But the runtime would fill in the mappings so the plugin itself would receive something like this.
+```json
+{
+  "name" : "ExamplePlugin",
+  "type" : "port-mapper",
+  "runtimeConfig": {
+    "portMappings": [
+      {"hostPort": 8080, "containerPort": 80, "protocol": "tcp"}
+    ]
+  }
+}
+```
+
+### Well-known Capabilities
+| Area  | Purpose | Capability | Spec and Example | Runtime implementations | Plugin Implementations |
+| ----- | ------- | -----------| ---------------- | ----------------------- | ---------------------  |
+| port mappings | Pass mapping from ports on the host to ports in the container network namespace. | `portMappings` | A list of portmapping entries.<br/>  <pre>[<br/>  { "hostPort": 8080, "containerPort": 80, "protocol": "tcp" },<br />  { "hostPort": 8000, "containerPort": 8001, "protocol": "udp" }<br />  ]<br /></pre> | kubernetes | CNI `portmap` plugin |
+| ip ranges | Dynamically configure the IP range(s) for address allocation. Runtimes that manage IP pools, but not individual IP addresses, can pass these to plugins. | `ipRanges` | The same as the `ranges` key for `host-local` - a list of lists of subnets. The outer list is the number of IPs to allocate, and the inner list is a pool of subnets for each allocation. <br/><pre>[<br/> [<br/>  { "subnet": "10.1.2.0/24", "rangeStart": "10.1.2.3", "rangeEnd": 10.1.2.99", "gateway": "10.1.2.254" } <br/>  ]<br/>]</pre> | none | CNI `host-local` plugin |
+| bandwidth limits | Dynamically configure interface bandwidth limits | `bandwidth` | Desired bandwidth limits. Rates are in bits per second, burst values are in bits. <pre> { "ingressRate": 2048, "ingressBurst": 1600, "egressRate": 4096, "egressBurst": 1600 } </pre> | none | CNI `bandwidth` plugin |
+| dns | Dynamically configure dns according to runtime | `dns` | Dictionary containing a list of `servers` (string entries), a list of `searches` (string entries), a list of `options` (string entries). <pre>{ <br> "searches" : [ "internal.yoyodyne.net", "corp.tyrell.net" ] <br> "servers": [ "8.8.8.8", "10.0.0.10" ] <br />} </pre> | kubernetes | CNI `win-bridge` plugin, CNI `win-overlay` plugin |
+| ips | Dynamically allocate IPs for container interface. Runtime which has the ability of address allocation can pass these to plugins.  | `ips` | A list of `IP` (\<ip\>\[/\<prefix\>\]). <pre> [ "192.168.0.1", 10.10.0.1/24", "3ffe:ffff:0:01ff::2", "3ffe:ffff:0:01ff::1/64" ] </pre> The plugin may require the IP address to include a prefix length. | none | CNI `static` plugin, CNI `host-local` plugin |
+| mac | Dynamically assign MAC. Runtime can pass this to plugins which need MAC as input. | `mac` | `MAC` (string entry). <pre> "c2:11:22:33:44:55" </pre> | none | CNI `tuning` plugin |
+| infiniband guid | Dynamically assign Infiniband GUID to network interface. Runtime can pass this to plugins which need Infiniband GUID as input. | `infinibandGUID` | `GUID` (string entry). <pre> "c2:11:22:33:44:55:66:77" </pre> | none | CNI [`ib-sriov-cni`](https://github.com/Mellanox/ib-sriov-cni) plugin |
+| device id | Provide device identifier which is associated with the network to allow the CNI plugin to perform device dependent network configurations. | `deviceID` | `deviceID` (string entry). <pre> "0000:04:00.5" </pre> | none | CNI `host-device` plugin |
+| aliases | Provide a list of names that will be mapped to the IP addresses assigned to this interface. Other containers on the same network may use one of these names to access the container.| `aliases` | List of `alias` (string entry). <pre> ["my-container", "primary-db"] </pre> | none | CNI `alias` plugin |
+| cgroup path | Provide the cgroup path for pod as requested by CNI plugins. | `cgroupPath` | `cgroupPath` (string entry). <pre>"/kubelet.slice/kubelet-kubepods.slice/kubelet-kubepods-burstable.slice/kubelet-kubepods-burstable-pod28ce45bc_63f8_48a3_a99b_cfb9e63c856c.slice" </pre> | none | CNI `host-local` plugin |
+
+## "args" in network config
+`args` in [network config](SPEC.md#network-configuration) were reserved as a  field in the `0.2.0` release of the CNI spec.
+> args (dictionary): Optional additional arguments provided by the container runtime. For example a dictionary of labels could be passed to CNI plugins by adding them to a labels field under args.
+
+`args` provide a way of providing more structured data than the flat strings that CNI_ARGS can support.
+
+`args` should be used for _optional_ meta-data. Runtimes can place additional data in `args` and plugins that don't understand that data should just ignore it. Runtimes should not require that a plugin understands or consumes that data provided, and so a runtime should not expect to receive an error if the data could not be acted on.
+
+This method of passing information to a plugin is recommended when the information is optional and the plugin can choose to ignore it. It's often that case that such information is passed to all plugins by the runtime without regard for whether the plugin can understand it.
+
+The conventions documented here are all namespaced under `cni` so they don't conflict with any existing `args`.
+
+For example:
+```jsonc
+{  
+   "cniVersion":"0.2.0",
+   "name":"net",
+   "args":{  
+      "cni":{  
+         "labels": [{"key": "app", "value": "myapp"}]
+      }
+   },
+   // <REST OF CNI CONFIG HERE>
+   "ipam":{  
+   //  <IPAM CONFIG HERE>
+   }
+}
+```
+
+| Area  | Purpose| Spec and Example | Runtime implementations | Plugin Implementations |
+| ----- | ------ | ------------     | ----------------------- | ---------------------- |
+| labels | Pass`key=value` labels to plugins | <pre>"labels" : [<br />  { "key" : "app", "value" : "myapp" },<br />  { "key" : "env", "value" : "prod" }<br />] </pre> | none | none |
+| ips   | Request specific IPs | Spec:<pre>"ips": ["\<ip\>[/\<prefix\>]", ...]</pre>Examples:<pre>"ips": ["10.2.2.42/24", "2001:db8::5"]</pre> The plugin may require the IP address to include a prefix length. | none | host-local, static |
+
+## CNI_ARGS
+CNI_ARGS formed part of the original CNI spec and have been present since the initial release.
+> `CNI_ARGS`: Extra arguments passed in by the user at invocation time. Alphanumeric key-value pairs separated by semicolons; for example, "FOO=BAR;ABC=123"
+
+The use of `CNI_ARGS` is deprecated and "args" should be used instead. If a runtime passes an equivalent key via `args` (eg the `ips` `args` Area and the `CNI_ARGS` `IP` Field) and the plugin understands `args`, the plugin must ignore the CNI_ARGS Field.
+
+| Field  | Purpose| Spec and Example | Runtime implementations | Plugin Implementations |
+| ------ | ------ | ---------------- | ----------------------- | ---------------------- |
+| IP     | Request a specific IP from IPAM plugins | Spec:<pre>IP=\<ip\>[/\<prefix\>]</pre>Example: <pre>IP=192.168.10.4/24</pre> The plugin may require the IP addresses to include a prefix length. | *rkt* supports passing additional arguments to plugins and the [documentation](https://coreos.com/rkt/docs/latest/networking/overriding-defaults.html) suggests IP can be used. | host-local, static |
+
+## Chained Plugins
+If plugins are agnostic about the type of interface created, they SHOULD work in a chained mode and configure existing interfaces. Plugins MAY also create the desired interface when not run in a chain.
+
+For example, the `bridge` plugin adds the host-side interface to a bridge. So, it should accept any previous result that includes a host-side interface, including `tap` devices. If not called as a chained plugin, it creates a `veth` pair first.
+
+Plugins that meet this convention are usable by a larger set of runtimes and interfaces, including hypervisors and DPDK providers.

Documentation/bridge.md

@@ -1,40 +0,0 @@
-# bridge plugin
-
-## Overview
-
-With bridge plugin, all containers (on the same host) are plugged into a bridge (virtual switch) that resides in the host network namespace.
-The containers receive one end of the veth pair with the other end connected to the bridge.
-An IP address is only assigned to one end of the veth pair -- one residing in the container.
-The bridge itself can also be assigned an IP address, turning it into a gateway for the containers.
-Alternatively, the bridge can function purely in L2 mode and would need to be bridged to the host network interface (if other than container-to-container communication on the same host is desired).
-
-The network configuration specifies the name of the bridge to be used.
-If the bridge is missing, the plugin will create one on first use and, if gateway mode is used, assign it an IP that was returned by IPAM plugin via the gateway field.
-
-## Example configuration
-```
-{
-	"name": "mynet",
-	"type": "bridge",
-	"bridge": "mynet0",
-	"isDefaultGateway": true,
-	"ipMasq": true,
-	"hairpinMode": true,
-	"ipam": {
-		"type": "host-local",
-		"subnet": "10.10.0.0/16"
-	}
-}
-```
-
-## Network configuration reference
-
-* `name` (string, required): the name of the network.
-* `type` (string, required): "bridge".
-* `bridge` (string, optional): name of the bridge to use/create. Defaults to "cni0".
-* `isGateway` (boolean, optional): assign an IP address to the bridge. Defaults to false.
-* `isDefaultGateway` (boolean, optional): Sets isGateway to true and makes the assigned IP the default route. Defaults to false.
-* `ipMasq` (boolean, optional): set up IP Masquerade on the host for traffic originating from this network and destined outside of it. Defaults to false.
-* `mtu` (integer, optional): explicitly set MTU to the specified value. Defaults to the value chosen by the kernel.
-* `hairpinMode` (boolean, optional): set hairpin mode for interfaces on the bridge. Defaults to false.
-* `ipam` (dictionary, required): IPAM configuration to be used for this network.

Documentation/cnitool.md

@@ -0,0 +1,19 @@
+# Overview
+
+The `cnitool` is a utility that can be used to test a CNI plugin
+without the need for a container runtime. The `cnitool` takes a
+`network name` and a `network namespace` and a command to `ADD` or
+`DEL`,.i.e, attach or detach containers from a network. The `cnitool`
+relies on the following environment variables to operate properly:
+
+* `NETCONFPATH`: This environment variable needs to be set to a
+  directory. It defaults to `/etc/cni/net.d`. The `cnitool` searches
+  for CNI configuration files in this directory with the extension
+  `*.conf` or `*.json`. It loads all the CNI configuration files in
+  this directory and if it finds a CNI configuration with the `network
+  name` given to the cnitool it returns the corresponding CNI
+  configuration, else it returns `nil`.
+* `CNI_PATH`: For a given CNI configuration `cnitool` will search for
+  the corresponding CNI plugin in this path.
+
+For the full documentation of `cnitool` see the [cnitool docs](../cnitool/README.md)

Documentation/dhcp.md

@@ -1,35 +0,0 @@
-# dhcp plugin
-
-## Overview
-
-With dhcp plugin the containers can get an IP allocated by a DHCP server already running on your network.
-This can be especially useful with plugin types such as [macvlan](https://github.com/containernetworking/cni/blob/master/Documentation/macvlan.md).
-Because a DHCP lease must be periodically renewed for the duration of container lifetime, a separate daemon is required to be running.
-The same plugin binary can also be run in the daemon mode.
-
-## Operation
-To use the dhcp IPAM plugin, first launch the dhcp daemon:
-
-```
-# Make sure the unix socket has been removed
-$ rm -f /run/cni/dhcp.sock
-$ ./dhcp daemon
-```
-
-Alternatively, you can use systemd socket activation protocol.
-Be sure that the .socket file uses /run/cni/dhcp.sock as the socket path.
-
-With the daemon running, containers using the dhcp plugin can be launched.
-
-## Example configuration
-
-```
-{
-	"ipam": {
-		"type": "dhcp",
-	}
-}
-
-## Network configuration reference
-
-* `type` (string, required): "dhcp"

Documentation/flannel.md

@@ -1,87 +0,0 @@
-# flannel plugin
-
-## Overview
-This plugin is designed to work in conjunction with [flannel](https://github.com/coreos/flannel), a network fabric for containers.
-When flannel daemon is started, it outputs a `/run/flannel/subnet.env` file that looks like this:
-```
-FLANNEL_NETWORK=10.1.0.0/16
-FLANNEL_SUBNET=10.1.17.1/24
-FLANNEL_MTU=1472
-FLANNEL_IPMASQ=true
-```
-
-This information reflects the attributes of flannel network on the host.
-The flannel CNI plugin uses this information to configure another CNI plugin, such as bridge plugin.
-
-## Operation
-Given the following network configuration file and the contents of `/run/flannel/subnet.env` above,
-```
-{
-	"name": "mynet",
-	"type": "flannel"
-}
-```
-the flannel plugin will generate another network configuration file:
-```
-{
-	"name": "mynet",
-	"type": "bridge",
-	"mtu": 1472,
-	"ipMasq": false,
-	"isGateway": true,
-	"ipam": {
-		"type": "host-local",
-		"subnet": "10.1.17.0/24"
-	}
-}
-```
-
-It will then invoke the bridge plugin, passing it the generated configuration.
-
-As can be seen from above, the flannel plugin, by default, will delegate to the bridge plugin.
-If additional configuration values need to be passed to the bridge plugin, it can be done so via the `delegate` field:
-```
-{
-	"name": "mynet",
-	"type": "flannel",
-	"delegate": {
-		"bridge": "mynet0",
-		"mtu": 1400
-	}
-}
-```
-
-This supplies a configuration parameter to the bridge plugin -- the created bridge will now be named `mynet0`.
-Notice that `mtu` has also been specified and this value will not be overwritten by flannel plugin.
-
-Additionally, the `delegate` field can be used to select a different kind of plugin altogether.
-To use `ipvlan` instead of `bridge`, the following configuration can be specified:
-
-```
-{
-	"name": "mynet",
-	"type": "flannel",
-	"delegate": {
-		"type": "ipvlan",
-		"master": "eth0"
-	}
-}
-```
-
-## Network configuration reference
-
-* `name` (string, required): the name of the network
-* `type` (string, required): "flannel"
-* `subnetFile` (string, optional): full path to the subnet file written out by flanneld. Defaults to /run/flannel/subnet.env
-* `delegate` (dictionary, optional): specifies configuration options for the delegated plugin.
-
-flannel plugin will always set the following fields in the delegated plugin configuration:
-
-* `name`: value of its "name" field.
-* `ipam`: "host-local" type will be used with "subnet" set to `$FLANNEL_SUBNET`.
-
-flannel plugin will set the following fields in the delegated plugin configuration if they are not present:
-* `ipMasq`: the inverse of `$FLANNEL_IPMASQ`
-* `mtu`: `$FLANNEL_MTU`
-
-Additionally, for the bridge plugin, `isGateway` will be set to `true`, if not present.

Documentation/host-local.md

@@ -1,41 +0,0 @@
-# host-local plugin
-
-## Overview
-
-host-local IPAM plugin allocates IPv4 addresses out of a specified address range.
-It stores the state locally on the host filesystem, therefore ensuring uniqueness of IP addresses on a single host.
-
-## Example configuration
-```
-{
-	"ipam": {
-		"type": "host-local",
-		"subnet": "10.10.0.0/16",
-		"rangeStart": "10.10.1.20",
-		"rangeEnd": "10.10.3.50",
-		"gateway": "10.10.0.254",
-		"routes": [
-			{ "dst": "0.0.0.0/0" },
-			{ "dst": "192.168.0.0/16", "gw": "10.10.5.1" }
-		]
-	}
-}
-```
-
-## Network configuration reference
-
-* `type` (string, required): "host-local".
-* `subnet` (string, required): CIDR block to allocate out of.
-* `rangeStart` (string, optional): IP inside of "subnet" from which to start allocating addresses. Defaults to ".2" IP inside of the "subnet" block.
-* `rangeEnd` (string, optional): IP inside of "subnet" with which to end allocating addresses. Defaults to ".254" IP inside of the "subnet" block.
-* `gateway` (string, optional): IP inside of "subnet" to designate as the gateway. Defaults to ".1" IP inside of the "subnet" block.
-* `routes` (string, optional): list of routes to add to the container namespace. Each route is a dictionary with "dst" and optional "gw" fields. If "gw" is omitted, value of "gateway" will be used.
-
-## Supported arguments
-The following [CNI_ARGS](https://github.com/containernetworking/cni/blob/master/SPEC.md#parameters) are supported:
-
-* `ip`: request a specific IP address from the subnet. If it's not available, the plugin will exit with an error
-
-## Files
-
-Allocated IP addresses are stored as files in /var/lib/cni/networks/$NETWORK_NAME.

Documentation/ipvlan.md

@@ -1,40 +0,0 @@
-# ipvlan plugin
-
-## Overview
-
-ipvlan is a new [addition](https://lwn.net/Articles/620087/) to the Linux kernel.
-Like its cousin macvlan, it virtualizes the host interface.
-However unlike macvlan which generates a new MAC address for each interface, ipvlan devices all share the same MAC.
-The kernel driver inspects the IP address of each packet when making a decision about which virtual interface should process the packet.
-
-Because all ipvlan interfaces share the MAC address with the host interface, DHCP can only be used in conjunction with ClientID (currently not supported by DHCP plugin).
-
-## Example configuration
-
-```
-{
-	"name": "mynet",
-	"type": "ipvlan",
-	"master": "eth0",
-	"ipam": {
-		"type": "host-local",
-		"subnet": "10.1.2.0/24",
-	}
-}
-```
-
-## Network configuration reference
-
-* `name` (string, required): the name of the network.
-* `type` (string, required): "ipvlan".
-* `master` (string, required): name of the host interface to enslave.
-* `mode` (string, optional): one of "l2", "l3". Defaults to "l2".
-* `mtu` (integer, optional): explicitly set MTU to the specified value. Defaults to the value chosen by the kernel.
-* `ipam` (dictionary, required): IPAM configuration to be used for this network.
-
-## Notes
-
-* `ipvlan` does not allow virtual interfaces to communicate with the master interface.
-Therefore the container will not be able to reach the host via `ipvlan` interface.
-Be sure to also have container join a network that provides connectivity to the host (e.g. `ptp`).
-* A single master interface can not be enslaved by both `macvlan` and `ipvlan`.

Documentation/macvlan.md

@@ -1,34 +0,0 @@
-# macvlan plugin
-
-## Overview
-
-[macvlan](http://backreference.org/2014/03/20/some-notes-on-macvlanmacvtap/) functions like a switch that is already connected to the host interface.
-A host interface gets "enslaved" with the virtual interfaces sharing the physical device but having distinct MAC addresses.
-Since each macvlan interface has its own MAC address, it makes it easy to use with existing DHCP servers already present on the network.
-
-## Example configuration
-
-```
-{
-	"name": "mynet",
-	"type": "macvlan",
-	"master": "eth0",
-	"ipam": {
-		"type": "dhcp"
-	}
-}
-```
-
-## Network configuration reference
-
-* `name` (string, required): the name of the network
-* `type` (string, required): "macvlan"
-* `master` (string, required): name of the host interface to enslave
-* `mode` (string, optional): one of "bridge", "private", "vepa", "passthrough". Defaults to "bridge".
-* `mtu` (integer, optional): explicitly set MTU to the specified value. Defaults to the value chosen by the kernel.
-* `ipam` (dictionary, required): IPAM configuration to be used for this network.
-
-## Notes
-
-* If are testing on a laptop, please remember that most wireless cards do not support being enslaved by macvlan.
-* A single master interface can not be enslaved by both `macvlan` and `ipvlan`.

Documentation/ptp.md

@@ -1,30 +0,0 @@
-# ptp plugin
-
-## Overview
-The ptp plugin creates a point-to-point link between a container and the host by using a veth device.
-One end of the veth pair is placed inside a container and the other end resides on the host.
-The host-local IPAM plugin can be used to allocate an IP address to the container.
-The traffic of the container interface will be routed through the interface of the host.
-
-## Example network configuration
-```
-{
-	"name": "mynet",
-	"type": "ptp",
-	"ipam": {
-		"type": "host-local",
-		"subnet": "10.1.1.0/24"
-	},
-	"dns": {
-		"nameservers": [ "10.1.1.1", "8.8.8.8" ]
-	}
-}
-
-## Network configuration reference
-
-* `name` (string, required): the name of the network
-* `type` (string, required): "ptp"
-* `ipMasq` (boolean, optional): set up IP Masquerade on the host for traffic originating from this network and destined outside of it. Defaults to false.
-* `mtu` (integer, optional): explicitly set MTU to the specified value. Defaults to value chosen by the kernel.
-* `ipam` (dictionary, required): IPAM configuration to be used for this network.
-* `dns` (dictionary, optional): DNS information to return as described in the [Result](/SPEC.md#result).

Documentation/spec-upgrades.md

@@ -0,0 +1,294 @@
+# How to Upgrade to CNI Specification v1.0
+
+CNI v1.0 has the following changes:
+
+- non-List configurations are removed
+- the `version` field in the `interfaces` array was redundant and is removed
+
+## libcni Changes in CNI v1.0
+
+**`/pkg/types/current` no longer exists**
+
+This means that runtimes need to explicitly select a version they support.
+This reduces code breakage when revendoring cni into other projects and
+returns the decision on which CNI Spec versions a plugin supports to the
+plugin's authors.
+
+For example, your Go imports might look like
+
+```go
+import (
+    cniv1 "github.com/containernetworking/cni/pkg/types/100"
+)
+```
+
+
+# Changes in CNI v0.4
+
+CNI v0.4 has the following important changes:
+
+- A new verb, "CHECK", was added. Runtimes can now ask plugins to verify the status of a container's attachment
+- A new configuration flag, `disableCheck`, which indicates to the runtime that configuration should not be CHECK'ed
+
+No changes were made to the result type.
+
+
+# How to upgrade to CNI Specification v0.3.0 and later
+
+The 0.3.0 specification contained a small error. The Result structure's `ip` field should have been renamed to `ips` to be consistent with the IPAM result structure definition; this rename was missed when updating the Result to accommodate multiple IP addresses and interfaces. All first-party CNI plugins (bridge, host-local, etc) were updated to use `ips` (and thus be inconsistent with the 0.3.0 specification) and most other plugins have not been updated to the 0.3.0 specification yet, so few (if any) users should be impacted by this change.
+
+The 0.3.1 specification corrects the `Result` structure to use the `ips` field name as originally intended.  This is the only change between 0.3.0 and 0.3.1.
+
+Version 0.3.0 of the [CNI Specification](https://github.com/containernetworking/cni/blob/spec-v0.3.0/SPEC.md) provides rich information
+about container network configuration, including details of network interfaces
+and support for multiple IP addresses.
+
+To support this new data, the specification changed in a couple significant
+ways that will impact CNI users, plugin authors, and runtime authors.
+
+This document provides guidance for how to upgrade:
+
+- [For CNI Users](#for-cni-users)
+- [For Plugin Authors](#for-plugin-authors)
+- [For Runtime Authors](#for-runtime-authors)
+
+**Note**: the CNI Spec is versioned independently from the GitHub releases
+for this repo.  For example, Release v0.4.0 supports Spec version v0.2.0,
+and Release v0.5.0 supports Spec v0.3.0.
+
+----
+
+## For CNI Users
+If you maintain CNI configuration files for a container runtime that uses CNI,
+ensure that the configuration files specify a `cniVersion` field and that the
+version there is supported by your container runtime and CNI plugins.
+Configuration files without a version field should be given version 0.2.0. 
+The CNI spec includes example configuration files for 
+[single plugins](SPEC.md#example-configurations)
+and for [lists of chained plugins](SPEC.md#example-configurations).
+
+Consult the documentation for your runtime and plugins to determine what
+CNI spec versions they support. Test any plugin upgrades before deploying to 
+production. You may find [cnitool](https://github.com/containernetworking/cni/tree/main/cnitool)
+useful. Specifically, your configuration version should be the lowest common
+version supported by your plugins.
+
+## For Plugin Authors
+This section provides guidance for upgrading plugins to CNI Spec Version 0.3.0.
+
+### General guidance for all plugins (language agnostic)
+To provide the smoothest upgrade path, **existing plugins should support
+multiple versions of the CNI spec**.  In particular, plugins with existing
+installed bases should add support for CNI spec version 1.0.0 while maintaining
+compatibility with older versions.
+
+To do this, two changes are required.  First, a plugin should advertise which
+CNI spec versions it supports.  It does this by responding to the `VERSION`
+command with the following JSON data:
+
+```json
+{
+  "cniVersion": "1.0.0",
+  "supportedVersions": [ "0.1.0", "0.2.0", "0.3.0", "0.3.1", "0.4.0", "1.0.0" ]
+}
+```
+
+Second, for the `ADD` command, a plugin must respect the `cniVersion` field
+provided in the [network configuration JSON](SPEC.md#network-configuration). 
+That field is a request for the plugin to return results of a particular format:
+
+- If the `cniVersion` field is not present, then spec v0.2.0 should be assumed
+	and v0.2.0 format result JSON returned.
+
+- If the plugin doesn't support the version, the plugin must error.
+
+- Otherwise, the plugin must return a [CNI Result](SPEC.md#result)
+	in the format requested.
+
+Result formats for older CNI spec versions are available in the
+[git history for SPEC.md](https://github.com/containernetworking/cni/commits/main/SPEC.md).
+
+For example, suppose a plugin, via its `VERSION` response, advertises CNI specification
+support for v0.2.0 and v0.3.0.  When it receives `cniVersion` key of `0.2.0`,
+the plugin must return result JSON conforming to CNI spec version 0.2.0.
+
+### Specific guidance for plugins written in Go
+Plugins written in Go may leverage the Go language packages in this repository
+to ease the process of upgrading and supporting multiple versions.  CNI 
+[Library and Plugins Release v0.5.0](https://github.com/containernetworking/cni/releases/tag/v0.5.0)
+includes important changes to the Golang APIs.  Plugins using these APIs will
+require some changes now, but should more-easily handle spec changes and
+new features going forward.
+
+For plugin authors, the biggest change is that `types.Result` is now an
+interface implemented by concrete struct types in the `types/100`,
+`types/040`, and `types/020` subpackages.
+
+Internally, plugins should use the latest spec version (eg `types/100`) structs,
+and convert to or from specific versions when required.  A typical plugin will
+only need to do a single conversion when it is about to complete and
+needs to print the result JSON in the requested `cniVersion` format to stdout.
+The library function `types.PrintResult()` simplifies this by converting and
+printing in a single call.
+
+Additionally, the plugin should advertise which CNI Spec versions it supports
+via the 3rd argument to `skel.PluginMain()`.
+
+Here is some example code
+
+```go
+import (
+	 "github.com/containernetworking/cni/pkg/skel"
+	 "github.com/containernetworking/cni/pkg/types"
+	 current "github.com/containernetworking/cni/pkg/types/100"
+	 "github.com/containernetworking/cni/pkg/version"
+)
+
+func cmdAdd(args *skel.CmdArgs) error {
+	// determine spec version to use
+	var netConf struct {
+		types.NetConf
+		// other plugin-specific configuration goes here
+	}
+	err := json.Unmarshal(args.StdinData, &netConf)
+	cniVersion := netConf.CNIVersion
+
+	// plugin does its work...
+	//   set up interfaces
+	//   assign addresses, etc
+	
+	// construct the result
+	result := &current.Result{
+		Interfaces: []*current.Interface{ ... },
+		IPs: []*current.IPs{ ... },
+		...
+	}
+	
+	// print result to stdout, in the format defined by the requested cniVersion
+	return types.PrintResult(result, cniVersion)
+}
+
+func main() {
+	skel.PluginMain(cmdAdd, cmdDel, version.All)
+}
+```
+
+Alternately, to use the result from a delegated IPAM plugin, the `result`
+value might be formed like this:
+
+```go
+ipamResult, err := ipam.ExecAdd(netConf.IPAM.Type, args.StdinData)
+result, err := current.NewResultFromResult(ipamResult)
+```
+
+Other examples of spec v0.3.0-compatible plugins are the
+[main plugins in this repo](https://github.com/containernetworking/plugins/)
+
+
+## For Runtime Authors
+
+This section provides guidance for upgrading container runtimes to support
+CNI Spec Version 0.3.0 and later.
+
+### General guidance for all runtimes (language agnostic)
+
+#### Support multiple CNI spec versions
+To provide the smoothest upgrade path and support the broadest range of CNI
+plugins, **container runtimes should support multiple versions of the CNI spec**.
+In particular, runtimes with existing installed bases should add support for CNI
+spec version 0.3.0 and later while maintaining compatibility with older versions.
+
+To support multiple versions of the CNI spec, runtimes should be able to
+call both new and legacy plugins, and handle the results from either.
+
+When calling a plugin, the runtime must request that the plugin respond in a
+particular format by specifying the `cniVersion` field in the
+[Network Configuration](SPEC.md#network-configuration)
+JSON block.  The plugin will then respond with
+a [Result](SPEC.md#result)
+in the format defined by that CNI spec version, and the runtime must parse
+and handle this result.
+
+#### Handle errors due to version incompatibility
+Plugins may respond with error indicating that they don't support the requested
+CNI version (see [Well-known Error Codes](SPEC.md#well-known-error-codes)),
+e.g.
+```json
+{
+  "cniVersion": "0.2.0",
+  "code": 1,
+  "msg": "CNI version not supported"
+}
+```
+In that case, the runtime may retry with a lower CNI spec version, or take
+some other action.
+
+#### (optional) Discover plugin version support
+Runtimes may discover which CNI spec versions are supported by a plugin, by
+calling the plugin with the `VERSION` command.  The `VERSION` command was
+added in CNI spec v0.2.0, so older plugins may not respect it.  In the absence
+of a successful response to `VERSION`, assume that the plugin only supports
+CNI spec v0.1.0.
+
+#### Handle missing data in v0.3.0 and later results
+The Result for the `ADD` command in CNI spec version 0.3.0 and later includes
+a new field `interfaces`.  An IP address in the `ip` field may describe which
+interface it is assigned to, by placing a numeric index in the `interface`
+subfield.
+
+However, some plugins which are v0.3.0 and later compatible may nonetheless
+omit the `interfaces` field and/or set the `interface` index value to `-1`.
+Runtimes should gracefully handle this situation, unless they have good reason
+to rely on the existence of the interface data.  In that case, provide the user
+an error message that helps diagnose the issue.
+
+### Specific guidance for container runtimes written in Go
+Container runtimes written in Go may leverage the Go language packages in this
+repository to ease the process of upgrading and supporting multiple versions.
+CNI [Library and Plugins Release v0.5.0](https://github.com/containernetworking/cni/releases)
+includes important changes to the Golang APIs.  Runtimes using these APIs will
+require some changes now, but should more-easily handle spec changes and
+new features going forward.
+
+For runtimes, the biggest changes to the Go libraries are in the `types` package.
+It has been refactored to make working with versioned results simpler. The top-level 
+`types.Result` is now an opaque interface instead of a struct, and APIs exposed by
+other packages, such as the high-level `libcni` package, have been updated to use 
+this interface.  Concrete types are now per-version subpackages. The `types/current`
+subpackage contains the latest (spec v0.3.0) types.
+
+When up-converting older result types to spec v0.3.0 and later, fields new in
+spec v0.3.0 and later (like `interfaces`) may be empty.  Conversely, when
+down-converting v0.3.0 and later results to an older version, any data in
+those fields will be lost.
+
+| From   | 0.1 | 0.2 | 0.3 | 0.4 | 1.0 |
+|--------|-----|-----|-----|-----|-----|
+| To 0.1 |  ✔  |  ✔  |  x  |  x  |  x  |
+| To 0.2 |  ✔  |  ✔  |  x  |  x  |  x  |
+| To 0.3 |  ✴  |  ✴  |  ✔  |  ✔  |  ✔  |
+| To 0.4 |  ✴  |  ✴  |  ✔  |  ✔  |  ✔  |
+| To 1.0 |  ✴  |  ✴  |  ✔  |  ✔  |  ✔  |
+
+Key:
+> ✔ : lossless conversion <br>
+> ✴ : higher-version output may have empty fields <br>
+> x : lower-version output is missing some data <br>
+
+
+
+A container runtime should use `current.NewResultFromResult()` to convert the
+opaque  `types.Result` to a concrete `current.Result` struct.  It may then
+work with the fields exposed by that struct:
+
+```go
+// runtime invokes the plugin to get the opaque types.Result
+// this may conform to any CNI spec version
+resultInterface, err := libcni.AddNetwork(ctx, netConf, runtimeConf)
+
+// upconvert result to the current 0.3.0 spec
+result, err := current.NewResultFromResult(resultInterface)
+
+// use the result fields ....
+for _, ip := range result.IPs { ... }
+```

Documentation/tuning.md

@@ -1,36 +0,0 @@
-# tuning plugin
-
-## Overview
-
-This plugin can change some system controls (sysctls) in the network namespace.
-It does not create any network interfaces and therefore does not bring connectivity by itself.
-It is only useful when used in addition to other plugins.
-
-## Operation
-The following network configuration file
-```
-{
-  "name": "mytuning",
-  "type": "tuning",
-  "sysctl": {
-          "net.core.somaxconn": "500"
-  }
-}
-```
-will set /proc/sys/net/core/somaxconn to 500.
-Other sysctls can be modified as long as they belong to the network namespace (`/proc/sys/net/*`).
-
-A successful result would simply be:
-```
-{
-  "cniVersion": "0.1.0"
-}
-```
-
-## Network sysctls documentation
-
-Some network sysctls are documented in the Linux sources:
-
-- [Documentation/sysctl/net.txt](https://www.kernel.org/doc/Documentation/sysctl/net.txt)
-- [Documentation/networking/ip-sysctl.txt](https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt)
-- [Documentation/networking/](https://www.kernel.org/doc/Documentation/networking/)

GOVERNANCE.md

@@ -0,0 +1,44 @@
+# CNI Governance
+
+This document defines project governance for the project.
+
+## Voting
+
+The CNI project employs "organization voting" to ensure no single organization can dominate the project.
+
+Individuals not associated with or employed by a company or organization are allowed one organization vote.
+Each company or organization (regardless of the number of maintainers associated with or employed by that company/organization) receives one organization vote.
+
+In other words, if two maintainers are employed by Company X, two by Company Y, two by Company Z, and one maintainer is an un-affiliated individual, a total of four "organization votes" are possible; one for X, one for Y, one for Z, and one for the un-affiliated individual.
+
+Any maintainer from an organization may cast the vote for that organization.
+
+For formal votes, a specific statement of what is being voted on should be added to the relevant github issue or PR, and a link to that issue or PR added to the maintainers meeting agenda document.
+Maintainers should indicate their yes/no vote on that issue or PR, and after a suitable period of time, the votes will be tallied and the outcome noted.
+
+## Changes in Maintainership
+
+New maintainers are proposed by an existing maintainer and are elected by a 2/3 majority organization vote.
+
+Maintainers can be removed by a 2/3 majority organization vote.
+
+## Approving PRs
+
+Non-specification-related PRs may be merged after receiving at least two organization votes.
+
+Changes to the CNI Specification also follow the normal PR approval process (eg, 2 organization votes), but any maintainer can request that the approval require a 2/3 majority organization vote.
+
+## Github Project Administration
+
+Maintainers will be added to the containernetworking GitHub organization and added to the GitHub cni-maintainers team, and made a GitHub maintainer of that team.
+
+After 6 months a maintainer will be made an "owner" of the GitHub organization.
+
+## Changes in Governance
+
+All changes in Governance require a 2/3 majority organization vote.
+
+## Other Changes
+
+Unless specified above, all other changes to the project require a 2/3 majority organization vote.
+Additionally, any maintainer may request that any change require a 2/3 majority organization vote.

Godeps/Godeps.json

@@ -1,184 +0,0 @@
-{
-	"ImportPath": "github.com/containernetworking/cni",
-	"GoVersion": "go1.6",
-	"Packages": [
-		"./..."
-	],
-	"Deps": [
-		{
-			"ImportPath": "github.com/coreos/go-iptables/iptables",
-			"Comment": "v0.1.0",
-			"Rev": "fbb73372b87f6e89951c2b6b31470c2c9d5cfae3"
-		},
-		{
-			"ImportPath": "github.com/coreos/go-systemd/activation",
-			"Comment": "v2-53-g2688e91",
-			"Rev": "2688e91251d9d8e404e86dd8f096e23b2f086958"
-		},
-		{
-			"ImportPath": "github.com/d2g/dhcp4",
-			"Rev": "f0e4d29ff0231dce36e250b2ed9ff08412584bca"
-		},
-		{
-			"ImportPath": "github.com/d2g/dhcp4client",
-			"Rev": "bed07e1bc5b85f69c6f0fd73393aa35ec68ed892"
-		},
-		{
-			"ImportPath": "github.com/onsi/ginkgo",
-			"Comment": "v1.2.0-29-g7f8ab55",
-			"Rev": "7f8ab55aaf3b86885aa55b762e803744d1674700"
-		},
-		{
-			"ImportPath": "github.com/onsi/ginkgo/config",
-			"Comment": "v1.2.0-29-g7f8ab55",
-			"Rev": "7f8ab55aaf3b86885aa55b762e803744d1674700"
-		},
-		{
-			"ImportPath": "github.com/onsi/ginkgo/internal/codelocation",
-			"Comment": "v1.2.0-29-g7f8ab55",
-			"Rev": "7f8ab55aaf3b86885aa55b762e803744d1674700"
-		},
-		{
-			"ImportPath": "github.com/onsi/ginkgo/internal/containernode",
-			"Comment": "v1.2.0-29-g7f8ab55",
-			"Rev": "7f8ab55aaf3b86885aa55b762e803744d1674700"
-		},
-		{
-			"ImportPath": "github.com/onsi/ginkgo/internal/failer",
-			"Comment": "v1.2.0-29-g7f8ab55",
-			"Rev": "7f8ab55aaf3b86885aa55b762e803744d1674700"
-		},
-		{
-			"ImportPath": "github.com/onsi/ginkgo/internal/leafnodes",
-			"Comment": "v1.2.0-29-g7f8ab55",
-			"Rev": "7f8ab55aaf3b86885aa55b762e803744d1674700"
-		},
-		{
-			"ImportPath": "github.com/onsi/ginkgo/internal/remote",
-			"Comment": "v1.2.0-29-g7f8ab55",
-			"Rev": "7f8ab55aaf3b86885aa55b762e803744d1674700"
-		},
-		{
-			"ImportPath": "github.com/onsi/ginkgo/internal/spec",
-			"Comment": "v1.2.0-29-g7f8ab55",
-			"Rev": "7f8ab55aaf3b86885aa55b762e803744d1674700"
-		},
-		{
-			"ImportPath": "github.com/onsi/ginkgo/internal/specrunner",
-			"Comment": "v1.2.0-29-g7f8ab55",
-			"Rev": "7f8ab55aaf3b86885aa55b762e803744d1674700"
-		},
-		{
-			"ImportPath": "github.com/onsi/ginkgo/internal/suite",
-			"Comment": "v1.2.0-29-g7f8ab55",
-			"Rev": "7f8ab55aaf3b86885aa55b762e803744d1674700"
-		},
-		{
-			"ImportPath": "github.com/onsi/ginkgo/internal/testingtproxy",
-			"Comment": "v1.2.0-29-g7f8ab55",
-			"Rev": "7f8ab55aaf3b86885aa55b762e803744d1674700"
-		},
-		{
-			"ImportPath": "github.com/onsi/ginkgo/internal/writer",
-			"Comment": "v1.2.0-29-g7f8ab55",
-			"Rev": "7f8ab55aaf3b86885aa55b762e803744d1674700"
-		},
-		{
-			"ImportPath": "github.com/onsi/ginkgo/reporters",
-			"Comment": "v1.2.0-29-g7f8ab55",
-			"Rev": "7f8ab55aaf3b86885aa55b762e803744d1674700"
-		},
-		{
-			"ImportPath": "github.com/onsi/ginkgo/reporters/stenographer",
-			"Comment": "v1.2.0-29-g7f8ab55",
-			"Rev": "7f8ab55aaf3b86885aa55b762e803744d1674700"
-		},
-		{
-			"ImportPath": "github.com/onsi/ginkgo/types",
-			"Comment": "v1.2.0-29-g7f8ab55",
-			"Rev": "7f8ab55aaf3b86885aa55b762e803744d1674700"
-		},
-		{
-			"ImportPath": "github.com/onsi/gomega",
-			"Comment": "v1.0-71-g2152b45",
-			"Rev": "2152b45fa28a361beba9aab0885972323a444e28"
-		},
-		{
-			"ImportPath": "github.com/onsi/gomega/format",
-			"Comment": "v1.0-71-g2152b45",
-			"Rev": "2152b45fa28a361beba9aab0885972323a444e28"
-		},
-		{
-			"ImportPath": "github.com/onsi/gomega/gbytes",
-			"Comment": "v1.0-71-g2152b45",
-			"Rev": "2152b45fa28a361beba9aab0885972323a444e28"
-		},
-		{
-			"ImportPath": "github.com/onsi/gomega/gexec",
-			"Comment": "v1.0-71-g2152b45",
-			"Rev": "2152b45fa28a361beba9aab0885972323a444e28"
-		},
-		{
-			"ImportPath": "github.com/onsi/gomega/internal/assertion",
-			"Comment": "v1.0-71-g2152b45",
-			"Rev": "2152b45fa28a361beba9aab0885972323a444e28"
-		},
-		{
-			"ImportPath": "github.com/onsi/gomega/internal/asyncassertion",
-			"Comment": "v1.0-71-g2152b45",
-			"Rev": "2152b45fa28a361beba9aab0885972323a444e28"
-		},
-		{
-			"ImportPath": "github.com/onsi/gomega/internal/oraclematcher",
-			"Comment": "v1.0-71-g2152b45",
-			"Rev": "2152b45fa28a361beba9aab0885972323a444e28"
-		},
-		{
-			"ImportPath": "github.com/onsi/gomega/internal/testingtsupport",
-			"Comment": "v1.0-71-g2152b45",
-			"Rev": "2152b45fa28a361beba9aab0885972323a444e28"
-		},
-		{
-			"ImportPath": "github.com/onsi/gomega/matchers",
-			"Comment": "v1.0-71-g2152b45",
-			"Rev": "2152b45fa28a361beba9aab0885972323a444e28"
-		},
-		{
-			"ImportPath": "github.com/onsi/gomega/matchers/support/goraph/bipartitegraph",
-			"Comment": "v1.0-71-g2152b45",
-			"Rev": "2152b45fa28a361beba9aab0885972323a444e28"
-		},
-		{
-			"ImportPath": "github.com/onsi/gomega/matchers/support/goraph/edge",
-			"Comment": "v1.0-71-g2152b45",
-			"Rev": "2152b45fa28a361beba9aab0885972323a444e28"
-		},
-		{
-			"ImportPath": "github.com/onsi/gomega/matchers/support/goraph/node",
-			"Comment": "v1.0-71-g2152b45",
-			"Rev": "2152b45fa28a361beba9aab0885972323a444e28"
-		},
-		{
-			"ImportPath": "github.com/onsi/gomega/matchers/support/goraph/util",
-			"Comment": "v1.0-71-g2152b45",
-			"Rev": "2152b45fa28a361beba9aab0885972323a444e28"
-		},
-		{
-			"ImportPath": "github.com/onsi/gomega/types",
-			"Comment": "v1.0-71-g2152b45",
-			"Rev": "2152b45fa28a361beba9aab0885972323a444e28"
-		},
-		{
-			"ImportPath": "github.com/vishvananda/netlink",
-			"Rev": "ecf47fd5739b3d2c3daf7c89c4b9715a2605c21b"
-		},
-		{
-			"ImportPath": "github.com/vishvananda/netlink/nl",
-			"Rev": "ecf47fd5739b3d2c3daf7c89c4b9715a2605c21b"
-		},
-		{
-			"ImportPath": "golang.org/x/sys/unix",
-			"Rev": "e11762ca30adc5b39fdbfd8c4250dabeb8e456d3"
-		}
-	]
-}

Godeps/Readme

@@ -1,5 +0,0 @@
-This directory tree is generated automatically by godep.
-
-Please do not edit.
-
-See https://github.com/tools/godep for more information.

MAINTAINERS

@@ -1,5 +1,14 @@
-Gabe Rosenhouse <grosenhouse@pivotal.io> (@rosenhouse)
-Michael Bridgen <michael@weave.works> (@squaremo)
-Stefan Junker <stefan.junker@coreos.com> (@steveeJ)
-Tom Denham <tom.denham@metaswitch.com> (@tomdee)
-Zach Gershman <zachgersh@gmail.com> (@zachgersh)
+Bruce Ma <brucema19901024@gmail.com> (@mars1024)
+Casey Callendrello <cdc@isovalent.com> (@squeed)
+Michael Cambria <mcambria@redhat.com> (@mccv1r0)
+Michael Zappa <Michael.Zappa@gmail.com> (@MikeZappa87)
+Tomofumi Hayashi <s1061123@gmail.com> (@s1061123)
+Lionel Jouin <lionel.jouin@est.tech> (@LionelJouin)
+Ben Leggett <benjamin@edera.dev> (@bleggett)
+Marcelo Guerrero <guerrero.viveros@gmail.com> (@mlguerrero12)
+Doug Smith <douglas.kipp.smith@gmail.com> (@dougbtv)
+
+Emeritus:
+Dan Williams <dcbw@redhat.com> (@dcbw)
+Matt Dupre <matt@tigera.io> (@matthewdupre)
+Piotr Skamruk <piotr.skamruk@gmail.com> (@jellonek)

Makefile

@@ -0,0 +1 @@
+include mk/lint.mk

README.md

@@ -1,19 +1,36 @@
-[![Build Status](https://travis-ci.org/containernetworking/cni.svg?branch=master)](https://travis-ci.org/containernetworking/cni)
-[![Coverage Status](https://coveralls.io/repos/github/containernetworking/cni/badge.svg?branch=master)](https://coveralls.io/github/containernetworking/cni?branch=master)
+![CNI Logo](logo.png)
+
+---
 
 # CNI - the Container Network Interface
 
+[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/2446/badge)](https://bestpractices.coreinfrastructure.org/projects/2446)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/containernetworking/cni/badge)](https://securityscorecards.dev/viewer/?uri=github.com/containernetworking/cni)
+
 ## What is CNI?
 
-The CNI (_Container Network Interface_) project consists of a specification and libraries for writing plugins to configure network interfaces in Linux containers, along with a number of supported plugins.
+CNI (_Container Network Interface_), a [Cloud Native Computing Foundation](https://cncf.io) project, consists of a specification and libraries for writing plugins to configure network interfaces in Linux containers, along with a number of supported plugins.
 CNI concerns itself only with network connectivity of containers and removing allocated resources when the container is deleted.
-Because of this focus CNI has a wide range of support and the specification is simple to implement.
+Because of this focus, CNI has a wide range of support and the specification is simple to implement.
 
-As well as the [specification](SPEC.md), this repository contains the Go source code of a library for integrating CNI into applications, an example command-line tool, a template for making new plugins, and the supported plugins.
+As well as the [specification](SPEC.md), this repository contains the Go source code of a [library for integrating CNI into applications](libcni) and an [example command-line tool](cnitool) for executing CNI plugins.  A [separate repository contains reference plugins](https://github.com/containernetworking/plugins) and a template for making new plugins.
 
 The template code makes it straight-forward to create a CNI plugin for an existing container networking project.
 CNI also makes a good framework for creating a new container networking project from scratch.
 
+Here are the recordings of two sessions that the CNI maintainers hosted at KubeCon/CloudNativeCon 2019:
+
+- [Introduction to CNI](https://youtu.be/YjjrQiJOyME)
+- [CNI deep dive](https://youtu.be/zChkx-AB5Xc)
+
+
+## Contributing to CNI
+
+We welcome contributions, including [bug reports](https://github.com/containernetworking/cni/issues), and code and documentation improvements.
+If you intend to contribute to code or documentation, please read [CONTRIBUTING.md](CONTRIBUTING.md). Also see the [contact section](#contact) in this README.
+
+The CNI project has a [weekly meeting](https://meet.jit.si/CNIMaintainersMeeting). It takes place Mondays at 11:00 US/Eastern. All are welcome to join.
+
 ## Why develop CNI?
 
 Application containers on Linux are a rapidly evolving area, and within this area networking is not well addressed as it is highly environment-specific.
@@ -22,37 +39,59 @@ We believe that many container runtimes and orchestrators will seek to solve the
 To avoid duplication, we think it is prudent to define a common interface between the network plugins and container execution: hence we put forward this specification, along with libraries for Go and a set of plugins.
 
 ## Who is using CNI?
+### Container runtimes
+- [Kubernetes - a system to simplify container operations](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/)
+- [OpenShift - Kubernetes with additional enterprise features](https://github.com/openshift/origin/blob/master/docs/openshift_networking_requirements.md)
+- [Cloud Foundry - a platform for cloud applications](https://github.com/cloudfoundry-incubator/cf-networking-release)
+- [Apache Mesos - a distributed systems kernel](https://github.com/apache/mesos/blob/master/docs/cni.md)
+- [Amazon ECS - a highly scalable, high performance container management service](https://aws.amazon.com/ecs/)
+- [Singularity - container platform optimized for HPC, EPC, and AI](https://github.com/sylabs/singularity)
+- [OpenSVC - orchestrator for legacy and containerized application stacks](https://docs.opensvc.com/latest/fr/agent.configure.cni.html)
 
-- [rkt - container engine](https://coreos.com/blog/rkt-cni-networking.html)
-- [Kurma - container runtime](http://kurma.io/)
-- [Kubernetes - a system to simplify container operations](http://kubernetes.io/docs/admin/network-plugins/)
-- [Cloud Foundry - a platform for cloud applications](https://github.com/cloudfoundry-incubator/guardian-cni-adapter)
-- [Weave - a multi-host Docker network](https://github.com/weaveworks/weave)
-- [Project Calico - a layer 3 virtual network](https://github.com/projectcalico/calico-cni)
+### 3rd party plugins
+- [Project Calico - a layer 3 virtual network](https://github.com/projectcalico/calico)
 - [Contiv Networking - policy networking for various use cases](https://github.com/contiv/netplugin)
+- [SR-IOV](https://github.com/hustcat/sriov-cni)
+- [Cilium - eBPF & XDP for containers](https://github.com/cilium/cilium)
+- [Multus - a Multi plugin](https://github.com/k8snetworkplumbingwg/multus-cni)
+- [Romana - Layer 3 CNI plugin supporting network policy for Kubernetes](https://github.com/romana/kube)
+- [CNI-Genie - generic CNI network plugin](https://github.com/Huawei-PaaS/CNI-Genie)
+- [Nuage CNI - Nuage Networks SDN plugin for network policy kubernetes support ](https://github.com/nuagenetworks/nuage-cni)
+- [Linen - a CNI plugin designed for overlay networks with Open vSwitch and fit in SDN/OpenFlow network environment](https://github.com/John-Lin/linen-cni)
+- [Vhostuser - a Dataplane network plugin - Supports OVS-DPDK & VPP](https://github.com/intel/vhost-user-net-plugin)
+- [Amazon ECS CNI Plugins - a collection of CNI Plugins to configure containers with Amazon EC2 elastic network interfaces (ENIs)](https://github.com/aws/amazon-ecs-cni-plugins)
+- [Bonding CNI - a Link aggregating plugin to address failover and high availability network](https://github.com/Intel-Corp/bond-cni)
+- [ovn-kubernetes - an container network plugin built on Open vSwitch (OVS) and Open Virtual Networking (OVN) with support for both Linux and Windows](https://github.com/openvswitch/ovn-kubernetes)
+- [Juniper Contrail](https://www.juniper.net/cloud) / [TungstenFabric](https://tungstenfabric.io) -  Provides overlay SDN solution, delivering multicloud networking, hybrid cloud networking, simultaneous overlay-underlay support, network policy enforcement, network isolation, service chaining and flexible load balancing
+- [Knitter - a CNI plugin supporting multiple networking for Kubernetes](https://github.com/ZTE/Knitter)
+- [DANM - a CNI-compliant networking solution for TelCo workloads running on Kubernetes](https://github.com/nokia/danm)
+- [cni-route-override - a meta CNI plugin that override route information](https://github.com/redhat-nfvpe/cni-route-override)
+- [Terway - a collection of CNI Plugins based on alibaba cloud VPC/ECS network product](https://github.com/AliyunContainerService/terway)
+- [Cisco ACI CNI - for on-prem and cloud container networking with consistent policy and security model.](https://github.com/noironetworks/aci-containers)
+- [Kube-OVN - a CNI plugin that bases on OVN/OVS and provides advanced features like subnet, static ip, ACL, QoS, etc.](https://github.com/kubeovn/kube-ovn)
+- [Project Antrea - an Open vSwitch k8s CNI](https://github.com/vmware-tanzu/antrea)
+- [Azure CNI - a CNI plugin that natively extends Azure Virtual Networks to containers](https://github.com/Azure/azure-container-networking)
+- [Hybridnet - a CNI plugin designed for hybrid clouds which provides both overlay and underlay networking for containers in one or more clusters. Overlay and underlay containers can run on the same node and have cluster-wide bidirectional network connectivity.](https://github.com/alibaba/hybridnet)
+- [Spiderpool - An IP Address Management (IPAM) CNI plugin of Kubernetes for managing static ip for underlay network](https://github.com/spidernet-io/spiderpool)
+- [AWS VPC CNI - Networking plugin for pod networking in Kubernetes using Elastic Network Interfaces on AWS](https://github.com/aws/amazon-vpc-cni-k8s)
 
-## Contributing to CNI
+The CNI team also maintains some [core plugins in a separate repository](https://github.com/containernetworking/plugins).
 
-We welcome contributions, including [bug reports](https://github.com/containernetworking/cni/issues), and code and documentation improvements.
-If you intend to contribute to code or documentation, please read [CONTRIBUTING.md](CONTRIBUTING.md). Also see the [contact section](#contact) in this README.
 
 ## How do I use CNI?
 
 ### Requirements
 
-CNI requires Go 1.5+ to build.
+The CNI spec is language agnostic.  To use the Go language libraries in this repository, you'll need a recent version of Go.  You can find the Go versions covered by our [automated tests](https://travis-ci.org/containernetworking/cni/builds) in [.travis.yaml](.travis.yml).
 
-Go 1.5 users will need to set GO15VENDOREXPERIMENT=1 to get vendored
-dependencies. This flag is set by default in 1.6.
+### Reference Plugins
 
-### Included Plugins
-
-This repository includes a number of common plugins in the `plugins/` directory.
-Please see the [Documentation/](Documentation/) directory for documentation about particular plugins.
+The CNI project maintains a set of [reference plugins](https://github.com/containernetworking/plugins) that implement the CNI specification.
+NOTE: the reference plugins used to live in this repository but have been split out into a [separate repository](https://github.com/containernetworking/plugins) as of May 2017.
 
 ### Running the plugins
 
-The scripts/ directory contains two scripts, `priv-net-run.sh` and `docker-run.sh`, that can be used to exercise the plugins.
+After building and installing the [reference plugins](https://github.com/containernetworking/plugins), you can use the `priv-net-run.sh` and `docker-run.sh` scripts in the `scripts/` directory to exercise the plugins.
 
 **note - priv-net-run.sh depends on `jq`**
 
@@ -62,6 +101,7 @@ Start out by creating a netconf file to describe a network:
 $ mkdir -p /etc/cni/net.d
 $ cat >/etc/cni/net.d/10-mynet.conf <<EOF
 {
+	"cniVersion": "0.2.0",
 	"name": "mynet",
 	"type": "bridge",
 	"bridge": "cni0",
@@ -78,6 +118,8 @@ $ cat >/etc/cni/net.d/10-mynet.conf <<EOF
 EOF
 $ cat >/etc/cni/net.d/99-loopback.conf <<EOF
 {
+	"cniVersion": "0.2.0",
+	"name": "lo",
 	"type": "loopback"
 }
 EOF
@@ -88,14 +130,15 @@ The directory `/etc/cni/net.d` is the default location in which the scripts will
 Next, build the plugins:
 
 ```bash
-$ ./build
+$ cd $GOPATH/src/github.com/containernetworking/plugins
+$ ./build_linux.sh # or build_windows.sh
 ```
 
 Finally, execute a command (`ifconfig` in this example) in a private network namespace that has joined the `mynet` network:
 
 ```bash
-$ CNI_PATH=`pwd`/bin
-$ cd scripts
+$ CNI_PATH=$GOPATH/src/github.com/containernetworking/plugins/bin
+$ cd $GOPATH/src/github.com/containernetworking/cni/scripts
 $ sudo CNI_PATH=$CNI_PATH ./priv-net-run.sh ifconfig
 eth0      Link encap:Ethernet  HWaddr f2:c2:6f:54:b8:2b  
           inet addr:10.22.0.2  Bcast:0.0.0.0  Mask:255.255.0.0
@@ -103,7 +146,7 @@ eth0      Link encap:Ethernet  HWaddr f2:c2:6f:54:b8:2b
           UP BROADCAST MULTICAST  MTU:1500  Metric:1
           RX packets:1 errors:0 dropped:0 overruns:0 frame:0
           TX packets:0 errors:0 dropped:1 overruns:0 carrier:0
-          collisions:0 txqueuelen:0 
+          collisions:0 txqueuelen:0
           RX bytes:90 (90.0 B)  TX bytes:0 (0.0 B)
 
 lo        Link encap:Local Loopback  
@@ -112,7 +155,7 @@ lo        Link encap:Local Loopback
           UP LOOPBACK RUNNING  MTU:65536  Metric:1
           RX packets:0 errors:0 dropped:0 overruns:0 frame:0
           TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
-          collisions:0 txqueuelen:0 
+          collisions:0 txqueuelen:0
           RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)
 ```
 
@@ -124,8 +167,8 @@ Use the instructions in the previous section to define a netconf and build the p
 Next, docker-run.sh script wraps `docker run`, to execute the plugins prior to entering the container:
 
 ```bash
-$ CNI_PATH=`pwd`/bin
-$ cd scripts
+$ CNI_PATH=$GOPATH/src/github.com/containernetworking/plugins/bin
+$ cd $GOPATH/src/github.com/containernetworking/cni/scripts
 $ sudo CNI_PATH=$CNI_PATH ./docker-run.sh --rm busybox:latest ifconfig
 eth0      Link encap:Ethernet  HWaddr fa:60:70:aa:07:d1  
           inet addr:10.22.0.2  Bcast:0.0.0.0  Mask:255.255.0.0
@@ -133,7 +176,7 @@ eth0      Link encap:Ethernet  HWaddr fa:60:70:aa:07:d1
           UP BROADCAST MULTICAST  MTU:1500  Metric:1
           RX packets:1 errors:0 dropped:0 overruns:0 frame:0
           TX packets:0 errors:0 dropped:1 overruns:0 carrier:0
-          collisions:0 txqueuelen:0 
+          collisions:0 txqueuelen:0
           RX bytes:90 (90.0 B)  TX bytes:0 (0.0 B)
 
 lo        Link encap:Local Loopback  
@@ -142,22 +185,36 @@ lo        Link encap:Local Loopback
           UP LOOPBACK RUNNING  MTU:65536  Metric:1
           RX packets:0 errors:0 dropped:0 overruns:0 frame:0
           TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
-          collisions:0 txqueuelen:0 
+          collisions:0 txqueuelen:0
           RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)
 ```
 
 ## What might CNI do in the future?
 
-CNI currently covers a wide range of needs for network configuration due to it simple model and API.
+CNI currently covers a wide range of needs for network configuration due to its simple model and API.
 However, in the future CNI might want to branch out into other directions:
 
 - Dynamic updates to existing network configuration
 - Dynamic policies for network bandwidth and firewall rules
 
-If these topics of are interest please contact the team via the mailing list or IRC and find some like minded people in the community to put a proposal together.
+If these topics are of interest, please contact the team via the mailing list or IRC and find some like-minded people in the community to put a proposal together.
+
+## Where are the binaries?
+
+The plugins moved to a separate repo:
+https://github.com/containernetworking/plugins, and the releases there
+include binaries and checksums.
+
+Prior to release 0.7.0 the `cni` release also included a `cnitool`
+binary; as this is a developer tool we suggest you build it yourself.
 
 ## Contact
 
-For any questions about CNI, please reach out on the mailing list:
+For any questions about CNI, please reach out via:
 - Email: [cni-dev](https://groups.google.com/forum/#!forum/cni-dev)
-- IRC: #[containernetworking](irc://irc.freenode.org:6667/#containernetworking) channel on freenode.org
+- IRC: #[containernetworking](irc://irc.freenode.net:6667/#containernetworking) channel on [freenode.net](https://freenode.net/)
+- Slack: #cni on the [CNCF slack](https://slack.cncf.io/).  NOTE: the previous CNI Slack (containernetworking.slack.com) has been sunsetted.
+
+## Security
+
+If you have a _security_ issue to report, please do so privately to the email addresses listed in the [MAINTAINERS](MAINTAINERS) file.

RELEASING.md

@@ -0,0 +1,19 @@
+# Release process
+## Preparing for a release
+
+Releases are performed by maintainers and should usually be discussed and planned at a maintainer meeting.
+
+- Choose the version number. It should be prefixed with `v`, e.g. `v1.2.3`
+- Take a quick scan through the PRs and issues to make sure there isn't anything crucial that _must_ be in the next release.
+- Create a draft of the release note
+- Discuss the level of testing that's needed and create a test plan if sensible
+- Check what version of `go` is used in the build container, updating it if there's a new stable release.
+
+## Publishing the release
+
+1. Make sure you are on the master branch and don't have any local uncommitted changes.
+1. Create a signed tag for the release `git tag -s $VERSION` (Ensure that GPG keys are created and added to GitHub)
+1. Push the tag to git `git push origin <TAG>`
+1. Create a release on Github, using the tag which was just pushed.
+1. Add the release note to the release.
+1. Announce the release on at least the CNI mailing, IRC and Slack.

ROADMAP.md

@@ -0,0 +1,18 @@
+# CNI Roadmap
+
+This document defines a high level roadmap for CNI development.
+The list below is not complete, and we advise to get the current project state from the [milestones defined in GitHub](https://github.com/containernetworking/cni/milestones).
+
+## CNI Milestones
+
+### [v1.0.0](https://github.com/containernetworking/cni/milestones/v1.0.0)
+
+- Targeted for April 2020
+- More precise specification language
+- Stable SPEC
+- Complete test coverage
+
+### Beyond v1.0.0
+
+- Conformance test suite for CNI plugins (both reference and 3rd party)
+- Signed release binaries

build

@@ -1,30 +0,0 @@
-#!/usr/bin/env bash
-set -e
-
-ORG_PATH="github.com/containernetworking"
-REPO_PATH="${ORG_PATH}/cni"
-
-if [ ! -h gopath/src/${REPO_PATH} ]; then
-	mkdir -p gopath/src/${ORG_PATH}
-	ln -s ../../../.. gopath/src/${REPO_PATH} || exit 255
-fi
-
-export GO15VENDOREXPERIMENT=1
-export GOBIN=${PWD}/bin
-export GOPATH=${PWD}/gopath
-
-echo "Building API"
-go build "$@" ${REPO_PATH}/libcni
-
-echo "Building reference CLI"
-go install "$@" ${REPO_PATH}/cnitool
-
-echo "Building plugins"
-PLUGINS="plugins/meta/* plugins/main/* plugins/ipam/*"
-for d in $PLUGINS; do
-	if [ -d $d ]; then
-		plugin=$(basename $d)
-		echo "  " $plugin
-		go install "$@" ${REPO_PATH}/$d
-	fi
-done

cnitool/README.md

@@ -0,0 +1,77 @@
+# cnitool
+
+`cnitool` is a simple program that executes a CNI configuration. It will
+add or remove an interface in an already-created network namespace.
+
+## Environment Variables
+
+* `NETCONFPATH`: This environment variable needs to be set to a
+  directory. It defaults to `/etc/cni/net.d`. The `cnitool` searches
+  for CNI configuration files in this directory according to the following priorities:
+  1. Search files with the extension `*.conflist`, representing a list of plugin configurations.
+  2. If there are no `*.conflist` files in the directory, search files with the extension `*.conf` or `*.json`, 
+  representing a single plugin configuration.
+  
+  It loads all the CNI configuration files in
+  this directory and if it finds a CNI configuration with the `network
+  name` given to the cnitool it returns the corresponding CNI
+  configuration, else it returns `nil`.
+* `CNI_PATH`: For a given CNI configuration `cnitool` will search for
+  the corresponding CNI plugin in this path.
+
+## Example invocation
+
+First, install cnitool:
+
+```bash
+go get github.com/containernetworking/cni
+go install github.com/containernetworking/cni/cnitool
+```
+
+Then, check out and build the plugins. All commands should be run from this directory.
+
+```bash
+git clone https://github.com/containernetworking/plugins.git
+cd plugins
+./build_linux.sh
+# or
+./build_windows.sh
+```
+
+Create a network configuration
+
+```bash
+echo '{"cniVersion":"0.4.0","name":"myptp","type":"ptp","ipMasq":true,"ipam":{"type":"host-local","subnet":"172.16.29.0/24","routes":[{"dst":"0.0.0.0/0"}]}}' | sudo tee /etc/cni/net.d/10-myptp.conf
+```
+
+Create a network namespace. This will be called `testing`:
+
+```bash
+sudo ip netns add testing
+```
+
+Add the container to the network:
+
+```bash
+sudo CNI_PATH=./bin cnitool add myptp /var/run/netns/testing
+```
+
+Check whether the container's networking is as expected (ONLY for spec v0.4.0+):
+
+```bash
+sudo CNI_PATH=./bin cnitool check myptp /var/run/netns/testing
+```
+
+Test that it works:
+
+```bash
+sudo ip -n testing addr
+sudo ip netns exec testing ping -c 1 4.2.2.2
+```
+
+And clean up:
+
+```bash
+sudo CNI_PATH=./bin cnitool del myptp /var/run/netns/testing
+sudo ip netns del testing
+```

cnitool/cni.go

@@ -1,87 +0,0 @@
-// Copyright 2015 CoreOS, Inc.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package main
-
-import (
-	"fmt"
-	"os"
-	"path/filepath"
-	"strings"
-
-	"github.com/containernetworking/cni/libcni"
-)
-
-const (
-	EnvCNIPath = "CNI_PATH"
-	EnvNetDir  = "NETCONFPATH"
-
-	DefaultNetDir = "/etc/cni/net.d"
-
-	CmdAdd = "add"
-	CmdDel = "del"
-)
-
-func main() {
-	if len(os.Args) < 3 {
-		usage()
-		return
-	}
-
-	netdir := os.Getenv(EnvNetDir)
-	if netdir == "" {
-		netdir = DefaultNetDir
-	}
-	netconf, err := libcni.LoadConf(netdir, os.Args[2])
-	if err != nil {
-		exit(err)
-	}
-
-	netns := os.Args[3]
-
-	cninet := &libcni.CNIConfig{
-		Path: strings.Split(os.Getenv(EnvCNIPath), ":"),
-	}
-
-	rt := &libcni.RuntimeConf{
-		ContainerID: "cni",
-		NetNS:       netns,
-		IfName:      "eth0",
-	}
-
-	switch os.Args[1] {
-	case CmdAdd:
-		_, err := cninet.AddNetwork(netconf, rt)
-		exit(err)
-	case CmdDel:
-		exit(cninet.DelNetwork(netconf, rt))
-	}
-}
-
-func usage() {
-	exe := filepath.Base(os.Args[0])
-
-	fmt.Fprintf(os.Stderr, "%s: Add or remove network interfaces from a network namespace\n", exe)
-	fmt.Fprintf(os.Stderr, "  %s %s <net> <netns>\n", exe, CmdAdd)
-	fmt.Fprintf(os.Stderr, "  %s %s <net> <netns>\n", exe, CmdDel)
-	os.Exit(1)
-}
-
-func exit(err error) {
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "%s\n", err)
-		os.Exit(1)
-	}
-	os.Exit(0)
-}

cnitool/cnitool.go

@@ -0,0 +1,156 @@
+// Copyright 2015 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"context"
+	"crypto/sha512"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/containernetworking/cni/libcni"
+)
+
+// Protocol parameters are passed to the plugins via OS environment variables.
+const (
+	EnvCNIPath        = "CNI_PATH"
+	EnvNetDir         = "NETCONFPATH"
+	EnvCapabilityArgs = "CAP_ARGS"
+	EnvCNIArgs        = "CNI_ARGS"
+	EnvCNIIfname      = "CNI_IFNAME"
+
+	DefaultNetDir = "/etc/cni/net.d"
+
+	CmdAdd    = "add"
+	CmdCheck  = "check"
+	CmdDel    = "del"
+	CmdGC     = "gc"
+	CmdStatus = "status"
+)
+
+func parseArgs(args string) ([][2]string, error) {
+	var result [][2]string
+
+	pairs := strings.Split(args, ";")
+	for _, pair := range pairs {
+		kv := strings.Split(pair, "=")
+		if len(kv) != 2 || kv[0] == "" || kv[1] == "" {
+			return nil, fmt.Errorf("invalid CNI_ARGS pair %q", pair)
+		}
+
+		result = append(result, [2]string{kv[0], kv[1]})
+	}
+
+	return result, nil
+}
+
+func main() {
+	if len(os.Args) < 4 {
+		usage()
+	}
+
+	netdir := os.Getenv(EnvNetDir)
+	if netdir == "" {
+		netdir = DefaultNetDir
+	}
+	netconf, err := libcni.LoadNetworkConf(netdir, os.Args[2])
+	if err != nil {
+		exit(err)
+	}
+
+	var capabilityArgs map[string]interface{}
+	capabilityArgsValue := os.Getenv(EnvCapabilityArgs)
+	if len(capabilityArgsValue) > 0 {
+		if err = json.Unmarshal([]byte(capabilityArgsValue), &capabilityArgs); err != nil {
+			exit(err)
+		}
+	}
+
+	var cniArgs [][2]string
+	args := os.Getenv(EnvCNIArgs)
+	if len(args) > 0 {
+		cniArgs, err = parseArgs(args)
+		if err != nil {
+			exit(err)
+		}
+	}
+
+	ifName, ok := os.LookupEnv(EnvCNIIfname)
+	if !ok {
+		ifName = "eth0"
+	}
+
+	netns := os.Args[3]
+	netns, err = filepath.Abs(netns)
+	if err != nil {
+		exit(err)
+	}
+
+	// Generate the containerid by hashing the netns path
+	s := sha512.Sum512([]byte(netns))
+	containerID := fmt.Sprintf("cnitool-%x", s[:10])
+
+	cninet := libcni.NewCNIConfig(filepath.SplitList(os.Getenv(EnvCNIPath)), nil)
+
+	rt := &libcni.RuntimeConf{
+		ContainerID:    containerID,
+		NetNS:          netns,
+		IfName:         ifName,
+		Args:           cniArgs,
+		CapabilityArgs: capabilityArgs,
+	}
+
+	switch os.Args[1] {
+	case CmdAdd:
+		result, err := cninet.AddNetworkList(context.TODO(), netconf, rt)
+		if result != nil {
+			_ = result.Print()
+		}
+		exit(err)
+	case CmdCheck:
+		err := cninet.CheckNetworkList(context.TODO(), netconf, rt)
+		exit(err)
+	case CmdDel:
+		exit(cninet.DelNetworkList(context.TODO(), netconf, rt))
+	case CmdGC:
+		// Currently just invoke GC without args, hence all network interface should be GC'ed!
+		exit(cninet.GCNetworkList(context.TODO(), netconf, nil))
+	case CmdStatus:
+		exit(cninet.GetStatusNetworkList(context.TODO(), netconf))
+	}
+}
+
+func usage() {
+	exe := filepath.Base(os.Args[0])
+
+	fmt.Fprintf(os.Stderr, "%s: Add, check, remove, gc or status network interfaces from a network namespace\n", exe)
+	fmt.Fprintf(os.Stderr, "  %s add    <net> <netns>\n", exe)
+	fmt.Fprintf(os.Stderr, "  %s check  <net> <netns>\n", exe)
+	fmt.Fprintf(os.Stderr, "  %s del    <net> <netns>\n", exe)
+	fmt.Fprintf(os.Stderr, "  %s gc     <net> <netns>\n", exe)
+	fmt.Fprintf(os.Stderr, "  %s status <net> <netns>\n", exe)
+	os.Exit(1)
+}
+
+func exit(err error) {
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "%s\n", err)
+		os.Exit(1)
+	}
+	os.Exit(0)
+}

go.mod

@@ -0,0 +1,22 @@
+module github.com/containernetworking/cni
+
+go 1.21
+
+require (
+	github.com/onsi/ginkgo/v2 v2.20.1
+	github.com/onsi/gomega v1.34.1
+	github.com/vishvananda/netns v0.0.4
+)
+
+require (
+	github.com/go-logr/logr v1.4.2 // indirect
+	github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
+	github.com/google/go-cmp v0.6.0 // indirect
+	github.com/google/pprof v0.0.0-20240727154555-813a5fbdbec8 // indirect
+	golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56 // indirect
+	golang.org/x/net v0.28.0 // indirect
+	golang.org/x/sys v0.23.0 // indirect
+	golang.org/x/text v0.17.0 // indirect
+	golang.org/x/tools v0.24.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

go.sum

@@ -0,0 +1,36 @@
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-logr/logr v1.4.2 h1:6pFjapn8bFcIbiKo3XT4j/BhANplGihG6tvd+8rYgrY=
+github.com/go-logr/logr v1.4.2/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-task/slim-sprig/v3 v3.0.0 h1:sUs3vkvUymDpBKi3qH1YSqBQk9+9D/8M2mN1vB6EwHI=
+github.com/go-task/slim-sprig/v3 v3.0.0/go.mod h1:W848ghGpv3Qj3dhTPRyJypKRiqCdHZiAzKg9hl15HA8=
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/pprof v0.0.0-20240727154555-813a5fbdbec8 h1:FKHo8hFI3A+7w0aUQuYXQ+6EN5stWmeY/AZqtM8xk9k=
+github.com/google/pprof v0.0.0-20240727154555-813a5fbdbec8/go.mod h1:K1liHPHnj73Fdn/EKuT8nrFqBihUSKXoLYU0BuatOYo=
+github.com/onsi/ginkgo/v2 v2.20.1 h1:YlVIbqct+ZmnEph770q9Q7NVAz4wwIiVNahee6JyUzo=
+github.com/onsi/ginkgo/v2 v2.20.1/go.mod h1:lG9ey2Z29hR41WMVthyJBGUBcBhGOtoPF2VFMvBXFCI=
+github.com/onsi/gomega v1.34.1 h1:EUMJIKUjM8sKjYbtxQI9A4z2o+rruxnzNvpknOXie6k=
+github.com/onsi/gomega v1.34.1/go.mod h1:kU1QgUvBDLXBJq618Xvm2LUX6rSAfRaFRTcdOeDLwwY=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+github.com/vishvananda/netns v0.0.4 h1:Oeaw1EM2JMxD51g9uhtC0D7erkIjgmj8+JZc26m1YX8=
+github.com/vishvananda/netns v0.0.4/go.mod h1:SpkAiCQRtJ6TvvxPnOSyH3BMl6unz3xZlaprSwhNNJM=
+golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56 h1:2dVuKD2vS7b0QIHQbpyTISPd0LeHDbnYEryqj5Q1ug8=
+golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56/go.mod h1:M4RDyNAINzryxdtnbRXRL/OHtkFuWGRjvuhBJpk2IlY=
+golang.org/x/net v0.28.0 h1:a9JDOJc5GMUJ0+UDqmLT86WiEy7iWyIhz8gz8E4e5hE=
+golang.org/x/net v0.28.0/go.mod h1:yqtgsTWOOnlGLG9GFRrK3++bGOUEkNBoHZc8MEDWPNg=
+golang.org/x/sys v0.23.0 h1:YfKFowiIMvtgl1UERQoTPPToxltDeZfbj4H7dVUCwmM=
+golang.org/x/sys v0.23.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/text v0.17.0 h1:XtiM5bkSOt+ewxlOE/aE/AKEHibwj/6gvWMl9Rsh0Qc=
+golang.org/x/text v0.17.0/go.mod h1:BuEKDfySbSR4drPmRPG/7iBdf8hvFMuRexcpahXilzY=
+golang.org/x/tools v0.24.0 h1:J1shsA93PJUEVaUSaay7UXAyE8aimq3GW0pjlolpa24=
+golang.org/x/tools v0.24.0/go.mod h1:YhNqVBIfWHdzvTLs0d8LCuMhkKUgSUKldakyV7W/WDQ=
+google.golang.org/protobuf v1.34.1 h1:9ddQBjfCyZPOHPUiPxpYESBLc+T8P3E+Vo4IbKZgFWg=
+google.golang.org/protobuf v1.34.1/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

libcni/api.go

@@ -14,50 +14,877 @@
 
 package libcni
 
+// Note this is the actual implementation of the CNI specification, which
+// is reflected in the SPEC.md file.
+// it is typically bundled into runtime providers (i.e. containerd or cri-o would use this
+// before calling runc or hcsshim).  It is also bundled into CNI providers as well, for example,
+// to add an IP to a container, to parse the configuration of the CNI and so on.
+
 import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
 	"strings"
 
 	"github.com/containernetworking/cni/pkg/invoke"
 	"github.com/containernetworking/cni/pkg/types"
+	"github.com/containernetworking/cni/pkg/types/create"
+	"github.com/containernetworking/cni/pkg/utils"
+	"github.com/containernetworking/cni/pkg/version"
 )
 
+var (
+	CacheDir = "/var/lib/cni"
+	// slightly awkward wording to preserve anyone matching on error strings
+	ErrorCheckNotSupp = fmt.Errorf("does not support the CHECK command")
+)
+
+const (
+	CNICacheV1 = "cniCacheV1"
+)
+
+// A RuntimeConf holds the arguments to one invocation of a CNI plugin
+// excepting the network configuration, with the nested exception that
+// the `runtimeConfig` from the network configuration is included
+// here.
 type RuntimeConf struct {
 	ContainerID string
 	NetNS       string
 	IfName      string
 	Args        [][2]string
+	// A dictionary of capability-specific data passed by the runtime
+	// to plugins as top-level keys in the 'runtimeConfig' dictionary
+	// of the plugin's stdin data.  libcni will ensure that only keys
+	// in this map which match the capabilities of the plugin are passed
+	// to the plugin
+	CapabilityArgs map[string]interface{}
+
+	// DEPRECATED. Will be removed in a future release.
+	CacheDir string
 }
 
-type NetworkConfig struct {
-	Network *types.NetConf
+// Use PluginConfig instead of NetworkConfig, the NetworkConfig
+// backwards-compat alias will be removed in a future release.
+type NetworkConfig = PluginConfig
+
+type PluginConfig struct {
+	Network *types.PluginConf
 	Bytes   []byte
 }
 
+type NetworkConfigList struct {
+	Name                   string
+	CNIVersion             string
+	DisableCheck           bool
+	DisableGC              bool
+	LoadOnlyInlinedPlugins bool
+	Plugins                []*PluginConfig
+	Bytes                  []byte
+}
+
+type NetworkAttachment struct {
+	ContainerID    string
+	Network        string
+	IfName         string
+	Config         []byte
+	NetNS          string
+	CniArgs        [][2]string
+	CapabilityArgs map[string]interface{}
+}
+
+type GCArgs struct {
+	ValidAttachments []types.GCAttachment
+}
+
 type CNI interface {
-	AddNetwork(net *NetworkConfig, rt *RuntimeConf) (*types.Result, error)
-	DelNetwork(net *NetworkConfig, rt *RuntimeConf) error
+	AddNetworkList(ctx context.Context, net *NetworkConfigList, rt *RuntimeConf) (types.Result, error)
+	CheckNetworkList(ctx context.Context, net *NetworkConfigList, rt *RuntimeConf) error
+	DelNetworkList(ctx context.Context, net *NetworkConfigList, rt *RuntimeConf) error
+	GetNetworkListCachedResult(net *NetworkConfigList, rt *RuntimeConf) (types.Result, error)
+	GetNetworkListCachedConfig(net *NetworkConfigList, rt *RuntimeConf) ([]byte, *RuntimeConf, error)
+
+	AddNetwork(ctx context.Context, net *PluginConfig, rt *RuntimeConf) (types.Result, error)
+	CheckNetwork(ctx context.Context, net *PluginConfig, rt *RuntimeConf) error
+	DelNetwork(ctx context.Context, net *PluginConfig, rt *RuntimeConf) error
+	GetNetworkCachedResult(net *PluginConfig, rt *RuntimeConf) (types.Result, error)
+	GetNetworkCachedConfig(net *PluginConfig, rt *RuntimeConf) ([]byte, *RuntimeConf, error)
+
+	ValidateNetworkList(ctx context.Context, net *NetworkConfigList) ([]string, error)
+	ValidateNetwork(ctx context.Context, net *PluginConfig) ([]string, error)
+
+	GCNetworkList(ctx context.Context, net *NetworkConfigList, args *GCArgs) error
+	GetStatusNetworkList(ctx context.Context, net *NetworkConfigList) error
+
+	GetCachedAttachments(containerID string) ([]*NetworkAttachment, error)
+
+	GetVersionInfo(ctx context.Context, pluginType string) (version.PluginInfo, error)
 }
 
 type CNIConfig struct {
-	Path []string
+	Path     []string
+	exec     invoke.Exec
+	cacheDir string
 }
 
-func (c *CNIConfig) AddNetwork(net *NetworkConfig, rt *RuntimeConf) (*types.Result, error) {
-	pluginPath, err := invoke.FindInPath(net.Network.Type, c.Path)
+// CNIConfig implements the CNI interface
+var _ CNI = &CNIConfig{}
+
+// NewCNIConfig returns a new CNIConfig object that will search for plugins
+// in the given paths and use the given exec interface to run those plugins,
+// or if the exec interface is not given, will use a default exec handler.
+func NewCNIConfig(path []string, exec invoke.Exec) *CNIConfig {
+	return NewCNIConfigWithCacheDir(path, "", exec)
+}
+
+// NewCNIConfigWithCacheDir returns a new CNIConfig object that will search for plugins
+// in the given paths use the given exec interface to run those plugins,
+// or if the exec interface is not given, will use a default exec handler.
+// The given cache directory will be used for temporary data storage when needed.
+func NewCNIConfigWithCacheDir(path []string, cacheDir string, exec invoke.Exec) *CNIConfig {
+	return &CNIConfig{
+		Path:     path,
+		cacheDir: cacheDir,
+		exec:     exec,
+	}
+}
+
+func buildOneConfig(name, cniVersion string, orig *PluginConfig, prevResult types.Result, rt *RuntimeConf) (*PluginConfig, error) {
+	var err error
+
+	inject := map[string]interface{}{
+		"name":       name,
+		"cniVersion": cniVersion,
+	}
+	// Add previous plugin result
+	if prevResult != nil {
+		inject["prevResult"] = prevResult
+	}
+
+	// Ensure every config uses the same name and version
+	orig, err = InjectConf(orig, inject)
 	if err != nil {
 		return nil, err
 	}
+	if rt != nil {
+		return injectRuntimeConfig(orig, rt)
+	}
 
-	return invoke.ExecPluginWithResult(pluginPath, net.Bytes, c.args("ADD", rt))
+	return orig, nil
 }
 
-func (c *CNIConfig) DelNetwork(net *NetworkConfig, rt *RuntimeConf) error {
-	pluginPath, err := invoke.FindInPath(net.Network.Type, c.Path)
+// This function takes a libcni RuntimeConf structure and injects values into
+// a "runtimeConfig" dictionary in the CNI network configuration JSON that
+// will be passed to the plugin on stdin.
+//
+// Only "capabilities arguments" passed by the runtime are currently injected.
+// These capabilities arguments are filtered through the plugin's advertised
+// capabilities from its config JSON, and any keys in the CapabilityArgs
+// matching plugin capabilities are added to the "runtimeConfig" dictionary
+// sent to the plugin via JSON on stdin.  For example, if the plugin's
+// capabilities include "portMappings", and the CapabilityArgs map includes a
+// "portMappings" key, that key and its value are added to the "runtimeConfig"
+// dictionary to be passed to the plugin's stdin.
+func injectRuntimeConfig(orig *PluginConfig, rt *RuntimeConf) (*PluginConfig, error) {
+	var err error
+
+	rc := make(map[string]interface{})
+	for capability, supported := range orig.Network.Capabilities {
+		if !supported {
+			continue
+		}
+		if data, ok := rt.CapabilityArgs[capability]; ok {
+			rc[capability] = data
+		}
+	}
+
+	if len(rc) > 0 {
+		orig, err = InjectConf(orig, map[string]interface{}{"runtimeConfig": rc})
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	return orig, nil
+}
+
+// ensure we have a usable exec if the CNIConfig was not given one
+func (c *CNIConfig) ensureExec() invoke.Exec {
+	if c.exec == nil {
+		c.exec = &invoke.DefaultExec{
+			RawExec:       &invoke.RawExec{Stderr: os.Stderr},
+			PluginDecoder: version.PluginDecoder{},
+		}
+	}
+	return c.exec
+}
+
+type cachedInfo struct {
+	Kind           string                 `json:"kind"`
+	ContainerID    string                 `json:"containerId"`
+	Config         []byte                 `json:"config"`
+	IfName         string                 `json:"ifName"`
+	NetworkName    string                 `json:"networkName"`
+	NetNS          string                 `json:"netns,omitempty"`
+	CniArgs        [][2]string            `json:"cniArgs,omitempty"`
+	CapabilityArgs map[string]interface{} `json:"capabilityArgs,omitempty"`
+	RawResult      map[string]interface{} `json:"result,omitempty"`
+	Result         types.Result           `json:"-"`
+}
+
+// getCacheDir returns the cache directory in this order:
+// 1) global cacheDir from CNIConfig object
+// 2) deprecated cacheDir from RuntimeConf object
+// 3) fall back to default cache directory
+func (c *CNIConfig) getCacheDir(rt *RuntimeConf) string {
+	if c.cacheDir != "" {
+		return c.cacheDir
+	}
+	if rt.CacheDir != "" {
+		return rt.CacheDir
+	}
+	return CacheDir
+}
+
+func (c *CNIConfig) getCacheFilePath(netName string, rt *RuntimeConf) (string, error) {
+	if netName == "" || rt.ContainerID == "" || rt.IfName == "" {
+		return "", fmt.Errorf("cache file path requires network name (%q), container ID (%q), and interface name (%q)", netName, rt.ContainerID, rt.IfName)
+	}
+	return filepath.Join(c.getCacheDir(rt), "results", fmt.Sprintf("%s-%s-%s", netName, rt.ContainerID, rt.IfName)), nil
+}
+
+func (c *CNIConfig) cacheAdd(result types.Result, config []byte, netName string, rt *RuntimeConf) error {
+	cached := cachedInfo{
+		Kind:           CNICacheV1,
+		ContainerID:    rt.ContainerID,
+		Config:         config,
+		IfName:         rt.IfName,
+		NetworkName:    netName,
+		NetNS:          rt.NetNS,
+		CniArgs:        rt.Args,
+		CapabilityArgs: rt.CapabilityArgs,
+	}
+
+	// We need to get type.Result into cachedInfo as JSON map
+	// Marshal to []byte, then Unmarshal into cached.RawResult
+	data, err := json.Marshal(result)
 	if err != nil {
 		return err
 	}
 
-	return invoke.ExecPluginWithoutResult(pluginPath, net.Bytes, c.args("DEL", rt))
+	err = json.Unmarshal(data, &cached.RawResult)
+	if err != nil {
+		return err
+	}
+
+	newBytes, err := json.Marshal(&cached)
+	if err != nil {
+		return err
+	}
+
+	fname, err := c.getCacheFilePath(netName, rt)
+	if err != nil {
+		return err
+	}
+	if err := os.MkdirAll(filepath.Dir(fname), 0o700); err != nil {
+		return err
+	}
+
+	return os.WriteFile(fname, newBytes, 0o600)
+}
+
+func (c *CNIConfig) cacheDel(netName string, rt *RuntimeConf) error {
+	fname, err := c.getCacheFilePath(netName, rt)
+	if err != nil {
+		// Ignore error
+		return nil
+	}
+	return os.Remove(fname)
+}
+
+func (c *CNIConfig) getCachedConfig(netName string, rt *RuntimeConf) ([]byte, *RuntimeConf, error) {
+	var bytes []byte
+
+	fname, err := c.getCacheFilePath(netName, rt)
+	if err != nil {
+		return nil, nil, err
+	}
+	bytes, err = os.ReadFile(fname)
+	if err != nil {
+		// Ignore read errors; the cached result may not exist on-disk
+		return nil, nil, nil
+	}
+
+	unmarshaled := cachedInfo{}
+	if err := json.Unmarshal(bytes, &unmarshaled); err != nil {
+		return nil, nil, fmt.Errorf("failed to unmarshal cached network %q config: %w", netName, err)
+	}
+	if unmarshaled.Kind != CNICacheV1 {
+		return nil, nil, fmt.Errorf("read cached network %q config has wrong kind: %v", netName, unmarshaled.Kind)
+	}
+
+	newRt := *rt
+	if unmarshaled.CniArgs != nil {
+		newRt.Args = unmarshaled.CniArgs
+	}
+	newRt.CapabilityArgs = unmarshaled.CapabilityArgs
+
+	return unmarshaled.Config, &newRt, nil
+}
+
+func (c *CNIConfig) getLegacyCachedResult(netName, cniVersion string, rt *RuntimeConf) (types.Result, error) {
+	fname, err := c.getCacheFilePath(netName, rt)
+	if err != nil {
+		return nil, err
+	}
+	data, err := os.ReadFile(fname)
+	if err != nil {
+		// Ignore read errors; the cached result may not exist on-disk
+		return nil, nil
+	}
+
+	// Load the cached result
+	result, err := create.CreateFromBytes(data)
+	if err != nil {
+		return nil, err
+	}
+
+	// Convert to the config version to ensure plugins get prevResult
+	// in the same version as the config.  The cached result version
+	// should match the config version unless the config was changed
+	// while the container was running.
+	result, err = result.GetAsVersion(cniVersion)
+	if err != nil {
+		return nil, fmt.Errorf("failed to convert cached result to config version %q: %w", cniVersion, err)
+	}
+	return result, nil
+}
+
+func (c *CNIConfig) getCachedResult(netName, cniVersion string, rt *RuntimeConf) (types.Result, error) {
+	fname, err := c.getCacheFilePath(netName, rt)
+	if err != nil {
+		return nil, err
+	}
+	fdata, err := os.ReadFile(fname)
+	if err != nil {
+		// Ignore read errors; the cached result may not exist on-disk
+		return nil, nil
+	}
+
+	cachedInfo := cachedInfo{}
+	if err := json.Unmarshal(fdata, &cachedInfo); err != nil || cachedInfo.Kind != CNICacheV1 {
+		return c.getLegacyCachedResult(netName, cniVersion, rt)
+	}
+
+	newBytes, err := json.Marshal(&cachedInfo.RawResult)
+	if err != nil {
+		return nil, fmt.Errorf("failed to marshal cached network %q config: %w", netName, err)
+	}
+
+	// Load the cached result
+	result, err := create.CreateFromBytes(newBytes)
+	if err != nil {
+		return nil, err
+	}
+
+	// Convert to the config version to ensure plugins get prevResult
+	// in the same version as the config.  The cached result version
+	// should match the config version unless the config was changed
+	// while the container was running.
+	result, err = result.GetAsVersion(cniVersion)
+	if err != nil {
+		return nil, fmt.Errorf("failed to convert cached result to config version %q: %w", cniVersion, err)
+	}
+	return result, nil
+}
+
+// GetNetworkListCachedResult returns the cached Result of the previous
+// AddNetworkList() operation for a network list, or an error.
+func (c *CNIConfig) GetNetworkListCachedResult(list *NetworkConfigList, rt *RuntimeConf) (types.Result, error) {
+	return c.getCachedResult(list.Name, list.CNIVersion, rt)
+}
+
+// GetNetworkCachedResult returns the cached Result of the previous
+// AddNetwork() operation for a network, or an error.
+func (c *CNIConfig) GetNetworkCachedResult(net *PluginConfig, rt *RuntimeConf) (types.Result, error) {
+	return c.getCachedResult(net.Network.Name, net.Network.CNIVersion, rt)
+}
+
+// GetNetworkListCachedConfig copies the input RuntimeConf to output
+// RuntimeConf with fields updated with info from the cached Config.
+func (c *CNIConfig) GetNetworkListCachedConfig(list *NetworkConfigList, rt *RuntimeConf) ([]byte, *RuntimeConf, error) {
+	return c.getCachedConfig(list.Name, rt)
+}
+
+// GetNetworkCachedConfig copies the input RuntimeConf to output
+// RuntimeConf with fields updated with info from the cached Config.
+func (c *CNIConfig) GetNetworkCachedConfig(net *PluginConfig, rt *RuntimeConf) ([]byte, *RuntimeConf, error) {
+	return c.getCachedConfig(net.Network.Name, rt)
+}
+
+// GetCachedAttachments returns a list of network attachments from the cache.
+// The returned list will be filtered by the containerID if the value is not empty.
+func (c *CNIConfig) GetCachedAttachments(containerID string) ([]*NetworkAttachment, error) {
+	dirPath := filepath.Join(c.getCacheDir(&RuntimeConf{}), "results")
+	entries, err := os.ReadDir(dirPath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, err
+	}
+
+	fileNames := make([]string, 0, len(entries))
+	for _, e := range entries {
+		fileNames = append(fileNames, e.Name())
+	}
+	sort.Strings(fileNames)
+
+	attachments := []*NetworkAttachment{}
+	for _, fname := range fileNames {
+		if len(containerID) > 0 {
+			part := fmt.Sprintf("-%s-", containerID)
+			pos := strings.Index(fname, part)
+			if pos <= 0 || pos+len(part) >= len(fname) {
+				continue
+			}
+		}
+
+		cacheFile := filepath.Join(dirPath, fname)
+		bytes, err := os.ReadFile(cacheFile)
+		if err != nil {
+			continue
+		}
+
+		cachedInfo := cachedInfo{}
+
+		if err := json.Unmarshal(bytes, &cachedInfo); err != nil {
+			continue
+		}
+		if cachedInfo.Kind != CNICacheV1 {
+			continue
+		}
+		if len(containerID) > 0 && cachedInfo.ContainerID != containerID {
+			continue
+		}
+		if cachedInfo.IfName == "" || cachedInfo.NetworkName == "" {
+			continue
+		}
+
+		attachments = append(attachments, &NetworkAttachment{
+			ContainerID:    cachedInfo.ContainerID,
+			Network:        cachedInfo.NetworkName,
+			IfName:         cachedInfo.IfName,
+			Config:         cachedInfo.Config,
+			NetNS:          cachedInfo.NetNS,
+			CniArgs:        cachedInfo.CniArgs,
+			CapabilityArgs: cachedInfo.CapabilityArgs,
+		})
+	}
+	return attachments, nil
+}
+
+func (c *CNIConfig) addNetwork(ctx context.Context, name, cniVersion string, net *PluginConfig, prevResult types.Result, rt *RuntimeConf) (types.Result, error) {
+	c.ensureExec()
+	pluginPath, err := c.exec.FindInPath(net.Network.Type, c.Path)
+	if err != nil {
+		return nil, err
+	}
+	if err := utils.ValidateContainerID(rt.ContainerID); err != nil {
+		return nil, err
+	}
+	if err := utils.ValidateNetworkName(name); err != nil {
+		return nil, err
+	}
+	if err := utils.ValidateInterfaceName(rt.IfName); err != nil {
+		return nil, err
+	}
+
+	newConf, err := buildOneConfig(name, cniVersion, net, prevResult, rt)
+	if err != nil {
+		return nil, err
+	}
+
+	return invoke.ExecPluginWithResult(ctx, pluginPath, newConf.Bytes, c.args("ADD", rt), c.exec)
+}
+
+// AddNetworkList executes a sequence of plugins with the ADD command
+func (c *CNIConfig) AddNetworkList(ctx context.Context, list *NetworkConfigList, rt *RuntimeConf) (types.Result, error) {
+	var err error
+	var result types.Result
+	for _, net := range list.Plugins {
+		result, err = c.addNetwork(ctx, list.Name, list.CNIVersion, net, result, rt)
+		if err != nil {
+			return nil, fmt.Errorf("plugin %s failed (add): %w", pluginDescription(net.Network), err)
+		}
+	}
+
+	if err = c.cacheAdd(result, list.Bytes, list.Name, rt); err != nil {
+		return nil, fmt.Errorf("failed to set network %q cached result: %w", list.Name, err)
+	}
+
+	return result, nil
+}
+
+func (c *CNIConfig) checkNetwork(ctx context.Context, name, cniVersion string, net *PluginConfig, prevResult types.Result, rt *RuntimeConf) error {
+	c.ensureExec()
+	pluginPath, err := c.exec.FindInPath(net.Network.Type, c.Path)
+	if err != nil {
+		return err
+	}
+
+	newConf, err := buildOneConfig(name, cniVersion, net, prevResult, rt)
+	if err != nil {
+		return err
+	}
+
+	return invoke.ExecPluginWithoutResult(ctx, pluginPath, newConf.Bytes, c.args("CHECK", rt), c.exec)
+}
+
+// CheckNetworkList executes a sequence of plugins with the CHECK command
+func (c *CNIConfig) CheckNetworkList(ctx context.Context, list *NetworkConfigList, rt *RuntimeConf) error {
+	// CHECK was added in CNI spec version 0.4.0 and higher
+	if gtet, err := version.GreaterThanOrEqualTo(list.CNIVersion, "0.4.0"); err != nil {
+		return err
+	} else if !gtet {
+		return fmt.Errorf("configuration version %q %w", list.CNIVersion, ErrorCheckNotSupp)
+	}
+
+	if list.DisableCheck {
+		return nil
+	}
+
+	cachedResult, err := c.getCachedResult(list.Name, list.CNIVersion, rt)
+	if err != nil {
+		return fmt.Errorf("failed to get network %q cached result: %w", list.Name, err)
+	}
+
+	for _, net := range list.Plugins {
+		if err := c.checkNetwork(ctx, list.Name, list.CNIVersion, net, cachedResult, rt); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func (c *CNIConfig) delNetwork(ctx context.Context, name, cniVersion string, net *PluginConfig, prevResult types.Result, rt *RuntimeConf) error {
+	c.ensureExec()
+	pluginPath, err := c.exec.FindInPath(net.Network.Type, c.Path)
+	if err != nil {
+		return err
+	}
+
+	newConf, err := buildOneConfig(name, cniVersion, net, prevResult, rt)
+	if err != nil {
+		return err
+	}
+
+	return invoke.ExecPluginWithoutResult(ctx, pluginPath, newConf.Bytes, c.args("DEL", rt), c.exec)
+}
+
+// DelNetworkList executes a sequence of plugins with the DEL command
+func (c *CNIConfig) DelNetworkList(ctx context.Context, list *NetworkConfigList, rt *RuntimeConf) error {
+	var cachedResult types.Result
+
+	// Cached result on DEL was added in CNI spec version 0.4.0 and higher
+	if gtet, err := version.GreaterThanOrEqualTo(list.CNIVersion, "0.4.0"); err != nil {
+		return err
+	} else if gtet {
+		if cachedResult, err = c.getCachedResult(list.Name, list.CNIVersion, rt); err != nil {
+			_ = c.cacheDel(list.Name, rt)
+			cachedResult = nil
+		}
+	}
+
+	for i := len(list.Plugins) - 1; i >= 0; i-- {
+		net := list.Plugins[i]
+		if err := c.delNetwork(ctx, list.Name, list.CNIVersion, net, cachedResult, rt); err != nil {
+			return fmt.Errorf("plugin %s failed (delete): %w", pluginDescription(net.Network), err)
+		}
+	}
+
+	_ = c.cacheDel(list.Name, rt)
+
+	return nil
+}
+
+func pluginDescription(net *types.PluginConf) string {
+	if net == nil {
+		return "<missing>"
+	}
+	pluginType := net.Type
+	out := fmt.Sprintf("type=%q", pluginType)
+	name := net.Name
+	if name != "" {
+		out += fmt.Sprintf(" name=%q", name)
+	}
+	return out
+}
+
+// AddNetwork executes the plugin with the ADD command
+func (c *CNIConfig) AddNetwork(ctx context.Context, net *PluginConfig, rt *RuntimeConf) (types.Result, error) {
+	result, err := c.addNetwork(ctx, net.Network.Name, net.Network.CNIVersion, net, nil, rt)
+	if err != nil {
+		return nil, err
+	}
+
+	if err = c.cacheAdd(result, net.Bytes, net.Network.Name, rt); err != nil {
+		return nil, fmt.Errorf("failed to set network %q cached result: %w", net.Network.Name, err)
+	}
+
+	return result, nil
+}
+
+// CheckNetwork executes the plugin with the CHECK command
+func (c *CNIConfig) CheckNetwork(ctx context.Context, net *PluginConfig, rt *RuntimeConf) error {
+	// CHECK was added in CNI spec version 0.4.0 and higher
+	if gtet, err := version.GreaterThanOrEqualTo(net.Network.CNIVersion, "0.4.0"); err != nil {
+		return err
+	} else if !gtet {
+		return fmt.Errorf("configuration version %q %w", net.Network.CNIVersion, ErrorCheckNotSupp)
+	}
+
+	cachedResult, err := c.getCachedResult(net.Network.Name, net.Network.CNIVersion, rt)
+	if err != nil {
+		return fmt.Errorf("failed to get network %q cached result: %w", net.Network.Name, err)
+	}
+	return c.checkNetwork(ctx, net.Network.Name, net.Network.CNIVersion, net, cachedResult, rt)
+}
+
+// DelNetwork executes the plugin with the DEL command
+func (c *CNIConfig) DelNetwork(ctx context.Context, net *PluginConfig, rt *RuntimeConf) error {
+	var cachedResult types.Result
+
+	// Cached result on DEL was added in CNI spec version 0.4.0 and higher
+	if gtet, err := version.GreaterThanOrEqualTo(net.Network.CNIVersion, "0.4.0"); err != nil {
+		return err
+	} else if gtet {
+		cachedResult, err = c.getCachedResult(net.Network.Name, net.Network.CNIVersion, rt)
+		if err != nil {
+			return fmt.Errorf("failed to get network %q cached result: %w", net.Network.Name, err)
+		}
+	}
+
+	if err := c.delNetwork(ctx, net.Network.Name, net.Network.CNIVersion, net, cachedResult, rt); err != nil {
+		return err
+	}
+	_ = c.cacheDel(net.Network.Name, rt)
+	return nil
+}
+
+// ValidateNetworkList checks that a configuration is reasonably valid.
+// - all the specified plugins exist on disk
+// - every plugin supports the desired version.
+//
+// Returns a list of all capabilities supported by the configuration, or error
+func (c *CNIConfig) ValidateNetworkList(ctx context.Context, list *NetworkConfigList) ([]string, error) {
+	version := list.CNIVersion
+
+	// holding map for seen caps (in case of duplicates)
+	caps := map[string]interface{}{}
+
+	errs := []error{}
+	for _, net := range list.Plugins {
+		if err := c.validatePlugin(ctx, net.Network.Type, version); err != nil {
+			errs = append(errs, err)
+		}
+		for c, enabled := range net.Network.Capabilities {
+			if !enabled {
+				continue
+			}
+			caps[c] = struct{}{}
+		}
+	}
+
+	if len(errs) > 0 {
+		return nil, fmt.Errorf("%v", errs)
+	}
+
+	// make caps list
+	cc := make([]string, 0, len(caps))
+	for c := range caps {
+		cc = append(cc, c)
+	}
+
+	return cc, nil
+}
+
+// ValidateNetwork checks that a configuration is reasonably valid.
+// It uses the same logic as ValidateNetworkList)
+// Returns a list of capabilities
+func (c *CNIConfig) ValidateNetwork(ctx context.Context, net *PluginConfig) ([]string, error) {
+	caps := []string{}
+	for c, ok := range net.Network.Capabilities {
+		if ok {
+			caps = append(caps, c)
+		}
+	}
+	if err := c.validatePlugin(ctx, net.Network.Type, net.Network.CNIVersion); err != nil {
+		return nil, err
+	}
+	return caps, nil
+}
+
+// validatePlugin checks that an individual plugin's configuration is sane
+func (c *CNIConfig) validatePlugin(ctx context.Context, pluginName, expectedVersion string) error {
+	c.ensureExec()
+	pluginPath, err := c.exec.FindInPath(pluginName, c.Path)
+	if err != nil {
+		return err
+	}
+	if expectedVersion == "" {
+		expectedVersion = "0.1.0"
+	}
+
+	vi, err := invoke.GetVersionInfo(ctx, pluginPath, c.exec)
+	if err != nil {
+		return err
+	}
+	for _, vers := range vi.SupportedVersions() {
+		if vers == expectedVersion {
+			return nil
+		}
+	}
+	return fmt.Errorf("plugin %s does not support config version %q", pluginName, expectedVersion)
+}
+
+// GetVersionInfo reports which versions of the CNI spec are supported by
+// the given plugin.
+func (c *CNIConfig) GetVersionInfo(ctx context.Context, pluginType string) (version.PluginInfo, error) {
+	c.ensureExec()
+	pluginPath, err := c.exec.FindInPath(pluginType, c.Path)
+	if err != nil {
+		return nil, err
+	}
+
+	return invoke.GetVersionInfo(ctx, pluginPath, c.exec)
+}
+
+// GCNetworkList will do two things
+// - dump the list of cached attachments, and issue deletes as necessary
+// - issue a GC to the underlying plugins (if the version is high enough)
+func (c *CNIConfig) GCNetworkList(ctx context.Context, list *NetworkConfigList, args *GCArgs) error {
+	// If DisableGC is set, then don't bother GCing at all.
+	if list.DisableGC {
+		return nil
+	}
+
+	// First, get the list of cached attachments
+	cachedAttachments, err := c.GetCachedAttachments("")
+	if err != nil {
+		return nil
+	}
+
+	var validAttachments map[types.GCAttachment]interface{}
+	if args != nil {
+		validAttachments = make(map[types.GCAttachment]interface{}, len(args.ValidAttachments))
+		for _, a := range args.ValidAttachments {
+			validAttachments[a] = nil
+		}
+	}
+
+	var errs []error
+
+	for _, cachedAttachment := range cachedAttachments {
+		if cachedAttachment.Network != list.Name {
+			continue
+		}
+		// we found this attachment
+		gca := types.GCAttachment{
+			ContainerID: cachedAttachment.ContainerID,
+			IfName:      cachedAttachment.IfName,
+		}
+		if _, ok := validAttachments[gca]; ok {
+			continue
+		}
+		// otherwise, this attachment wasn't valid and we should issue a CNI DEL
+		rt := RuntimeConf{
+			ContainerID:    cachedAttachment.ContainerID,
+			NetNS:          cachedAttachment.NetNS,
+			IfName:         cachedAttachment.IfName,
+			Args:           cachedAttachment.CniArgs,
+			CapabilityArgs: cachedAttachment.CapabilityArgs,
+		}
+		if err := c.DelNetworkList(ctx, list, &rt); err != nil {
+			errs = append(errs, fmt.Errorf("failed to delete stale attachment %s %s: %w", rt.ContainerID, rt.IfName, err))
+		}
+	}
+
+	// now, if the version supports it, issue a GC
+	if gt, _ := version.GreaterThanOrEqualTo(list.CNIVersion, "1.1.0"); gt {
+		inject := map[string]interface{}{
+			"name":       list.Name,
+			"cniVersion": list.CNIVersion,
+		}
+		if args != nil {
+			inject["cni.dev/valid-attachments"] = args.ValidAttachments
+			// #1101: spec used incorrect variable name
+			inject["cni.dev/attachments"] = args.ValidAttachments
+		}
+
+		for _, plugin := range list.Plugins {
+			// build config here
+			pluginConfig, err := InjectConf(plugin, inject)
+			if err != nil {
+				errs = append(errs, fmt.Errorf("failed to generate configuration to GC plugin %s: %w", plugin.Network.Type, err))
+			}
+			if err := c.gcNetwork(ctx, pluginConfig); err != nil {
+				errs = append(errs, fmt.Errorf("failed to GC plugin %s: %w", plugin.Network.Type, err))
+			}
+		}
+	}
+
+	return errors.Join(errs...)
+}
+
+func (c *CNIConfig) gcNetwork(ctx context.Context, net *PluginConfig) error {
+	c.ensureExec()
+	pluginPath, err := c.exec.FindInPath(net.Network.Type, c.Path)
+	if err != nil {
+		return err
+	}
+	args := c.args("GC", &RuntimeConf{})
+
+	return invoke.ExecPluginWithoutResult(ctx, pluginPath, net.Bytes, args, c.exec)
+}
+
+func (c *CNIConfig) GetStatusNetworkList(ctx context.Context, list *NetworkConfigList) error {
+	// If the version doesn't support status, abort.
+	if gt, _ := version.GreaterThanOrEqualTo(list.CNIVersion, "1.1.0"); !gt {
+		return nil
+	}
+
+	inject := map[string]interface{}{
+		"name":       list.Name,
+		"cniVersion": list.CNIVersion,
+	}
+
+	for _, plugin := range list.Plugins {
+		// build config here
+		pluginConfig, err := InjectConf(plugin, inject)
+		if err != nil {
+			return fmt.Errorf("failed to generate configuration to get plugin STATUS %s: %w", plugin.Network.Type, err)
+		}
+		if err := c.getStatusNetwork(ctx, pluginConfig); err != nil {
+			return err // Don't collect errors here, so we return a clean error code.
+		}
+	}
+	return nil
+}
+
+func (c *CNIConfig) getStatusNetwork(ctx context.Context, net *PluginConfig) error {
+	c.ensureExec()
+	pluginPath, err := c.exec.FindInPath(net.Network.Type, c.Path)
+	if err != nil {
+		return err
+	}
+	args := c.args("STATUS", &RuntimeConf{})
+
+	return invoke.ExecPluginWithoutResult(ctx, pluginPath, net.Bytes, args, c.exec)
 }
 
 // =====
@@ -68,6 +895,6 @@ func (c *CNIConfig) args(action string, rt *RuntimeConf) *invoke.Args {
 		NetNS:       rt.NetNS,
 		PluginArgs:  rt.Args,
 		IfName:      rt.IfName,
-		Path:        strings.Join(c.Path, ":"),
+		Path:        strings.Join(c.Path, string(os.PathListSeparator)),
 	}
 }

libcni/backwards_compatibility_test.go

@@ -0,0 +1,100 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package libcni_test
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"github.com/onsi/gomega/gexec"
+
+	"github.com/containernetworking/cni/libcni"
+	"github.com/containernetworking/cni/pkg/version/legacy_examples"
+)
+
+var _ = Describe("Backwards compatibility", func() {
+	var cacheDirPath string
+
+	BeforeEach(func() {
+		var err error
+		cacheDirPath, err = os.MkdirTemp("", "cni_cachedir")
+		Expect(err).NotTo(HaveOccurred())
+	})
+
+	AfterEach(func() {
+		Expect(os.RemoveAll(cacheDirPath)).To(Succeed())
+	})
+
+	It("correctly handles the response from a legacy plugin", func() {
+		example := legacy_examples.V010
+		pluginPath, err := example.Build()
+		Expect(err).NotTo(HaveOccurred())
+
+		netConf, err := libcni.ConfFromBytes([]byte(fmt.Sprintf(
+			`{ "name": "old-thing", "type": "%s" }`, example.Name)))
+		Expect(err).NotTo(HaveOccurred())
+
+		runtimeConf := &libcni.RuntimeConf{
+			ContainerID: "some-container-id",
+			NetNS:       "/some/netns/path",
+			IfName:      "eth0",
+		}
+
+		cniConfig := libcni.NewCNIConfigWithCacheDir([]string{filepath.Dir(pluginPath)}, cacheDirPath, nil)
+
+		result, err := cniConfig.AddNetwork(context.TODO(), netConf, runtimeConf)
+		Expect(err).NotTo(HaveOccurred())
+
+		Expect(result).To(Equal(legacy_examples.ExpectedResult))
+
+		err = cniConfig.DelNetwork(context.TODO(), netConf, runtimeConf)
+		Expect(err).NotTo(HaveOccurred())
+
+		Expect(os.RemoveAll(pluginPath)).To(Succeed())
+	})
+
+	It("correctly handles the request from a runtime with an older libcni", func() {
+		if runtime.GOOS == "windows" {
+			Skip("cannot build old runtime on windows")
+		}
+		example := legacy_examples.V010_Runtime
+
+		binPath, err := example.Build()
+		Expect(err).NotTo(HaveOccurred())
+
+		for _, configName := range example.NetConfs {
+			conf, err := example.GenerateNetConf(configName)
+			if err != nil {
+				Fail("Failed to generate config name " + configName + ": " + err.Error())
+			}
+			defer conf.Cleanup()
+
+			cmd := exec.Command(binPath, pluginDirs...)
+			cmd.Stdin = strings.NewReader(conf.Config)
+
+			session, err := gexec.Start(cmd, GinkgoWriter, GinkgoWriter)
+			Expect(err).NotTo(HaveOccurred())
+
+			Eventually(session).Should(gexec.Exit(0))
+		}
+	})
+})

libcni/conf.go

@@ -16,35 +16,293 @@ package libcni
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
-	"io/ioutil"
 	"os"
 	"path/filepath"
+	"slices"
 	"sort"
+	"strings"
+
+	"github.com/containernetworking/cni/pkg/types"
+	"github.com/containernetworking/cni/pkg/version"
 )
 
-func ConfFromBytes(bytes []byte) (*NetworkConfig, error) {
-	conf := &NetworkConfig{Bytes: bytes}
-	if err := json.Unmarshal(bytes, &conf.Network); err != nil {
-		return nil, fmt.Errorf("error parsing configuration: %s", err)
+type NotFoundError struct {
+	Dir  string
+	Name string
+}
+
+func (e NotFoundError) Error() string {
+	return fmt.Sprintf(`no net configuration with name "%s" in %s`, e.Name, e.Dir)
+}
+
+type NoConfigsFoundError struct {
+	Dir string
+}
+
+func (e NoConfigsFoundError) Error() string {
+	return fmt.Sprintf(`no net configurations found in %s`, e.Dir)
+}
+
+// This will not validate that the plugins actually belong to the netconfig by ensuring
+// that they are loaded from a directory named after the networkName, relative to the network config.
+//
+// Since here we are just accepting raw bytes, the caller is responsible for ensuring that the plugin
+// config provided here actually "belongs" to the networkconfig in question.
+func NetworkPluginConfFromBytes(pluginConfBytes []byte) (*PluginConfig, error) {
+	// TODO why are we creating a struct that holds both the byte representation and the deserialized
+	// representation, and returning that, instead of just returning the deserialized representation?
+	conf := &PluginConfig{Bytes: pluginConfBytes, Network: &types.PluginConf{}}
+	if err := json.Unmarshal(pluginConfBytes, conf.Network); err != nil {
+		return nil, fmt.Errorf("error parsing configuration: %w", err)
+	}
+	if conf.Network.Type == "" {
+		return nil, fmt.Errorf("error parsing configuration: missing 'type'")
 	}
 	return conf, nil
 }
 
-func ConfFromFile(filename string) (*NetworkConfig, error) {
-	bytes, err := ioutil.ReadFile(filename)
+// Given a path to a directory containing a network configuration, and the name of a network,
+// loads all plugin definitions found at path `networkConfPath/networkName/*.conf`
+func NetworkPluginConfsFromFiles(networkConfPath, networkName string) ([]*PluginConfig, error) {
+	var pConfs []*PluginConfig
+
+	pluginConfPath := filepath.Join(networkConfPath, networkName)
+
+	pluginConfFiles, err := ConfFiles(pluginConfPath, []string{".conf"})
 	if err != nil {
-		return nil, fmt.Errorf("error reading %s: %s", filename, err)
+		return nil, fmt.Errorf("failed to read plugin config files in %s: %w", pluginConfPath, err)
+	}
+
+	for _, pluginConfFile := range pluginConfFiles {
+		pluginConfBytes, err := os.ReadFile(pluginConfFile)
+		if err != nil {
+			return nil, fmt.Errorf("error reading %s: %w", pluginConfFile, err)
+		}
+		pluginConf, err := NetworkPluginConfFromBytes(pluginConfBytes)
+		if err != nil {
+			return nil, err
+		}
+		pConfs = append(pConfs, pluginConf)
+	}
+	return pConfs, nil
+}
+
+func NetworkConfFromBytes(confBytes []byte) (*NetworkConfigList, error) {
+	rawList := make(map[string]interface{})
+	if err := json.Unmarshal(confBytes, &rawList); err != nil {
+		return nil, fmt.Errorf("error parsing configuration list: %w", err)
+	}
+
+	rawName, ok := rawList["name"]
+	if !ok {
+		return nil, fmt.Errorf("error parsing configuration list: no name")
+	}
+	name, ok := rawName.(string)
+	if !ok {
+		return nil, fmt.Errorf("error parsing configuration list: invalid name type %T", rawName)
+	}
+
+	var cniVersion string
+	rawVersion, ok := rawList["cniVersion"]
+	if ok {
+		cniVersion, ok = rawVersion.(string)
+		if !ok {
+			return nil, fmt.Errorf("error parsing configuration list: invalid cniVersion type %T", rawVersion)
+		}
+	}
+
+	rawVersions, ok := rawList["cniVersions"]
+	if ok {
+		// Parse the current package CNI version
+		rvs, ok := rawVersions.([]interface{})
+		if !ok {
+			return nil, fmt.Errorf("error parsing configuration list: invalid type for cniVersions: %T", rvs)
+		}
+		vs := make([]string, 0, len(rvs))
+		for i, rv := range rvs {
+			v, ok := rv.(string)
+			if !ok {
+				return nil, fmt.Errorf("error parsing configuration list: invalid type for cniVersions index %d: %T", i, rv)
+			}
+			gt, err := version.GreaterThan(v, version.Current())
+			if err != nil {
+				return nil, fmt.Errorf("error parsing configuration list: invalid cniVersions entry %s at index %d: %w", v, i, err)
+			} else if !gt {
+				// Skip versions "greater" than this implementation of the spec
+				vs = append(vs, v)
+			}
+		}
+
+		// if cniVersion was already set, append it to the list for sorting.
+		if cniVersion != "" {
+			gt, err := version.GreaterThan(cniVersion, version.Current())
+			if err != nil {
+				return nil, fmt.Errorf("error parsing configuration list: invalid cniVersion %s: %w", cniVersion, err)
+			} else if !gt {
+				// ignore any versions higher than the current implemented spec version
+				vs = append(vs, cniVersion)
+			}
+		}
+		slices.SortFunc[[]string](vs, func(v1, v2 string) int {
+			if v1 == v2 {
+				return 0
+			}
+			if gt, _ := version.GreaterThan(v1, v2); gt {
+				return 1
+			}
+			return -1
+		})
+		if len(vs) > 0 {
+			cniVersion = vs[len(vs)-1]
+		}
+	}
+
+	readBool := func(key string) (bool, error) {
+		rawVal, ok := rawList[key]
+		if !ok {
+			return false, nil
+		}
+		if b, ok := rawVal.(bool); ok {
+			return b, nil
+		}
+
+		s, ok := rawVal.(string)
+		if !ok {
+			return false, fmt.Errorf("error parsing configuration list: invalid type %T for %s", rawVal, key)
+		}
+		s = strings.ToLower(s)
+		switch s {
+		case "false":
+			return false, nil
+		case "true":
+			return true, nil
+		}
+		return false, fmt.Errorf("error parsing configuration list: invalid value %q for %s", s, key)
+	}
+
+	disableCheck, err := readBool("disableCheck")
+	if err != nil {
+		return nil, err
+	}
+
+	disableGC, err := readBool("disableGC")
+	if err != nil {
+		return nil, err
+	}
+
+	loadOnlyInlinedPlugins, err := readBool("loadOnlyInlinedPlugins")
+	if err != nil {
+		return nil, err
+	}
+
+	list := &NetworkConfigList{
+		Name:                   name,
+		DisableCheck:           disableCheck,
+		DisableGC:              disableGC,
+		LoadOnlyInlinedPlugins: loadOnlyInlinedPlugins,
+		CNIVersion:             cniVersion,
+		Bytes:                  confBytes,
+	}
+
+	var plugins []interface{}
+	plug, ok := rawList["plugins"]
+	// We can have a `plugins` list key in the main conf,
+	// We can also have `loadOnlyInlinedPlugins == true`
+	//
+	// If `plugins` is there, then `loadOnlyInlinedPlugins` can be true
+	//
+	// If plugins is NOT there, then `loadOnlyInlinedPlugins` cannot be true
+	//
+	// We have to have at least some plugins.
+	if !ok && loadOnlyInlinedPlugins {
+		return nil, fmt.Errorf("error parsing configuration list: `loadOnlyInlinedPlugins` is true, and no 'plugins' key")
+	} else if !ok && !loadOnlyInlinedPlugins {
+		return list, nil
+	}
+
+	plugins, ok = plug.([]interface{})
+	if !ok {
+		return nil, fmt.Errorf("error parsing configuration list: invalid 'plugins' type %T", plug)
+	}
+	if len(plugins) == 0 {
+		return nil, fmt.Errorf("error parsing configuration list: no plugins in list")
+	}
+
+	for i, conf := range plugins {
+		newBytes, err := json.Marshal(conf)
+		if err != nil {
+			return nil, fmt.Errorf("failed to marshal plugin config %d: %w", i, err)
+		}
+		netConf, err := ConfFromBytes(newBytes)
+		if err != nil {
+			return nil, fmt.Errorf("failed to parse plugin config %d: %w", i, err)
+		}
+		list.Plugins = append(list.Plugins, netConf)
+	}
+	return list, nil
+}
+
+func NetworkConfFromFile(filename string) (*NetworkConfigList, error) {
+	bytes, err := os.ReadFile(filename)
+	if err != nil {
+		return nil, fmt.Errorf("error reading %s: %w", filename, err)
+	}
+
+	conf, err := NetworkConfFromBytes(bytes)
+	if err != nil {
+		return nil, err
+	}
+
+	if !conf.LoadOnlyInlinedPlugins {
+		plugins, err := NetworkPluginConfsFromFiles(filepath.Dir(filename), conf.Name)
+		if err != nil {
+			return nil, err
+		}
+		conf.Plugins = append(conf.Plugins, plugins...)
+	}
+
+	if len(conf.Plugins) == 0 {
+		// Having 0 plugins for a given network is not necessarily a problem,
+		// but return as error for caller to decide, since they tried to load
+		return nil, fmt.Errorf("no plugin configs found")
+	}
+	return conf, nil
+}
+
+// Deprecated: This file format is no longer supported, use NetworkConfXXX and NetworkPluginXXX functions
+func ConfFromBytes(bytes []byte) (*NetworkConfig, error) {
+	return NetworkPluginConfFromBytes(bytes)
+}
+
+// Deprecated: This file format is no longer supported, use NetworkConfXXX and NetworkPluginXXX functions
+func ConfFromFile(filename string) (*NetworkConfig, error) {
+	bytes, err := os.ReadFile(filename)
+	if err != nil {
+		return nil, fmt.Errorf("error reading %s: %w", filename, err)
 	}
 	return ConfFromBytes(bytes)
 }
 
-func ConfFiles(dir string) ([]string, error) {
+func ConfListFromBytes(bytes []byte) (*NetworkConfigList, error) {
+	return NetworkConfFromBytes(bytes)
+}
+
+func ConfListFromFile(filename string) (*NetworkConfigList, error) {
+	return NetworkConfFromFile(filename)
+}
+
+// ConfFiles simply returns a slice of all files in the provided directory
+// with extensions matching the provided set.
+func ConfFiles(dir string, extensions []string) ([]string, error) {
 	// In part, adapted from rkt/networking/podenv.go#listFiles
-	files, err := ioutil.ReadDir(dir)
+	files, err := os.ReadDir(dir)
 	switch {
 	case err == nil: // break
 	case os.IsNotExist(err):
+		// If folder not there, return no error - only return an
+		// error if we cannot read contents or there are no contents.
 		return nil, nil
 	default:
 		return nil, err
@@ -55,20 +313,24 @@ func ConfFiles(dir string) ([]string, error) {
 		if f.IsDir() {
 			continue
 		}
-		if filepath.Ext(f.Name()) == ".conf" {
-			confFiles = append(confFiles, filepath.Join(dir, f.Name()))
+		fileExt := filepath.Ext(f.Name())
+		for _, ext := range extensions {
+			if fileExt == ext {
+				confFiles = append(confFiles, filepath.Join(dir, f.Name()))
+			}
 		}
 	}
 	return confFiles, nil
 }
 
+// Deprecated: This file format is no longer supported, use NetworkConfXXX and NetworkPluginXXX functions
 func LoadConf(dir, name string) (*NetworkConfig, error) {
-	files, err := ConfFiles(dir)
+	files, err := ConfFiles(dir, []string{".conf", ".json"})
 	switch {
 	case err != nil:
 		return nil, err
 	case len(files) == 0:
-		return nil, fmt.Errorf("no net configurations found")
+		return nil, NoConfigsFoundError{Dir: dir}
 	}
 	sort.Strings(files)
 
@@ -81,5 +343,103 @@ func LoadConf(dir, name string) (*NetworkConfig, error) {
 			return conf, nil
 		}
 	}
-	return nil, fmt.Errorf(`no net configuration with name "%s" in %s`, name, dir)
+	return nil, NotFoundError{dir, name}
+}
+
+func LoadConfList(dir, name string) (*NetworkConfigList, error) {
+	return LoadNetworkConf(dir, name)
+}
+
+// LoadNetworkConf looks at all the network configs in a given dir,
+// loads and parses them all, and returns the first one with an extension of `.conf`
+// that matches the provided network name predicate.
+func LoadNetworkConf(dir, name string) (*NetworkConfigList, error) {
+	// TODO this .conflist/.conf extension thing is confusing and inexact
+	// for implementors. We should pick one extension for everything and stick with it.
+	files, err := ConfFiles(dir, []string{".conflist"})
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(files)
+
+	for _, confFile := range files {
+		conf, err := NetworkConfFromFile(confFile)
+		if err != nil {
+			return nil, err
+		}
+		if conf.Name == name {
+			return conf, nil
+		}
+	}
+
+	// Deprecated: Try and load a network configuration file (instead of list)
+	// from the same name, then upconvert.
+	singleConf, err := LoadConf(dir, name)
+	if err != nil {
+		// A little extra logic so the error makes sense
+		var ncfErr NoConfigsFoundError
+		if len(files) != 0 && errors.As(err, &ncfErr) {
+			// Config lists found but no config files found
+			return nil, NotFoundError{dir, name}
+		}
+
+		return nil, err
+	}
+	return ConfListFromConf(singleConf)
+}
+
+// InjectConf takes a PluginConfig and inserts additional values into it, ensuring the result is serializable.
+func InjectConf(original *PluginConfig, newValues map[string]interface{}) (*PluginConfig, error) {
+	config := make(map[string]interface{})
+	err := json.Unmarshal(original.Bytes, &config)
+	if err != nil {
+		return nil, fmt.Errorf("unmarshal existing network bytes: %w", err)
+	}
+
+	for key, value := range newValues {
+		if key == "" {
+			return nil, fmt.Errorf("keys cannot be empty")
+		}
+
+		if value == nil {
+			return nil, fmt.Errorf("key '%s' value must not be nil", key)
+		}
+
+		config[key] = value
+	}
+
+	newBytes, err := json.Marshal(config)
+	if err != nil {
+		return nil, err
+	}
+
+	return NetworkPluginConfFromBytes(newBytes)
+}
+
+// ConfListFromConf "upconverts" a network config in to a NetworkConfigList,
+// with the single network as the only entry in the list.
+//
+// Deprecated: Non-conflist file formats are unsupported, use NetworkConfXXX and NetworkPluginXXX functions
+func ConfListFromConf(original *PluginConfig) (*NetworkConfigList, error) {
+	// Re-deserialize the config's json, then make a raw map configlist.
+	// This may seem a bit strange, but it's to make the Bytes fields
+	// actually make sense. Otherwise, the generated json is littered with
+	// golang default values.
+
+	rawConfig := make(map[string]interface{})
+	if err := json.Unmarshal(original.Bytes, &rawConfig); err != nil {
+		return nil, err
+	}
+
+	rawConfigList := map[string]interface{}{
+		"name":       original.Network.Name,
+		"cniVersion": original.Network.CNIVersion,
+		"plugins":    []interface{}{rawConfig},
+	}
+
+	b, err := json.Marshal(rawConfigList)
+	if err != nil {
+		return nil, err
+	}
+	return ConfListFromBytes(b)
 }

libcni/conf_test.go

@@ -0,0 +1,798 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package libcni_test
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	"github.com/containernetworking/cni/libcni"
+	"github.com/containernetworking/cni/pkg/types"
+)
+
+var _ = Describe("Loading configuration from disk", func() {
+	Describe("LoadConf", func() {
+		var (
+			configDir    string
+			pluginConfig []byte
+		)
+
+		BeforeEach(func() {
+			var err error
+			configDir, err = os.MkdirTemp("", "plugin-conf")
+			Expect(err).NotTo(HaveOccurred())
+
+			pluginConfig = []byte(`{ "name": "some-plugin", "type": "foobar", "some-key": "some-value" }`)
+			Expect(os.WriteFile(filepath.Join(configDir, "50-whatever.conf"), pluginConfig, 0o600)).To(Succeed())
+		})
+
+		AfterEach(func() {
+			Expect(os.RemoveAll(configDir)).To(Succeed())
+		})
+
+		It("finds the network config file for the plugin of the given type", func() {
+			netConfig, err := libcni.LoadConf(configDir, "some-plugin")
+			Expect(err).NotTo(HaveOccurred())
+			Expect(netConfig).To(Equal(&libcni.PluginConfig{
+				Network: &types.PluginConf{
+					Name: "some-plugin",
+					Type: "foobar",
+				},
+				Bytes: pluginConfig,
+			}))
+		})
+
+		Context("when the config directory does not exist", func() {
+			BeforeEach(func() {
+				Expect(os.RemoveAll(configDir)).To(Succeed())
+			})
+
+			It("returns a useful error", func() {
+				_, err := libcni.LoadConf(configDir, "some-plugin")
+				Expect(err).To(MatchError(libcni.NoConfigsFoundError{Dir: configDir}))
+			})
+		})
+
+		Context("when the config file is .json extension instead of .conf", func() {
+			BeforeEach(func() {
+				Expect(os.Remove(configDir + "/50-whatever.conf")).To(Succeed())
+				pluginConfig = []byte(`{ "name": "some-plugin", "some-key": "some-value", "type": "foobar" }`)
+				Expect(os.WriteFile(filepath.Join(configDir, "50-whatever.json"), pluginConfig, 0o600)).To(Succeed())
+			})
+			It("finds the network config file for the plugin of the given type", func() {
+				netConfig, err := libcni.LoadConf(configDir, "some-plugin")
+				Expect(err).NotTo(HaveOccurred())
+				Expect(netConfig).To(Equal(&libcni.PluginConfig{
+					Network: &types.PluginConf{
+						Name: "some-plugin",
+						Type: "foobar",
+					},
+					Bytes: pluginConfig,
+				}))
+			})
+		})
+
+		Context("when there is no config for the desired plugin", func() {
+			It("returns a useful error", func() {
+				_, err := libcni.LoadConf(configDir, "some-other-plugin")
+				Expect(err).To(MatchError(ContainSubstring(`no net configuration with name "some-other-plugin" in`)))
+			})
+		})
+
+		Context("when a config file is malformed", func() {
+			BeforeEach(func() {
+				Expect(os.WriteFile(filepath.Join(configDir, "00-bad.conf"), []byte(`{`), 0o600)).To(Succeed())
+			})
+
+			It("returns a useful error", func() {
+				_, err := libcni.LoadConf(configDir, "some-plugin")
+				Expect(err).To(MatchError(`error parsing configuration: unexpected end of JSON input`))
+			})
+		})
+
+		Context("when the config is in a nested subdir", func() {
+			BeforeEach(func() {
+				subdir := filepath.Join(configDir, "subdir1", "subdir2")
+				Expect(os.MkdirAll(subdir, 0o700)).To(Succeed())
+
+				pluginConfig = []byte(`{ "name": "deep", "some-key": "some-value" }`)
+				Expect(os.WriteFile(filepath.Join(subdir, "90-deep.conf"), pluginConfig, 0o600)).To(Succeed())
+			})
+
+			It("will not find the config", func() {
+				_, err := libcni.LoadConf(configDir, "deep")
+				Expect(err).To(MatchError(HavePrefix("no net configuration with name")))
+			})
+		})
+	})
+
+	Describe("Capabilities", func() {
+		var configDir string
+
+		BeforeEach(func() {
+			var err error
+			configDir, err = os.MkdirTemp("", "plugin-conf")
+			Expect(err).NotTo(HaveOccurred())
+
+			pluginConfig := []byte(`{ "name": "some-plugin", "type": "noop", "cniVersion": "0.3.1", "capabilities": { "portMappings": true, "somethingElse": true, "noCapability": false } }`)
+			Expect(os.WriteFile(filepath.Join(configDir, "50-whatever.conf"), pluginConfig, 0o600)).To(Succeed())
+		})
+
+		AfterEach(func() {
+			Expect(os.RemoveAll(configDir)).To(Succeed())
+		})
+
+		It("reads plugin capabilities from network config", func() {
+			netConfig, err := libcni.LoadConf(configDir, "some-plugin")
+			Expect(err).NotTo(HaveOccurred())
+			Expect(netConfig.Network.Capabilities).To(Equal(map[string]bool{
+				"portMappings":  true,
+				"somethingElse": true,
+				"noCapability":  false,
+			}))
+		})
+	})
+
+	Describe("ConfFromFile", func() {
+		Context("when the file cannot be opened", func() {
+			It("returns a useful error", func() {
+				_, err := libcni.ConfFromFile("/tmp/nope/not-here")
+				Expect(err).To(MatchError(HavePrefix(`error reading /tmp/nope/not-here: open /tmp/nope/not-here`)))
+			})
+		})
+
+		Context("when the file is missing 'type'", func() {
+			var fileName, configDir string
+			BeforeEach(func() {
+				var err error
+				configDir, err = os.MkdirTemp("", "plugin-conf")
+				Expect(err).NotTo(HaveOccurred())
+
+				fileName = filepath.Join(configDir, "50-whatever.conf")
+				pluginConfig := []byte(`{ "name": "some-plugin", "some-key": "some-value" }`)
+				Expect(os.WriteFile(fileName, pluginConfig, 0o600)).To(Succeed())
+			})
+
+			AfterEach(func() {
+				Expect(os.RemoveAll(configDir)).To(Succeed())
+			})
+
+			It("returns a useful error", func() {
+				_, err := libcni.ConfFromFile(fileName)
+				Expect(err).To(MatchError(`error parsing configuration: missing 'type'`))
+			})
+		})
+	})
+
+	Describe("NetworkPluginConfFromBytes", func() {
+		Context("when the config is missing 'type'", func() {
+			It("returns a useful error", func() {
+				_, err := libcni.ConfFromBytes([]byte(`{ "name": "some-plugin", "some-key": "some-value" }`))
+				Expect(err).To(MatchError(`error parsing configuration: missing 'type'`))
+			})
+		})
+	})
+
+	Describe("LoadNetworkConf", func() {
+		var (
+			configDir  string
+			configList []byte
+		)
+
+		BeforeEach(func() {
+			var err error
+			configDir, err = os.MkdirTemp("", "plugin-conf")
+			Expect(err).NotTo(HaveOccurred())
+
+			configList = []byte(`{
+  "name": "some-network",
+  "cniVersion": "0.2.0",
+  "disableCheck": true,
+  "plugins": [
+    {
+      "type": "host-local",
+      "subnet": "10.0.0.1/24"
+    },
+    {
+      "type": "bridge",
+      "mtu": 1400
+    },
+    {
+      "type": "port-forwarding",
+      "ports": {"20.0.0.1:8080": "80"}
+    }
+  ]
+}`)
+			Expect(os.WriteFile(filepath.Join(configDir, "50-whatever.conflist"), configList, 0o600)).To(Succeed())
+		})
+
+		AfterEach(func() {
+			Expect(os.RemoveAll(configDir)).To(Succeed())
+		})
+
+		It("finds the network config file for the plugin of the given type", func() {
+			netConfigList, err := libcni.LoadNetworkConf(configDir, "some-network")
+			Expect(err).NotTo(HaveOccurred())
+			Expect(netConfigList).To(Equal(&libcni.NetworkConfigList{
+				Name:         "some-network",
+				CNIVersion:   "0.2.0",
+				DisableCheck: true,
+				Plugins: []*libcni.PluginConfig{
+					{
+						Network: &types.PluginConf{Type: "host-local"},
+						Bytes:   []byte(`{"subnet":"10.0.0.1/24","type":"host-local"}`),
+					},
+					{
+						Network: &types.PluginConf{Type: "bridge"},
+						Bytes:   []byte(`{"mtu":1400,"type":"bridge"}`),
+					},
+					{
+						Network: &types.PluginConf{Type: "port-forwarding"},
+						Bytes:   []byte(`{"ports":{"20.0.0.1:8080":"80"},"type":"port-forwarding"}`),
+					},
+				},
+				Bytes: configList,
+			}))
+		})
+
+		Context("when there is a config file with the same name as the list", func() {
+			BeforeEach(func() {
+				configFile := []byte(`{
+					"name": "some-network",
+					"cniVersion": "0.2.0",
+					"type": "bridge"
+				}`)
+				Expect(os.WriteFile(filepath.Join(configDir, "49-whatever.conf"), configFile, 0o600)).To(Succeed())
+			})
+
+			It("Loads the config list first", func() {
+				netConfigList, err := libcni.LoadNetworkConf(configDir, "some-network")
+				Expect(err).NotTo(HaveOccurred())
+				Expect(netConfigList.Plugins).To(HaveLen(3))
+			})
+
+			It("falls back to the config file", func() {
+				Expect(os.Remove(filepath.Join(configDir, "50-whatever.conflist"))).To(Succeed())
+
+				netConfigList, err := libcni.LoadNetworkConf(configDir, "some-network")
+				Expect(err).NotTo(HaveOccurred())
+				Expect(netConfigList.Plugins).To(HaveLen(1))
+				Expect(netConfigList.Plugins[0].Network.Type).To(Equal("bridge"))
+			})
+		})
+
+		Context("when the config directory does not exist", func() {
+			BeforeEach(func() {
+				Expect(os.RemoveAll(configDir)).To(Succeed())
+			})
+
+			It("returns a useful error", func() {
+				_, err := libcni.LoadNetworkConf(configDir, "some-network")
+				Expect(err).To(MatchError(libcni.NoConfigsFoundError{Dir: configDir}))
+			})
+		})
+
+		Context("when there is no config for the desired network name", func() {
+			It("returns a useful error", func() {
+				_, err := libcni.LoadNetworkConf(configDir, "some-other-network")
+				Expect(err).To(MatchError(libcni.NotFoundError{Dir: configDir, Name: "some-other-network"}))
+			})
+		})
+
+		Context("when a config file is malformed", func() {
+			BeforeEach(func() {
+				Expect(os.WriteFile(filepath.Join(configDir, "00-bad.conflist"), []byte(`{`), 0o600)).To(Succeed())
+			})
+
+			It("returns a useful error", func() {
+				_, err := libcni.LoadNetworkConf(configDir, "some-plugin")
+				Expect(err).To(MatchError(`error parsing configuration list: unexpected end of JSON input`))
+			})
+		})
+
+		Context("when the config is in a nested subdir", func() {
+			BeforeEach(func() {
+				subdir := filepath.Join(configDir, "subdir1", "subdir2")
+				Expect(os.MkdirAll(subdir, 0o700)).To(Succeed())
+
+				configList = []byte(`{
+  "name": "deep",
+  "cniVersion": "0.2.0",
+  "plugins": [
+    {
+      "type": "host-local",
+      "subnet": "10.0.0.1/24"
+    },
+  ]
+}`)
+				Expect(os.WriteFile(filepath.Join(subdir, "90-deep.conflist"), configList, 0o600)).To(Succeed())
+			})
+
+			It("will not find the config", func() {
+				_, err := libcni.LoadNetworkConf(configDir, "deep")
+				Expect(err).To(MatchError(HavePrefix("no net configuration with name")))
+			})
+		})
+
+		Context("when disableCheck is a string not a boolean", func() {
+			It("will read a 'true' value and convert to boolean", func() {
+				configList = []byte(`{
+				  "name": "some-network",
+				  "cniVersion": "0.4.0",
+				  "disableCheck": "true",
+				  "plugins": [
+				    {
+				      "type": "host-local",
+				      "subnet": "10.0.0.1/24"
+				    }
+				  ]
+				}`)
+				Expect(os.WriteFile(filepath.Join(configDir, "50-whatever.conflist"), configList, 0o600)).To(Succeed())
+
+				netConfigList, err := libcni.LoadNetworkConf(configDir, "some-network")
+				Expect(err).NotTo(HaveOccurred())
+				Expect(netConfigList.DisableCheck).To(BeTrue())
+			})
+
+			It("will read a 'false' value and convert to boolean", func() {
+				configList = []byte(`{
+				  "name": "some-network",
+				  "cniVersion": "0.4.0",
+				  "disableCheck": "false",
+				  "plugins": [
+				    {
+				      "type": "host-local",
+				      "subnet": "10.0.0.1/24"
+				    }
+				  ]
+				}`)
+				Expect(os.WriteFile(filepath.Join(configDir, "50-whatever.conflist"), configList, 0o600)).To(Succeed())
+
+				netConfigList, err := libcni.LoadNetworkConf(configDir, "some-network")
+				Expect(err).NotTo(HaveOccurred())
+				Expect(netConfigList.DisableCheck).To(BeFalse())
+			})
+
+			It("will return an error on an unrecognized value", func() {
+				const badValue string = "adsfasdfasf"
+				configList = []byte(fmt.Sprintf(`{
+				  "name": "some-network",
+				  "cniVersion": "0.4.0",
+				  "disableCheck": "%s",
+				  "plugins": [
+				    {
+				      "type": "host-local",
+				      "subnet": "10.0.0.1/24"
+				    }
+				  ]
+				}`, badValue))
+				Expect(os.WriteFile(filepath.Join(configDir, "50-whatever.conflist"), configList, 0o600)).To(Succeed())
+
+				_, err := libcni.LoadNetworkConf(configDir, "some-network")
+				Expect(err).To(MatchError(fmt.Sprintf("error parsing configuration list: invalid value \"%s\" for disableCheck", badValue)))
+			})
+		})
+
+		Context("for loadOnlyInlinedPlugins", func() {
+			It("the value will be parsed", func() {
+				configList = []byte(`{
+				  "name": "some-network",
+				  "cniVersion": "0.4.0",
+				  "loadOnlyInlinedPlugins": true,
+				  "plugins": [
+				    {
+				      "type": "host-local",
+				      "subnet": "10.0.0.1/24"
+				    }
+				  ]
+				}`)
+				Expect(os.WriteFile(filepath.Join(configDir, "50-whatever.conflist"), configList, 0o600)).To(Succeed())
+
+				dirPluginConf := []byte(`{
+				      "type": "bro-check-out-my-plugin",
+				      "subnet": "10.0.0.1/24"
+				}`)
+
+				subDir := filepath.Join(configDir, "some-network")
+				Expect(os.MkdirAll(subDir, 0o700)).To(Succeed())
+				Expect(os.WriteFile(filepath.Join(subDir, "funky-second-plugin.conf"), dirPluginConf, 0o600)).To(Succeed())
+
+				netConfigList, err := libcni.LoadNetworkConf(configDir, "some-network")
+				Expect(err).NotTo(HaveOccurred())
+				Expect(netConfigList.LoadOnlyInlinedPlugins).To(BeTrue())
+			})
+
+			It("the value will be false if not in config", func() {
+				configList = []byte(`{
+				  "name": "some-network",
+				  "cniVersion": "0.4.0",
+				  "plugins": [
+				    {
+				      "type": "host-local",
+				      "subnet": "10.0.0.1/24"
+				    }
+				  ]
+				}`)
+				Expect(os.WriteFile(filepath.Join(configDir, "50-whatever.conflist"), configList, 0o600)).To(Succeed())
+
+				netConfigList, err := libcni.LoadNetworkConf(configDir, "some-network")
+				Expect(err).NotTo(HaveOccurred())
+				Expect(netConfigList.LoadOnlyInlinedPlugins).To(BeFalse())
+			})
+
+			It("will return an error on an unrecognized value", func() {
+				const badValue string = "sphagnum"
+				configList = []byte(fmt.Sprintf(`{
+				  "name": "some-network",
+				  "cniVersion": "0.4.0",
+				  "loadOnlyInlinedPlugins": "%s",
+				  "plugins": [
+				    {
+				      "type": "host-local",
+				      "subnet": "10.0.0.1/24"
+				    }
+				  ]
+				}`, badValue))
+				Expect(os.WriteFile(filepath.Join(configDir, "50-whatever.conflist"), configList, 0o600)).To(Succeed())
+
+				_, err := libcni.LoadNetworkConf(configDir, "some-network")
+				Expect(err).To(MatchError(fmt.Sprintf(`error parsing configuration list: invalid value "%s" for loadOnlyInlinedPlugins`, badValue)))
+			})
+
+			It("will return an error if `plugins` is missing and `loadOnlyInlinedPlugins` is `true`", func() {
+				configList = []byte(`{
+				  "name": "some-network",
+				  "cniVersion": "0.4.0",
+				  "loadOnlyInlinedPlugins": true
+				}`)
+				Expect(os.WriteFile(filepath.Join(configDir, "50-whatever.conflist"), configList, 0o600)).To(Succeed())
+
+				_, err := libcni.LoadNetworkConf(configDir, "some-network")
+				Expect(err).To(MatchError("error parsing configuration list: `loadOnlyInlinedPlugins` is true, and no 'plugins' key"))
+			})
+
+			It("will return no error if `plugins` is missing and `loadOnlyInlinedPlugins` is false", func() {
+				configList = []byte(`{
+				  "name": "some-network",
+				  "cniVersion": "0.4.0",
+				  "loadOnlyInlinedPlugins": false
+				}`)
+				Expect(os.WriteFile(filepath.Join(configDir, "50-whatever.conflist"), configList, 0o600)).To(Succeed())
+
+				dirPluginConf := []byte(`{
+				      "type": "bro-check-out-my-plugin",
+				      "subnet": "10.0.0.1/24"
+				}`)
+
+				subDir := filepath.Join(configDir, "some-network")
+				Expect(os.MkdirAll(subDir, 0o700)).To(Succeed())
+				Expect(os.WriteFile(filepath.Join(subDir, "funky-second-plugin.conf"), dirPluginConf, 0o600)).To(Succeed())
+
+				netConfigList, err := libcni.LoadNetworkConf(configDir, "some-network")
+				Expect(err).NotTo(HaveOccurred())
+				Expect(netConfigList.LoadOnlyInlinedPlugins).To(BeFalse())
+				Expect(netConfigList.Plugins).To(HaveLen(1))
+			})
+
+			It("will return error if `loadOnlyInlinedPlugins` is implicitly false + no conf plugin is defined, but no plugins subfolder with network name exists", func() {
+				configList = []byte(`{
+				  "name": "some-network",
+				  "cniVersion": "0.4.0"
+				}`)
+				Expect(os.WriteFile(filepath.Join(configDir, "50-whatever.conflist"), configList, 0o600)).To(Succeed())
+
+				_, err := libcni.LoadNetworkConf(configDir, "some-network")
+				Expect(err).To(MatchError("no plugin configs found"))
+			})
+
+			It("will return NO error if `loadOnlyInlinedPlugins` is implicitly false + at least 1 conf plugin is defined, but no plugins subfolder with network name exists", func() {
+				configList = []byte(`{
+				  "name": "some-network",
+				  "cniVersion": "0.4.0",
+				  "plugins": [
+				    {
+				      "type": "host-local",
+				      "subnet": "10.0.0.1/24"
+				    }
+				  ]
+				}`)
+				Expect(os.WriteFile(filepath.Join(configDir, "50-whatever.conflist"), configList, 0o600)).To(Succeed())
+
+				_, err := libcni.LoadNetworkConf(configDir, "some-network")
+				Expect(err).NotTo(HaveOccurred())
+			})
+
+			It("will return NO error if `loadOnlyInlinedPlugins` is implicitly false + at least 1 conf plugin is defined and network name subfolder exists, but is empty/unreadable", func() {
+				configList = []byte(`{
+				  "name": "some-network",
+				  "cniVersion": "0.4.0",
+				  "plugins": [
+				    {
+				      "type": "host-local",
+				      "subnet": "10.0.0.1/24"
+				    }
+				  ]
+				}`)
+				Expect(os.WriteFile(filepath.Join(configDir, "50-whatever.conflist"), configList, 0o600)).To(Succeed())
+
+				subDir := filepath.Join(configDir, "some-network")
+				Expect(os.MkdirAll(subDir, 0o700)).To(Succeed())
+
+				_, err := libcni.LoadNetworkConf(configDir, "some-network")
+				Expect(err).NotTo(HaveOccurred())
+			})
+
+			It("will merge loaded and inlined plugin lists if both `plugins` is set and `loadOnlyInlinedPlugins` is false", func() {
+				configList = []byte(`{
+				  "name": "some-network",
+				  "cniVersion": "0.4.0",
+				  "plugins": [
+				    {
+				      "type": "host-local",
+				      "subnet": "10.0.0.1/24"
+				    }
+	          	  ]
+				}`)
+
+				dirPluginConf := []byte(`{
+				      "type": "bro-check-out-my-plugin",
+				      "subnet": "10.0.0.1/24"
+				}`)
+
+				Expect(os.WriteFile(filepath.Join(configDir, "50-whatever.conflist"), configList, 0o600)).To(Succeed())
+
+				subDir := filepath.Join(configDir, "some-network")
+				Expect(os.MkdirAll(subDir, 0o700)).To(Succeed())
+				Expect(os.WriteFile(filepath.Join(subDir, "funky-second-plugin.conf"), dirPluginConf, 0o600)).To(Succeed())
+
+				netConfigList, err := libcni.LoadNetworkConf(configDir, "some-network")
+				Expect(err).NotTo(HaveOccurred())
+				Expect(netConfigList.LoadOnlyInlinedPlugins).To(BeFalse())
+				Expect(netConfigList.Plugins).To(HaveLen(2))
+			})
+
+			It("will ignore loaded plugins if `plugins` is set and `loadOnlyInlinedPlugins` is true", func() {
+				configList = []byte(`{
+				  "name": "some-network",
+				  "cniVersion": "0.4.0",
+				  "loadOnlyInlinedPlugins": true,
+				  "plugins": [
+				    {
+				      "type": "host-local",
+				      "subnet": "10.0.0.1/24"
+				    }
+	          	  ]
+				}`)
+
+				dirPluginConf := []byte(`{
+				      "type": "bro-check-out-my-plugin",
+				      "subnet": "10.0.0.1/24"
+				}`)
+
+				Expect(os.WriteFile(filepath.Join(configDir, "50-whatever.conflist"), configList, 0o600)).To(Succeed())
+				subDir := filepath.Join(configDir, "some-network")
+				Expect(os.MkdirAll(subDir, 0o700)).To(Succeed())
+				Expect(os.WriteFile(filepath.Join(subDir, "funky-second-plugin.conf"), dirPluginConf, 0o600)).To(Succeed())
+
+				netConfigList, err := libcni.LoadNetworkConf(configDir, "some-network")
+				Expect(err).NotTo(HaveOccurred())
+				Expect(netConfigList.LoadOnlyInlinedPlugins).To(BeTrue())
+				Expect(netConfigList.Plugins).To(HaveLen(1))
+				Expect(netConfigList.Plugins[0].Network.Type).To(Equal("host-local"))
+			})
+		})
+	})
+
+	Describe("NetworkConfFromFile", func() {
+		Context("when the file cannot be opened", func() {
+			It("returns a useful error", func() {
+				_, err := libcni.NetworkConfFromFile("/tmp/nope/not-here")
+				Expect(err).To(MatchError(HavePrefix(`error reading /tmp/nope/not-here: open /tmp/nope/not-here`)))
+			})
+		})
+	})
+
+	Describe("InjectConf", func() {
+		var testNetConfig *libcni.PluginConfig
+
+		BeforeEach(func() {
+			testNetConfig = &libcni.PluginConfig{
+				Network: &types.PluginConf{Name: "some-plugin", Type: "foobar"},
+				Bytes:   []byte(`{ "name": "some-plugin", "type": "foobar" }`),
+			}
+		})
+
+		Context("when function parameters are incorrect", func() {
+			It("returns unmarshal error", func() {
+				conf := &libcni.PluginConfig{
+					Network: &types.PluginConf{Name: "some-plugin"},
+					Bytes:   []byte(`{ cc cc cc}`),
+				}
+
+				_, err := libcni.InjectConf(conf, map[string]interface{}{"": nil})
+				Expect(err).To(MatchError(HavePrefix(`unmarshal existing network bytes`)))
+			})
+
+			It("returns key  error", func() {
+				_, err := libcni.InjectConf(testNetConfig, map[string]interface{}{"": nil})
+				Expect(err).To(MatchError(HavePrefix(`keys cannot be empty`)))
+			})
+
+			It("returns newValue  error", func() {
+				_, err := libcni.InjectConf(testNetConfig, map[string]interface{}{"test": nil})
+				Expect(err).To(MatchError(HavePrefix(`key 'test' value must not be nil`)))
+			})
+		})
+
+		Context("when new string value added", func() {
+			It("adds the new key & value to the config", func() {
+				newPluginConfig := []byte(`{"name":"some-plugin","test":"test","type":"foobar"}`)
+
+				resultConfig, err := libcni.InjectConf(testNetConfig, map[string]interface{}{"test": "test"})
+				Expect(err).NotTo(HaveOccurred())
+				Expect(resultConfig).To(Equal(&libcni.PluginConfig{
+					Network: &types.PluginConf{
+						Name: "some-plugin",
+						Type: "foobar",
+					},
+					Bytes: newPluginConfig,
+				}))
+			})
+
+			It("adds the new value for exiting key", func() {
+				newPluginConfig := []byte(`{"name":"some-plugin","test":"changedValue","type":"foobar"}`)
+
+				resultConfig, err := libcni.InjectConf(testNetConfig, map[string]interface{}{"test": "test"})
+				Expect(err).NotTo(HaveOccurred())
+
+				resultConfig, err = libcni.InjectConf(resultConfig, map[string]interface{}{"test": "changedValue"})
+				Expect(err).NotTo(HaveOccurred())
+
+				Expect(resultConfig).To(Equal(&libcni.PluginConfig{
+					Network: &types.PluginConf{
+						Name: "some-plugin",
+						Type: "foobar",
+					},
+					Bytes: newPluginConfig,
+				}))
+			})
+
+			It("adds existing key & value", func() {
+				newPluginConfig := []byte(`{"name":"some-plugin","test":"test","type":"foobar"}`)
+
+				resultConfig, err := libcni.InjectConf(testNetConfig, map[string]interface{}{"test": "test"})
+				Expect(err).NotTo(HaveOccurred())
+
+				resultConfig, err = libcni.InjectConf(resultConfig, map[string]interface{}{"test": "test"})
+				Expect(err).NotTo(HaveOccurred())
+
+				Expect(resultConfig).To(Equal(&libcni.PluginConfig{
+					Network: &types.PluginConf{
+						Name: "some-plugin",
+						Type: "foobar",
+					},
+					Bytes: newPluginConfig,
+				}))
+			})
+
+			It("adds sub-fields of NetworkConfig.Network to the config", func() {
+				expectedPluginConfig := []byte(`{"dns":{"domain":"local","nameservers":["server1","server2"]},"name":"some-plugin","type":"bridge"}`)
+				servers := []string{"server1", "server2"}
+				newDNS := &types.DNS{Nameservers: servers, Domain: "local"}
+
+				// inject DNS
+				resultConfig, err := libcni.InjectConf(testNetConfig, map[string]interface{}{"dns": newDNS})
+				Expect(err).NotTo(HaveOccurred())
+
+				// inject type
+				resultConfig, err = libcni.InjectConf(resultConfig, map[string]interface{}{"type": "bridge"})
+				Expect(err).NotTo(HaveOccurred())
+
+				Expect(resultConfig).To(Equal(&libcni.PluginConfig{
+					Network: &types.PluginConf{Name: "some-plugin", Type: "bridge", DNS: types.DNS{Nameservers: servers, Domain: "local"}},
+					Bytes:   expectedPluginConfig,
+				}))
+			})
+		})
+	})
+})
+
+var _ = Describe("NetworkConfFromBytes", func() {
+	Describe("Version selection", func() {
+		makeConfig := func(versions ...string) []byte {
+			// ugly fake json encoding, but whatever
+			vs := []string{}
+			for _, v := range versions {
+				vs = append(vs, fmt.Sprintf(`"%s"`, v))
+			}
+			return []byte(fmt.Sprintf(`{"name": "test", "cniVersions": [%s], "plugins": [{"type": "foo"}]}`, strings.Join(vs, ",")))
+		}
+		It("correctly selects the maximum version", func() {
+			conf, err := libcni.NetworkConfFromBytes(makeConfig("1.1.0", "0.4.0", "1.0.0"))
+			Expect(err).NotTo(HaveOccurred())
+			Expect(conf.CNIVersion).To(Equal("1.1.0"))
+		})
+
+		It("selects the highest version supported by libcni", func() {
+			conf, err := libcni.NetworkConfFromBytes(makeConfig("99.0.0", "1.1.0", "0.4.0", "1.0.0"))
+			Expect(err).NotTo(HaveOccurred())
+			Expect(conf.CNIVersion).To(Equal("1.1.0"))
+		})
+
+		It("fails when invalid versions are specified", func() {
+			_, err := libcni.NetworkConfFromBytes(makeConfig("1.1.0", "0.4.0", "1.0.f"))
+			Expect(err).To(HaveOccurred())
+		})
+
+		It("falls back to cniVersion", func() {
+			conf, err := libcni.NetworkConfFromBytes([]byte(`{"name": "test", "cniVersion": "1.2.3", "plugins": [{"type": "foo"}]}`))
+			Expect(err).NotTo(HaveOccurred())
+			Expect(conf.CNIVersion).To(Equal("1.2.3"))
+		})
+
+		It("merges cniVersions and cniVersion", func() {
+			conf, err := libcni.NetworkConfFromBytes([]byte(`{"name": "test", "cniVersion": "1.0.0", "cniVersions": ["0.1.0", "0.4.0"], "plugins": [{"type": "foo"}]}`))
+			Expect(err).NotTo(HaveOccurred())
+			Expect(conf.CNIVersion).To(Equal("1.0.0"))
+		})
+
+		It("handles an empty cniVersions array", func() {
+			conf, err := libcni.NetworkConfFromBytes([]byte(`{"name": "test", "cniVersions": [], "plugins": [{"type": "foo"}]}`))
+			Expect(err).NotTo(HaveOccurred())
+			Expect(conf.CNIVersion).To(Equal(""))
+		})
+	})
+})
+
+var _ = Describe("ConfListFromConf", func() {
+	var testNetConfig *libcni.PluginConfig
+
+	BeforeEach(func() {
+		pb := []byte(`{"name":"some-plugin","cniVersion":"0.3.1", "type":"foobar"}`)
+		tc, err := libcni.ConfFromBytes(pb)
+		Expect(err).NotTo(HaveOccurred())
+		testNetConfig = tc
+	})
+
+	It("correctly upconverts a NetworkConfig to a NetworkConfigList", func() {
+		ncl, err := libcni.ConfListFromConf(testNetConfig)
+		Expect(err).NotTo(HaveOccurred())
+		bytes := ncl.Bytes
+
+		// null out the json - we don't care about the exact marshalling
+		ncl.Bytes = nil
+		ncl.Plugins[0].Bytes = nil
+		testNetConfig.Bytes = nil
+
+		Expect(ncl).To(Equal(&libcni.NetworkConfigList{
+			Name:       "some-plugin",
+			CNIVersion: "0.3.1",
+			Plugins:    []*libcni.PluginConfig{testNetConfig},
+		}))
+
+		// Test that the json unmarshals to the same data
+		ncl2, err := libcni.NetworkConfFromBytes(bytes)
+		Expect(err).NotTo(HaveOccurred())
+		ncl2.Bytes = nil
+		ncl2.Plugins[0].Bytes = nil
+
+		Expect(ncl2).To(Equal(ncl))
+	})
+})

libcni/libcni_suite_test.go

@@ -0,0 +1,62 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package libcni_test
+
+import (
+	"encoding/json"
+	"path/filepath"
+	"testing"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"github.com/onsi/gomega/gexec"
+)
+
+func TestLibcni(t *testing.T) {
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "Libcni Suite")
+}
+
+var pluginPackages = map[string]string{
+	"noop":  "github.com/containernetworking/cni/plugins/test/noop",
+	"sleep": "github.com/containernetworking/cni/plugins/test/sleep",
+}
+
+var (
+	pluginPaths map[string]string
+	pluginDirs  []string // array of plugin dirs
+)
+
+var _ = SynchronizedBeforeSuite(func() []byte {
+	paths := map[string]string{}
+	for name, packagePath := range pluginPackages {
+		execPath, err := gexec.Build(packagePath)
+		Expect(err).NotTo(HaveOccurred())
+		paths[name] = execPath
+	}
+	crossNodeData, err := json.Marshal(paths)
+	Expect(err).NotTo(HaveOccurred())
+
+	return crossNodeData
+}, func(crossNodeData []byte) {
+	Expect(json.Unmarshal(crossNodeData, &pluginPaths)).To(Succeed())
+	for _, pluginPath := range pluginPaths {
+		pluginDirs = append(pluginDirs, filepath.Dir(pluginPath))
+	}
+})
+
+var _ = SynchronizedAfterSuite(func() {}, func() {
+	gexec.CleanupBuildArtifacts()
+})

mk/dependencies/golangci.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+set -e
+
+GOLANGCI_LINT_VERSION="v1.57.1"
+
+go install "github.com/golangci/golangci-lint/cmd/golangci-lint@${GOLANGCI_LINT_VERSION}"

mk/lint.mk

@@ -0,0 +1,14 @@
+.PHONY: lint
+lint: golangci/install golangci/lint
+
+.PHONY: golangci/install
+golangci/install:
+	./mk/dependencies/golangci.sh
+
+.PHONY: golangci/lint
+golangci/lint:
+	golangci-lint run --verbose
+
+.PHONY: golangci/fix
+golangci/fix:
+	golangci-lint run --verbose --fix

pkg/invoke/args.go

@@ -15,6 +15,7 @@
 package invoke
 
 import (
+	"fmt"
 	"os"
 	"strings"
 )
@@ -22,6 +23,8 @@ import (
 type CNIArgs interface {
 	// For use with os/exec; i.e., return nil to inherit the
 	// environment from this process
+	// For use in delegation; inherit the environment from this
+	// process and allow overrides
 	AsEnv() []string
 }
 
@@ -29,7 +32,7 @@ type inherited struct{}
 
 var inheritArgsFromEnv inherited
 
-func (_ *inherited) AsEnv() []string {
+func (*inherited) AsEnv() []string {
 	return nil
 }
 
@@ -47,6 +50,9 @@ type Args struct {
 	Path          string
 }
 
+// Args implements the CNIArgs interface
+var _ CNIArgs = &Args{}
+
 func (args *Args) AsEnv() []string {
 	env := os.Environ()
 	pluginArgsStr := args.PluginArgsStr
@@ -54,14 +60,17 @@ func (args *Args) AsEnv() []string {
 		pluginArgsStr = stringify(args.PluginArgs)
 	}
 
+	// Duplicated values which come first will be overridden, so we must put the
+	// custom values in the end to avoid being overridden by the process environments.
 	env = append(env,
 		"CNI_COMMAND="+args.Command,
 		"CNI_CONTAINERID="+args.ContainerID,
 		"CNI_NETNS="+args.NetNS,
 		"CNI_ARGS="+pluginArgsStr,
 		"CNI_IFNAME="+args.IfName,
-		"CNI_PATH="+args.Path)
-	return env
+		"CNI_PATH="+args.Path,
+	)
+	return dedupEnv(env)
 }
 
 // taken from rkt/networking/net_plugin.go
@@ -74,3 +83,46 @@ func stringify(pluginArgs [][2]string) string {
 
 	return strings.Join(entries, ";")
 }
+
+// DelegateArgs implements the CNIArgs interface
+// used for delegation to inherit from environments
+// and allow some overrides like CNI_COMMAND
+var _ CNIArgs = &DelegateArgs{}
+
+type DelegateArgs struct {
+	Command string
+}
+
+func (d *DelegateArgs) AsEnv() []string {
+	env := os.Environ()
+
+	// The custom values should come in the end to override the existing
+	// process environment of the same key.
+	env = append(env,
+		"CNI_COMMAND="+d.Command,
+	)
+	return dedupEnv(env)
+}
+
+// dedupEnv returns a copy of env with any duplicates removed, in favor of later values.
+// Items not of the normal environment "key=value" form are preserved unchanged.
+func dedupEnv(env []string) []string {
+	out := make([]string, 0, len(env))
+	envMap := map[string]string{}
+
+	for _, kv := range env {
+		// find the first "=" in environment, if not, just keep it
+		eq := strings.Index(kv, "=")
+		if eq < 0 {
+			out = append(out, kv)
+			continue
+		}
+		envMap[kv[:eq]] = kv[eq+1:]
+	}
+
+	for k, v := range envMap {
+		out = append(out, fmt.Sprintf("%s=%s", k, v))
+	}
+
+	return out
+}

pkg/invoke/args_test.go

@@ -0,0 +1,139 @@
+// Copyright 2017 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package invoke_test
+
+import (
+	"os"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	"github.com/containernetworking/cni/pkg/invoke"
+)
+
+var _ = Describe("CNIArgs AsEnv", func() {
+	Describe("Args AsEnv", func() {
+		BeforeEach(func() {
+			os.Setenv("CNI_COMMAND", "DEL")
+			os.Setenv("CNI_IFNAME", "eth0")
+			os.Setenv("CNI_CONTAINERID", "id")
+			os.Setenv("CNI_ARGS", "args")
+			os.Setenv("CNI_NETNS", "testns")
+			os.Setenv("CNI_PATH", "testpath")
+		})
+
+		It("places the CNI environment variables in the end to be prepended", func() {
+			args := invoke.Args{
+				Command:     "ADD",
+				ContainerID: "some-container-id",
+				NetNS:       "/some/netns/path",
+				PluginArgs: [][2]string{
+					{"KEY1", "VALUE1"},
+					{"KEY2", "VALUE2"},
+				},
+				IfName: "eth7",
+				Path:   "/some/cni/path",
+			}
+
+			latentEnvs := os.Environ()
+			numLatentEnvs := len(latentEnvs)
+
+			cniEnvs := args.AsEnv()
+			Expect(cniEnvs).To(HaveLen(numLatentEnvs))
+
+			Expect(inStringSlice("CNI_COMMAND=ADD", cniEnvs)).To(BeTrue())
+			Expect(inStringSlice("CNI_IFNAME=eth7", cniEnvs)).To(BeTrue())
+			Expect(inStringSlice("CNI_CONTAINERID=some-container-id", cniEnvs)).To(BeTrue())
+			Expect(inStringSlice("CNI_NETNS=/some/netns/path", cniEnvs)).To(BeTrue())
+			Expect(inStringSlice("CNI_ARGS=KEY1=VALUE1;KEY2=VALUE2", cniEnvs)).To(BeTrue())
+			Expect(inStringSlice("CNI_PATH=/some/cni/path", cniEnvs)).To(BeTrue())
+
+			Expect(inStringSlice("CNI_COMMAND=DEL", cniEnvs)).To(BeFalse())
+			Expect(inStringSlice("CNI_IFNAME=eth0", cniEnvs)).To(BeFalse())
+			Expect(inStringSlice("CNI_CONTAINERID=id", cniEnvs)).To(BeFalse())
+			Expect(inStringSlice("CNI_NETNS=testns", cniEnvs)).To(BeFalse())
+			Expect(inStringSlice("CNI_ARGS=args", cniEnvs)).To(BeFalse())
+			Expect(inStringSlice("CNI_PATH=testpath", cniEnvs)).To(BeFalse())
+		})
+
+		AfterEach(func() {
+			os.Unsetenv("CNI_COMMAND")
+			os.Unsetenv("CNI_IFNAME")
+			os.Unsetenv("CNI_CONTAINERID")
+			os.Unsetenv("CNI_ARGS")
+			os.Unsetenv("CNI_NETNS")
+			os.Unsetenv("CNI_PATH")
+		})
+	})
+
+	Describe("DelegateArgs AsEnv", func() {
+		BeforeEach(func() {
+			os.Unsetenv("CNI_COMMAND")
+		})
+
+		It("override CNI_COMMAND if it already exists in environment variables", func() {
+			os.Setenv("CNI_COMMAND", "DEL")
+
+			delegateArgs := invoke.DelegateArgs{
+				Command: "ADD",
+			}
+
+			latentEnvs := os.Environ()
+			numLatentEnvs := len(latentEnvs)
+
+			cniEnvs := delegateArgs.AsEnv()
+			Expect(cniEnvs).To(HaveLen(numLatentEnvs))
+
+			Expect(inStringSlice("CNI_COMMAND=ADD", cniEnvs)).To(BeTrue())
+			Expect(inStringSlice("CNI_COMMAND=DEL", cniEnvs)).To(BeFalse())
+		})
+
+		It("append CNI_COMMAND if it does not exist in environment variables", func() {
+			delegateArgs := invoke.DelegateArgs{
+				Command: "ADD",
+			}
+
+			latentEnvs := os.Environ()
+			numLatentEnvs := len(latentEnvs)
+
+			cniEnvs := delegateArgs.AsEnv()
+			Expect(cniEnvs).To(HaveLen(numLatentEnvs + 1))
+
+			Expect(inStringSlice("CNI_COMMAND=ADD", cniEnvs)).To(BeTrue())
+		})
+
+		AfterEach(func() {
+			os.Unsetenv("CNI_COMMAND")
+		})
+	})
+
+	Describe("inherited AsEnv", func() {
+		It("return nil string slice if we call AsEnv of inherited", func() {
+			inheritedArgs := invoke.ArgsFromEnv()
+
+			var nilSlice []string = nil
+			Expect(inheritedArgs.AsEnv()).To(Equal(nilSlice))
+		})
+	})
+})
+
+func inStringSlice(in string, slice []string) bool {
+	for _, s := range slice {
+		if in == s {
+			return true
+		}
+	}
+	return false
+}

pkg/invoke/delegate.go

@@ -15,39 +15,75 @@
 package invoke
 
 import (
-	"fmt"
+	"context"
 	"os"
-	"strings"
+	"path/filepath"
 
 	"github.com/containernetworking/cni/pkg/types"
 )
 
-func DelegateAdd(delegatePlugin string, netconf []byte) (*types.Result, error) {
-	if os.Getenv("CNI_COMMAND") != "ADD" {
-		return nil, fmt.Errorf("CNI_COMMAND is not ADD")
+func delegateCommon(delegatePlugin string, exec Exec) (string, Exec, error) {
+	if exec == nil {
+		exec = defaultExec
 	}
 
-	paths := strings.Split(os.Getenv("CNI_PATH"), ":")
+	paths := filepath.SplitList(os.Getenv("CNI_PATH"))
+	pluginPath, err := exec.FindInPath(delegatePlugin, paths)
+	if err != nil {
+		return "", nil, err
+	}
 
-	pluginPath, err := FindInPath(delegatePlugin, paths)
+	return pluginPath, exec, nil
+}
+
+// DelegateAdd calls the given delegate plugin with the CNI ADD action and
+// JSON configuration
+func DelegateAdd(ctx context.Context, delegatePlugin string, netconf []byte, exec Exec) (types.Result, error) {
+	pluginPath, realExec, err := delegateCommon(delegatePlugin, exec)
 	if err != nil {
 		return nil, err
 	}
 
-	return ExecPluginWithResult(pluginPath, netconf, ArgsFromEnv())
+	// DelegateAdd will override the original "CNI_COMMAND" env from process with ADD
+	return ExecPluginWithResult(ctx, pluginPath, netconf, delegateArgs("ADD"), realExec)
 }
 
-func DelegateDel(delegatePlugin string, netconf []byte) error {
-	if os.Getenv("CNI_COMMAND") != "DEL" {
-		return fmt.Errorf("CNI_COMMAND is not DEL")
-	}
+// DelegateCheck calls the given delegate plugin with the CNI CHECK action and
+// JSON configuration
+func DelegateCheck(ctx context.Context, delegatePlugin string, netconf []byte, exec Exec) error {
+	return delegateNoResult(ctx, delegatePlugin, netconf, exec, "CHECK")
+}
 
-	paths := strings.Split(os.Getenv("CNI_PATH"), ":")
-
-	pluginPath, err := FindInPath(delegatePlugin, paths)
+func delegateNoResult(ctx context.Context, delegatePlugin string, netconf []byte, exec Exec, verb string) error {
+	pluginPath, realExec, err := delegateCommon(delegatePlugin, exec)
 	if err != nil {
 		return err
 	}
 
-	return ExecPluginWithoutResult(pluginPath, netconf, ArgsFromEnv())
+	return ExecPluginWithoutResult(ctx, pluginPath, netconf, delegateArgs(verb), realExec)
+}
+
+// DelegateDel calls the given delegate plugin with the CNI DEL action and
+// JSON configuration
+func DelegateDel(ctx context.Context, delegatePlugin string, netconf []byte, exec Exec) error {
+	return delegateNoResult(ctx, delegatePlugin, netconf, exec, "DEL")
+}
+
+// DelegateStatus calls the given delegate plugin with the CNI STATUS action and
+// JSON configuration
+func DelegateStatus(ctx context.Context, delegatePlugin string, netconf []byte, exec Exec) error {
+	return delegateNoResult(ctx, delegatePlugin, netconf, exec, "STATUS")
+}
+
+// DelegateGC calls the given delegate plugin with the CNI GC action and
+// JSON configuration
+func DelegateGC(ctx context.Context, delegatePlugin string, netconf []byte, exec Exec) error {
+	return delegateNoResult(ctx, delegatePlugin, netconf, exec, "GC")
+}
+
+// return CNIArgs used by delegation
+func delegateArgs(action string) *DelegateArgs {
+	return &DelegateArgs{
+		Command: action,
+	}
 }

pkg/invoke/delegate_test.go

@@ -0,0 +1,270 @@
+// Copyright 2017 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package invoke_test
+
+import (
+	"context"
+	"encoding/json"
+	"net"
+	"os"
+	"path/filepath"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	"github.com/containernetworking/cni/pkg/invoke"
+	current "github.com/containernetworking/cni/pkg/types/100"
+	"github.com/containernetworking/cni/pkg/version"
+	"github.com/containernetworking/cni/plugins/test/noop/debug"
+)
+
+var _ = Describe("Delegate", func() {
+	var (
+		pluginName     string
+		netConf        []byte
+		debugFileName  string
+		debugBehavior  *debug.Debug
+		expectedResult *current.Result
+		ctx            context.Context
+	)
+
+	BeforeEach(func() {
+		netConf, _ = json.Marshal(map[string]string{
+			"name":       "delegate-test",
+			"cniVersion": version.Current(),
+		})
+
+		expectedResult = &current.Result{
+			CNIVersion: current.ImplementedSpecVersion,
+			IPs: []*current.IPConfig{
+				{
+					Address: net.IPNet{
+						IP:   net.ParseIP("10.1.2.3"),
+						Mask: net.CIDRMask(24, 32),
+					},
+				},
+			},
+		}
+		expectedResultBytes, _ := json.Marshal(expectedResult)
+
+		debugFile, err := os.CreateTemp("", "cni_debug")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(debugFile.Close()).To(Succeed())
+		debugFileName = debugFile.Name()
+		debugBehavior = &debug.Debug{
+			ReportResult: string(expectedResultBytes),
+		}
+		Expect(debugBehavior.WriteDebug(debugFileName)).To(Succeed())
+		pluginName = "noop"
+		ctx = context.TODO()
+		os.Setenv("CNI_ARGS", "DEBUG="+debugFileName)
+		os.Setenv("CNI_PATH", filepath.Dir(pathToPlugin))
+		os.Setenv("CNI_NETNS", "/tmp/some/netns/path")
+		os.Setenv("CNI_IFNAME", "eth7")
+		os.Setenv("CNI_CONTAINERID", "container")
+	})
+
+	AfterEach(func() {
+		os.RemoveAll(debugFileName)
+
+		for _, k := range []string{"CNI_COMMAND", "CNI_ARGS", "CNI_PATH", "CNI_NETNS", "CNI_IFNAME"} {
+			os.Unsetenv(k)
+		}
+	})
+
+	Describe("DelegateAdd", func() {
+		BeforeEach(func() {
+			os.Setenv("CNI_COMMAND", "ADD")
+		})
+
+		It("finds and execs the named plugin", func() {
+			result, err := invoke.DelegateAdd(ctx, pluginName, netConf, nil)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(result).To(Equal(expectedResult))
+
+			pluginInvocation, err := debug.ReadDebug(debugFileName)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(pluginInvocation.Command).To(Equal("ADD"))
+			Expect(pluginInvocation.CmdArgs.IfName).To(Equal("eth7"))
+		})
+
+		Context("if the ADD delegation runs on an existing non-ADD command, ", func() {
+			BeforeEach(func() {
+				os.Setenv("CNI_COMMAND", "NOPE")
+			})
+
+			It("aborts and returns a useful error", func() {
+				result, err := invoke.DelegateAdd(ctx, pluginName, netConf, nil)
+				Expect(err).NotTo(HaveOccurred())
+				Expect(result).To(Equal(expectedResult))
+
+				pluginInvocation, err := debug.ReadDebug(debugFileName)
+				Expect(err).NotTo(HaveOccurred())
+				Expect(pluginInvocation.Command).To(Equal("ADD"))
+				Expect(pluginInvocation.CmdArgs.IfName).To(Equal("eth7"))
+
+				// check the original env
+				Expect(os.Getenv("CNI_COMMAND")).To(Equal("NOPE"))
+			})
+		})
+
+		Context("when the plugin cannot be found", func() {
+			BeforeEach(func() {
+				pluginName = "non-existent-plugin"
+			})
+
+			It("returns a useful error", func() {
+				_, err := invoke.DelegateAdd(ctx, pluginName, netConf, nil)
+				Expect(err).To(MatchError(HavePrefix("failed to find plugin")))
+			})
+		})
+	})
+
+	Describe("DelegateCheck", func() {
+		BeforeEach(func() {
+			os.Setenv("CNI_COMMAND", "CHECK")
+		})
+
+		It("finds and execs the named plugin", func() {
+			err := invoke.DelegateCheck(ctx, pluginName, netConf, nil)
+			Expect(err).NotTo(HaveOccurred())
+
+			pluginInvocation, err := debug.ReadDebug(debugFileName)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(pluginInvocation.Command).To(Equal("CHECK"))
+			Expect(pluginInvocation.CmdArgs.IfName).To(Equal("eth7"))
+		})
+
+		Context("if the CHECK delegation runs on an existing non-CHECK command", func() {
+			BeforeEach(func() {
+				os.Setenv("CNI_COMMAND", "NOPE")
+			})
+
+			It("aborts and returns a useful error", func() {
+				err := invoke.DelegateCheck(ctx, pluginName, netConf, nil)
+				Expect(err).NotTo(HaveOccurred())
+
+				pluginInvocation, err := debug.ReadDebug(debugFileName)
+				Expect(err).NotTo(HaveOccurred())
+				Expect(pluginInvocation.Command).To(Equal("CHECK"))
+				Expect(pluginInvocation.CmdArgs.IfName).To(Equal("eth7"))
+
+				// check the original env
+				Expect(os.Getenv("CNI_COMMAND")).To(Equal("NOPE"))
+			})
+		})
+
+		Context("when the plugin cannot be found", func() {
+			BeforeEach(func() {
+				pluginName = "non-existent-plugin"
+			})
+
+			It("returns a useful error", func() {
+				err := invoke.DelegateCheck(ctx, pluginName, netConf, nil)
+				Expect(err).To(MatchError(HavePrefix("failed to find plugin")))
+			})
+		})
+	})
+
+	Describe("DelegateDel", func() {
+		BeforeEach(func() {
+			os.Setenv("CNI_COMMAND", "DEL")
+		})
+
+		It("finds and execs the named plugin", func() {
+			err := invoke.DelegateDel(ctx, pluginName, netConf, nil)
+			Expect(err).NotTo(HaveOccurred())
+
+			pluginInvocation, err := debug.ReadDebug(debugFileName)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(pluginInvocation.Command).To(Equal("DEL"))
+			Expect(pluginInvocation.CmdArgs.IfName).To(Equal("eth7"))
+		})
+
+		Context("if the DEL delegation runs on an existing non-DEL command", func() {
+			BeforeEach(func() {
+				os.Setenv("CNI_COMMAND", "NOPE")
+			})
+
+			It("aborts and returns a useful error", func() {
+				err := invoke.DelegateDel(ctx, pluginName, netConf, nil)
+				Expect(err).NotTo(HaveOccurred())
+
+				pluginInvocation, err := debug.ReadDebug(debugFileName)
+				Expect(err).NotTo(HaveOccurred())
+				Expect(pluginInvocation.Command).To(Equal("DEL"))
+				Expect(pluginInvocation.CmdArgs.IfName).To(Equal("eth7"))
+
+				// check the original env
+				Expect(os.Getenv("CNI_COMMAND")).To(Equal("NOPE"))
+			})
+		})
+
+		Context("when the plugin cannot be found", func() {
+			BeforeEach(func() {
+				pluginName = "non-existent-plugin"
+			})
+
+			It("returns a useful error", func() {
+				err := invoke.DelegateDel(ctx, pluginName, netConf, nil)
+				Expect(err).To(MatchError(HavePrefix("failed to find plugin")))
+			})
+		})
+	})
+
+	Describe("DelegateStatus", func() {
+		BeforeEach(func() {
+			os.Setenv("CNI_COMMAND", "STATUS")
+		})
+
+		It("finds and execs the named plugin", func() {
+			err := invoke.DelegateStatus(ctx, pluginName, netConf, nil)
+			Expect(err).NotTo(HaveOccurred())
+
+			pluginInvocation, err := debug.ReadDebug(debugFileName)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(pluginInvocation.Command).To(Equal("STATUS"))
+		})
+
+		Context("if the STATUS delegation runs on an existing non-STATUS command", func() {
+			BeforeEach(func() {
+				os.Setenv("CNI_COMMAND", "NOPE")
+			})
+
+			It("aborts and returns a useful error", func() {
+				err := invoke.DelegateStatus(ctx, pluginName, netConf, nil)
+				Expect(err).NotTo(HaveOccurred())
+
+				pluginInvocation, err := debug.ReadDebug(debugFileName)
+				Expect(err).NotTo(HaveOccurred())
+				Expect(pluginInvocation.Command).To(Equal("STATUS"))
+
+				// check the original env
+				Expect(os.Getenv("CNI_COMMAND")).To(Equal("NOPE"))
+			})
+		})
+
+		Context("when the plugin cannot be found", func() {
+			BeforeEach(func() {
+				pluginName = "non-existent-plugin"
+			})
+
+			It("returns a useful error", func() {
+				err := invoke.DelegateStatus(ctx, pluginName, netConf, nil)
+				Expect(err).To(MatchError(HavePrefix("failed to find plugin")))
+			})
+		})
+	})
+})

pkg/invoke/exec.go

@@ -15,61 +15,173 @@
 package invoke
 
 import (
-	"bytes"
+	"context"
 	"encoding/json"
 	"fmt"
 	"os"
-	"os/exec"
 
 	"github.com/containernetworking/cni/pkg/types"
+	"github.com/containernetworking/cni/pkg/types/create"
+	"github.com/containernetworking/cni/pkg/version"
 )
 
-func pluginErr(err error, output []byte) error {
-	if _, ok := err.(*exec.ExitError); ok {
-		emsg := types.Error{}
-		if perr := json.Unmarshal(output, &emsg); perr != nil {
-			return fmt.Errorf("netplugin failed but error parsing its diagnostic message %q: %v", string(output), perr)
-		}
-		details := ""
-		if emsg.Details != "" {
-			details = fmt.Sprintf("; %v", emsg.Details)
-		}
-		return fmt.Errorf("%v%v", emsg.Msg, details)
-	}
-
-	return err
+// Exec is an interface encapsulates all operations that deal with finding
+// and executing a CNI plugin. Tests may provide a fake implementation
+// to avoid writing fake plugins to temporary directories during the test.
+type Exec interface {
+	ExecPlugin(ctx context.Context, pluginPath string, stdinData []byte, environ []string) ([]byte, error)
+	FindInPath(plugin string, paths []string) (string, error)
+	Decode(jsonBytes []byte) (version.PluginInfo, error)
 }
 
-func ExecPluginWithResult(pluginPath string, netconf []byte, args CNIArgs) (*types.Result, error) {
-	stdoutBytes, err := execPlugin(pluginPath, netconf, args)
+// Plugin must return result in same version as specified in netconf; but
+// for backwards compatibility reasons if the result version is empty use
+// config version (rather than technically correct 0.1.0).
+// https://github.com/containernetworking/cni/issues/895
+func fixupResultVersion(netconf, result []byte) (string, []byte, error) {
+	versionDecoder := &version.ConfigDecoder{}
+	confVersion, err := versionDecoder.Decode(netconf)
+	if err != nil {
+		return "", nil, err
+	}
+
+	var rawResult map[string]interface{}
+	if err := json.Unmarshal(result, &rawResult); err != nil {
+		return "", nil, fmt.Errorf("failed to unmarshal raw result: %w", err)
+	}
+
+	// plugin output of "null" is successfully unmarshalled, but results in a nil
+	// map which causes a panic when the confVersion is assigned below.
+	if rawResult == nil {
+		rawResult = make(map[string]interface{})
+	}
+
+	// Manually decode Result version; we need to know whether its cniVersion
+	// is empty, while built-in decoders (correctly) substitute 0.1.0 for an
+	// empty version per the CNI spec.
+	if resultVerRaw, ok := rawResult["cniVersion"]; ok {
+		resultVer, ok := resultVerRaw.(string)
+		if ok && resultVer != "" {
+			return resultVer, result, nil
+		}
+	}
+
+	// If the cniVersion is not present or empty, assume the result is
+	// the same CNI spec version as the config
+	rawResult["cniVersion"] = confVersion
+	newBytes, err := json.Marshal(rawResult)
+	if err != nil {
+		return "", nil, fmt.Errorf("failed to remarshal fixed result: %w", err)
+	}
+
+	return confVersion, newBytes, nil
+}
+
+// For example, a testcase could pass an instance of the following fakeExec
+// object to ExecPluginWithResult() to verify the incoming stdin and environment
+// and provide a tailored response:
+//
+// import (
+//	"encoding/json"
+//	"path"
+//	"strings"
+// )
+//
+// type fakeExec struct {
+//	version.PluginDecoder
+// }
+//
+// func (f *fakeExec) ExecPlugin(pluginPath string, stdinData []byte, environ []string) ([]byte, error) {
+//	net := &types.NetConf{}
+//	err := json.Unmarshal(stdinData, net)
+//	if err != nil {
+//		return nil, fmt.Errorf("failed to unmarshal configuration: %v", err)
+//	}
+//	pluginName := path.Base(pluginPath)
+//	if pluginName != net.Type {
+//		return nil, fmt.Errorf("plugin name %q did not match config type %q", pluginName, net.Type)
+//	}
+//	for _, e := range environ {
+//		// Check environment for forced failure request
+//		parts := strings.Split(e, "=")
+//		if len(parts) > 0 && parts[0] == "FAIL" {
+//			return nil, fmt.Errorf("failed to execute plugin %s", pluginName)
+//		}
+//	}
+//	return []byte("{\"CNIVersion\":\"0.4.0\"}"), nil
+// }
+//
+// func (f *fakeExec) FindInPath(plugin string, paths []string) (string, error) {
+//	if len(paths) > 0 {
+//		return path.Join(paths[0], plugin), nil
+//	}
+//	return "", fmt.Errorf("failed to find plugin %s in paths %v", plugin, paths)
+// }
+
+func ExecPluginWithResult(ctx context.Context, pluginPath string, netconf []byte, args CNIArgs, exec Exec) (types.Result, error) {
+	if exec == nil {
+		exec = defaultExec
+	}
+
+	stdoutBytes, err := exec.ExecPlugin(ctx, pluginPath, netconf, args.AsEnv())
 	if err != nil {
 		return nil, err
 	}
 
-	res := &types.Result{}
-	err = json.Unmarshal(stdoutBytes, res)
-	return res, err
+	resultVersion, fixedBytes, err := fixupResultVersion(netconf, stdoutBytes)
+	if err != nil {
+		return nil, err
+	}
+
+	return create.Create(resultVersion, fixedBytes)
 }
 
-func ExecPluginWithoutResult(pluginPath string, netconf []byte, args CNIArgs) error {
-	_, err := execPlugin(pluginPath, netconf, args)
+func ExecPluginWithoutResult(ctx context.Context, pluginPath string, netconf []byte, args CNIArgs, exec Exec) error {
+	if exec == nil {
+		exec = defaultExec
+	}
+	_, err := exec.ExecPlugin(ctx, pluginPath, netconf, args.AsEnv())
 	return err
 }
 
-func execPlugin(pluginPath string, netconf []byte, args CNIArgs) ([]byte, error) {
-	stdout := &bytes.Buffer{}
-
-	c := exec.Cmd{
-		Env:    args.AsEnv(),
-		Path:   pluginPath,
-		Args:   []string{pluginPath},
-		Stdin:  bytes.NewBuffer(netconf),
-		Stdout: stdout,
-		Stderr: os.Stderr,
+// GetVersionInfo returns the version information available about the plugin.
+// For recent-enough plugins, it uses the information returned by the VERSION
+// command.  For older plugins which do not recognize that command, it reports
+// version 0.1.0
+func GetVersionInfo(ctx context.Context, pluginPath string, exec Exec) (version.PluginInfo, error) {
+	if exec == nil {
+		exec = defaultExec
 	}
-	if err := c.Run(); err != nil {
-		return nil, pluginErr(err, stdout.Bytes())
+	args := &Args{
+		Command: "VERSION",
+
+		// set fake values required by plugins built against an older version of skel
+		NetNS:  "dummy",
+		IfName: "dummy",
+		Path:   "dummy",
+	}
+	stdin := []byte(fmt.Sprintf(`{"cniVersion":%q}`, version.Current()))
+	stdoutBytes, err := exec.ExecPlugin(ctx, pluginPath, stdin, args.AsEnv())
+	if err != nil {
+		if err.Error() == "unknown CNI_COMMAND: VERSION" {
+			return version.PluginSupports("0.1.0"), nil
+		}
+		return nil, err
 	}
 
-	return stdout.Bytes(), nil
+	return exec.Decode(stdoutBytes)
+}
+
+// DefaultExec is an object that implements the Exec interface which looks
+// for and executes plugins from disk.
+type DefaultExec struct {
+	*RawExec
+	version.PluginDecoder
+}
+
+// DefaultExec implements the Exec interface
+var _ Exec = &DefaultExec{}
+
+var defaultExec = &DefaultExec{
+	RawExec: &RawExec{Stderr: os.Stderr},
 }

pkg/invoke/exec_test.go

@@ -0,0 +1,215 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package invoke_test
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	"github.com/containernetworking/cni/pkg/invoke"
+	"github.com/containernetworking/cni/pkg/invoke/fakes"
+	current "github.com/containernetworking/cni/pkg/types/100"
+	"github.com/containernetworking/cni/pkg/version"
+)
+
+var _ = Describe("Executing a plugin, unit tests", func() {
+	var (
+		pluginExec     invoke.Exec
+		rawExec        *fakes.RawExec
+		versionDecoder *fakes.VersionDecoder
+
+		pluginPath string
+		netconf    []byte
+		cniargs    *fakes.CNIArgs
+		ctx        context.Context
+	)
+
+	BeforeEach(func() {
+		rawExec = &fakes.RawExec{}
+		rawExec.ExecPluginCall.Returns.ResultBytes = []byte(`{ "cniVersion": "0.3.1", "ips": [ { "version": "4", "address": "1.2.3.4/24" } ] }`)
+
+		versionDecoder = &fakes.VersionDecoder{}
+		versionDecoder.DecodeCall.Returns.PluginInfo = version.PluginSupports("0.42.0")
+
+		pluginExec = &struct {
+			*fakes.RawExec
+			*fakes.VersionDecoder
+		}{
+			RawExec:        rawExec,
+			VersionDecoder: versionDecoder,
+		}
+		pluginPath = "/some/plugin/path"
+		netconf = []byte(`{ "some": "stdin", "cniVersion": "0.3.1" }`)
+		cniargs = &fakes.CNIArgs{}
+		cniargs.AsEnvCall.Returns.Env = []string{"SOME=ENV"}
+		ctx = context.TODO()
+	})
+
+	Describe("returning a result", func() {
+		It("unmarshals the result bytes into the Result type", func() {
+			r, err := invoke.ExecPluginWithResult(ctx, pluginPath, netconf, cniargs, pluginExec)
+			Expect(err).NotTo(HaveOccurred())
+
+			result, err := current.GetResult(r)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(result.IPs).To(HaveLen(1))
+			Expect(result.IPs[0].Address.IP.String()).To(Equal("1.2.3.4"))
+		})
+
+		It("passes its arguments through to the rawExec", func() {
+			_, err := invoke.ExecPluginWithResult(ctx, pluginPath, netconf, cniargs, pluginExec)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(rawExec.ExecPluginCall.Received.PluginPath).To(Equal(pluginPath))
+			Expect(rawExec.ExecPluginCall.Received.StdinData).To(Equal(netconf))
+			Expect(rawExec.ExecPluginCall.Received.Environ).To(Equal([]string{"SOME=ENV"}))
+		})
+
+		Context("when the rawExec fails", func() {
+			BeforeEach(func() {
+				rawExec.ExecPluginCall.Returns.Error = errors.New("banana")
+			})
+			It("returns the error", func() {
+				_, err := invoke.ExecPluginWithResult(ctx, pluginPath, netconf, cniargs, pluginExec)
+				Expect(err).To(MatchError("banana"))
+			})
+		})
+
+		It("returns an error using the default exec interface", func() {
+			// pluginPath should not exist on-disk so we expect an error.
+			// This test simply tests that the default exec handler
+			// is run when the exec interface is nil.
+			_, err := invoke.ExecPluginWithResult(ctx, pluginPath, netconf, cniargs, nil)
+			Expect(err).To(HaveOccurred())
+		})
+
+		It("assumes config version if result version is missing", func() {
+			rawExec.ExecPluginCall.Returns.ResultBytes = []byte(`{ "ips": [ { "version": "4", "address": "1.2.3.4/24" } ] }`)
+			r, err := invoke.ExecPluginWithResult(ctx, pluginPath, netconf, cniargs, pluginExec)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(r.Version()).To(Equal("0.3.1"))
+
+			result, err := current.GetResult(r)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(result.IPs).To(HaveLen(1))
+			Expect(result.IPs[0].Address.IP.String()).To(Equal("1.2.3.4"))
+		})
+
+		It("assumes config version if result version is empty", func() {
+			rawExec.ExecPluginCall.Returns.ResultBytes = []byte(`{ "cniVersion": "", "ips": [ { "version": "4", "address": "1.2.3.4/24" } ] }`)
+			r, err := invoke.ExecPluginWithResult(ctx, pluginPath, netconf, cniargs, pluginExec)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(r.Version()).To(Equal("0.3.1"))
+
+			result, err := current.GetResult(r)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(result.IPs).To(HaveLen(1))
+			Expect(result.IPs[0].Address.IP.String()).To(Equal("1.2.3.4"))
+		})
+
+		It("assumes 0.1.0 if config and result version are empty", func() {
+			netconf = []byte(`{ "some": "stdin" }`)
+			rawExec.ExecPluginCall.Returns.ResultBytes = []byte(`{ "some": "version-info" }`)
+			r, err := invoke.ExecPluginWithResult(ctx, pluginPath, netconf, cniargs, pluginExec)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(r.Version()).To(Equal("0.1.0"))
+		})
+	})
+
+	Describe("without returning a result", func() {
+		It("passes its arguments through to the rawExec", func() {
+			err := invoke.ExecPluginWithoutResult(ctx, pluginPath, netconf, cniargs, pluginExec)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(rawExec.ExecPluginCall.Received.PluginPath).To(Equal(pluginPath))
+			Expect(rawExec.ExecPluginCall.Received.StdinData).To(Equal(netconf))
+			Expect(rawExec.ExecPluginCall.Received.Environ).To(Equal([]string{"SOME=ENV"}))
+		})
+
+		Context("when the rawExec fails", func() {
+			BeforeEach(func() {
+				rawExec.ExecPluginCall.Returns.Error = errors.New("banana")
+			})
+			It("returns the error", func() {
+				err := invoke.ExecPluginWithoutResult(ctx, pluginPath, netconf, cniargs, pluginExec)
+				Expect(err).To(MatchError("banana"))
+			})
+		})
+
+		It("returns an error using the default exec interface", func() {
+			// pluginPath should not exist on-disk so we expect an error.
+			// This test simply tests that the default exec handler
+			// is run when the exec interface is nil.
+			err := invoke.ExecPluginWithoutResult(ctx, pluginPath, netconf, cniargs, nil)
+			Expect(err).To(HaveOccurred())
+		})
+	})
+
+	Describe("discovering the plugin version", func() {
+		BeforeEach(func() {
+			rawExec.ExecPluginCall.Returns.ResultBytes = []byte(`{ "some": "version-info" }`)
+		})
+
+		It("execs the plugin with the command VERSION", func() {
+			_, err := invoke.GetVersionInfo(ctx, pluginPath, pluginExec)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(rawExec.ExecPluginCall.Received.PluginPath).To(Equal(pluginPath))
+			Expect(rawExec.ExecPluginCall.Received.Environ).To(ContainElement("CNI_COMMAND=VERSION"))
+			expectedStdin, _ := json.Marshal(map[string]string{"cniVersion": version.Current()})
+			Expect(rawExec.ExecPluginCall.Received.StdinData).To(MatchJSON(expectedStdin))
+		})
+
+		It("decodes and returns the version info", func() {
+			versionInfo, err := invoke.GetVersionInfo(ctx, pluginPath, pluginExec)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(versionInfo.SupportedVersions()).To(Equal([]string{"0.42.0"}))
+			Expect(versionDecoder.DecodeCall.Received.JSONBytes).To(MatchJSON(`{ "some": "version-info" }`))
+		})
+
+		Context("when the rawExec fails", func() {
+			BeforeEach(func() {
+				rawExec.ExecPluginCall.Returns.Error = errors.New("banana")
+			})
+			It("returns the error", func() {
+				_, err := invoke.GetVersionInfo(ctx, pluginPath, pluginExec)
+				Expect(err).To(MatchError("banana"))
+			})
+		})
+
+		Context("when the plugin is too old to recognize the VERSION command", func() {
+			BeforeEach(func() {
+				rawExec.ExecPluginCall.Returns.Error = errors.New("unknown CNI_COMMAND: VERSION")
+			})
+
+			It("interprets the error as a 0.1.0 version", func() {
+				versionInfo, err := invoke.GetVersionInfo(ctx, pluginPath, pluginExec)
+				Expect(err).NotTo(HaveOccurred())
+				Expect(versionInfo.SupportedVersions()).To(ConsistOf("0.1.0"))
+			})
+
+			It("sets dummy values for env vars required by very old plugins", func() {
+				_, err := invoke.GetVersionInfo(ctx, pluginPath, pluginExec)
+				Expect(err).NotTo(HaveOccurred())
+
+				env := rawExec.ExecPluginCall.Received.Environ
+				Expect(env).To(ContainElement("CNI_NETNS=dummy"))
+				Expect(env).To(ContainElement("CNI_IFNAME=dummy"))
+				Expect(env).To(ContainElement("CNI_PATH=dummy"))
+			})
+		})
+	})
+})

pkg/invoke/fakes/cni_args.go

@@ -0,0 +1,27 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package fakes
+
+type CNIArgs struct {
+	AsEnvCall struct {
+		Returns struct {
+			Env []string
+		}
+	}
+}
+
+func (a *CNIArgs) AsEnv() []string {
+	return a.AsEnvCall.Returns.Env
+}

pkg/invoke/fakes/raw_exec.go

@@ -0,0 +1,54 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package fakes
+
+import "context"
+
+type RawExec struct {
+	ExecPluginCall struct {
+		Received struct {
+			PluginPath string
+			StdinData  []byte
+			Environ    []string
+		}
+		Returns struct {
+			ResultBytes []byte
+			Error       error
+		}
+	}
+	FindInPathCall struct {
+		Received struct {
+			Plugin string
+			Paths  []string
+		}
+		Returns struct {
+			Path  string
+			Error error
+		}
+	}
+}
+
+func (e *RawExec) ExecPlugin(ctx context.Context, pluginPath string, stdinData []byte, environ []string) ([]byte, error) {
+	e.ExecPluginCall.Received.PluginPath = pluginPath
+	e.ExecPluginCall.Received.StdinData = stdinData
+	e.ExecPluginCall.Received.Environ = environ
+	return e.ExecPluginCall.Returns.ResultBytes, e.ExecPluginCall.Returns.Error
+}
+
+func (e *RawExec) FindInPath(plugin string, paths []string) (string, error) {
+	e.FindInPathCall.Received.Plugin = plugin
+	e.FindInPathCall.Received.Paths = paths
+	return e.FindInPathCall.Returns.Path, e.FindInPathCall.Returns.Error
+}

pkg/invoke/fakes/version_decoder.go

@@ -12,23 +12,23 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package ns_test
+package fakes
 
-import (
-	"math/rand"
-	"runtime"
+import "github.com/containernetworking/cni/pkg/version"
 
-	. "github.com/onsi/ginkgo"
-	"github.com/onsi/ginkgo/config"
-	. "github.com/onsi/gomega"
-
-	"testing"
-)
-
-func TestNs(t *testing.T) {
-	rand.Seed(config.GinkgoConfig.RandomSeed)
-	runtime.LockOSThread()
-
-	RegisterFailHandler(Fail)
-	RunSpecs(t, "pkg/ns Suite")
+type VersionDecoder struct {
+	DecodeCall struct {
+		Received struct {
+			JSONBytes []byte
+		}
+		Returns struct {
+			PluginInfo version.PluginInfo
+			Error      error
+		}
+	}
+}
+
+func (e *VersionDecoder) Decode(jsonData []byte) (version.PluginInfo, error) {
+	e.DecodeCall.Received.JSONBytes = jsonData
+	return e.DecodeCall.Returns.PluginInfo, e.DecodeCall.Returns.Error
 }

pkg/invoke/find.go

@@ -18,6 +18,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strings"
 )
 
 // FindInPath returns the full path of the plugin by searching in the provided path
@@ -26,22 +27,22 @@ func FindInPath(plugin string, paths []string) (string, error) {
 		return "", fmt.Errorf("no plugin name provided")
 	}
 
+	if strings.ContainsRune(plugin, os.PathSeparator) {
+		return "", fmt.Errorf("invalid plugin name: %s", plugin)
+	}
+
 	if len(paths) == 0 {
 		return "", fmt.Errorf("no paths provided")
 	}
 
-	var fullpath string
 	for _, path := range paths {
-		full := filepath.Join(path, plugin)
-		if fi, err := os.Stat(full); err == nil && fi.Mode().IsRegular() {
-			fullpath = full
-			break
+		for _, fe := range ExecutableFileExtensions {
+			fullpath := filepath.Join(path, plugin) + fe
+			if fi, err := os.Stat(fullpath); err == nil && fi.Mode().IsRegular() {
+				return fullpath, nil
+			}
 		}
 	}
 
-	if fullpath == "" {
-		return "", fmt.Errorf("failed to find plugin %q in path %s", plugin, paths)
-	}
-
-	return fullpath, nil
+	return "", fmt.Errorf("failed to find plugin %q in path %s", plugin, paths)
 }

pkg/invoke/find_test.go

@@ -16,32 +16,49 @@ package invoke_test
 
 import (
 	"fmt"
-	"io/ioutil"
+	"os"
 	"path/filepath"
+	"strings"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
 
 	"github.com/containernetworking/cni/pkg/invoke"
-	. "github.com/onsi/ginkgo"
-	. "github.com/onsi/gomega"
 )
 
 var _ = Describe("FindInPath", func() {
 	var (
-		multiplePaths  []string
-		pluginName     string
-		pluginDir      string
-		anotherTempDir string
+		multiplePaths         []string
+		pluginName            string
+		plugin2NameWithExt    string
+		plugin2NameWithoutExt string
+		pluginDir             string
+		anotherTempDir        string
 	)
 
 	BeforeEach(func() {
-		tempDir, err := ioutil.TempDir("", "cni-find")
+		tempDir, err := os.MkdirTemp("", "cni-find")
 		Expect(err).NotTo(HaveOccurred())
 
-		plugin, err := ioutil.TempFile(tempDir, "a-cni-plugin")
+		plugin, err := os.CreateTemp(tempDir, "a-cni-plugin")
+		Expect(err).NotTo(HaveOccurred())
 
-		anotherTempDir, err = ioutil.TempDir("", "nothing-here")
+		plugin2Name := "a-plugin-with-extension" + invoke.ExecutableFileExtensions[0]
+		plugin2, err := os.Create(filepath.Join(tempDir, plugin2Name))
+		Expect(err).NotTo(HaveOccurred())
+
+		anotherTempDir, err = os.MkdirTemp("", "nothing-here")
+		Expect(err).NotTo(HaveOccurred())
 
 		multiplePaths = []string{anotherTempDir, tempDir}
 		pluginDir, pluginName = filepath.Split(plugin.Name())
+		_, plugin2NameWithExt = filepath.Split(plugin2.Name())
+		plugin2NameWithoutExt = strings.Split(plugin2NameWithExt, ".")[0]
+	})
+
+	AfterEach(func() {
+		os.RemoveAll(pluginDir)
+		os.RemoveAll(anotherTempDir)
 	})
 
 	Context("when multiple paths are provided", func() {
@@ -52,6 +69,14 @@ var _ = Describe("FindInPath", func() {
 		})
 	})
 
+	Context("when a plugin name without its file name extension is provided", func() {
+		It("returns the path to the plugin, including its extension", func() {
+			pluginPath, err := invoke.FindInPath(plugin2NameWithoutExt, multiplePaths)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(pluginPath).To(Equal(filepath.Join(pluginDir, plugin2NameWithExt)))
+		})
+	})
+
 	Context("when an error occurs", func() {
 		Context("when no paths are provided", func() {
 			It("returns an error noting no paths were provided", func() {
@@ -74,5 +99,13 @@ var _ = Describe("FindInPath", func() {
 				Expect(err).To(MatchError(fmt.Sprintf("failed to find plugin %q in path %s", pluginName, pathsWithNothing)))
 			})
 		})
+
+		Context("When the plugin contains a directory separator", func() {
+			It("returns an error", func() {
+				bogusPlugin := ".." + string(os.PathSeparator) + "pluginname"
+				_, err := invoke.FindInPath(bogusPlugin, []string{anotherTempDir})
+				Expect(err).To(MatchError("invalid plugin name: " + bogusPlugin))
+			})
+		})
 	})
 })

pkg/invoke/get_version_integration_test.go

@@ -0,0 +1,133 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package invoke_test
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"runtime"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	"github.com/containernetworking/cni/pkg/invoke"
+	"github.com/containernetworking/cni/pkg/version"
+	"github.com/containernetworking/cni/pkg/version/testhelpers"
+)
+
+var _ = Describe("GetVersion, integration tests", func() {
+	var (
+		pluginDir  string
+		pluginPath string
+	)
+
+	BeforeEach(func() {
+		pluginDir, err := os.MkdirTemp("", "plugins")
+		Expect(err).NotTo(HaveOccurred())
+		pluginPath = filepath.Join(pluginDir, "test-plugin")
+		if runtime.GOOS == "windows" {
+			pluginPath += ".exe"
+		}
+	})
+
+	AfterEach(func() {
+		Expect(os.RemoveAll(pluginDir)).To(Succeed())
+	})
+
+	DescribeTable("correctly reporting plugin versions",
+		func(gitRef string, pluginSource string, expectedVersions version.PluginInfo) {
+			Expect(testhelpers.BuildAt([]byte(pluginSource), gitRef, pluginPath)).To(Succeed())
+			versionInfo, err := invoke.GetVersionInfo(context.TODO(), pluginPath, nil)
+			Expect(err).NotTo(HaveOccurred())
+
+			Expect(versionInfo.SupportedVersions()).To(ConsistOf(expectedVersions.SupportedVersions()))
+		},
+
+		Entry("historical: before VERSION was introduced",
+			git_ref_v010, plugin_source_no_custom_versions,
+			version.PluginSupports("0.1.0"),
+		),
+
+		Entry("historical: when VERSION was introduced but plugins couldn't customize it",
+			git_ref_v020_no_custom_versions, plugin_source_no_custom_versions,
+			version.PluginSupports("0.1.0", "0.2.0"),
+		),
+
+		Entry("historical: when plugins started reporting their own version list",
+			git_ref_v020_custom_versions, plugin_source_v020_custom_versions,
+			version.PluginSupports("0.2.0", "0.999.0"),
+		),
+
+		Entry("historical: before CHECK was introduced",
+			git_ref_v031, plugin_source_v020_custom_versions,
+			version.PluginSupports("0.2.0", "0.999.0"),
+		),
+
+		// this entry tracks the current behavior.  Before you change it, ensure
+		// that its previous behavior is captured in the most recent "historical" entry
+		Entry("current",
+			"HEAD", plugin_source_v040_check,
+			version.PluginSupports("0.2.0", "0.4.0", "0.999.0"),
+		),
+	)
+})
+
+// A 0.4.0 plugin that supports CHECK
+const plugin_source_v040_check = `package main
+
+import (
+	"github.com/containernetworking/cni/pkg/skel"
+	"github.com/containernetworking/cni/pkg/version"
+	"fmt"
+)
+
+func c(_ *skel.CmdArgs) error { fmt.Println("{}"); return nil }
+
+func main() { skel.PluginMain(c, c, c, version.PluginSupports("0.2.0", "0.4.0", "0.999.0"), "") }
+`
+
+const git_ref_v031 = "909fe7d"
+
+// a 0.2.0 plugin that can report its own versions
+const plugin_source_v020_custom_versions = `package main
+
+import (
+	"github.com/containernetworking/cni/pkg/skel"
+	"github.com/containernetworking/cni/pkg/version"
+	"fmt"
+)
+
+func c(_ *skel.CmdArgs) error { fmt.Println("{}"); return nil }
+
+func main() { skel.PluginMain(c, c, version.PluginSupports("0.2.0", "0.999.0")) }
+`
+const git_ref_v020_custom_versions = "bf31ed15"
+
+// a minimal 0.1.0 / 0.2.0 plugin that cannot report it's own version support
+const plugin_source_no_custom_versions = `package main
+
+import "github.com/containernetworking/cni/pkg/skel"
+import "fmt"
+
+func c(_ *skel.CmdArgs) error { fmt.Println("{}"); return nil }
+
+func main() { skel.PluginMain(c, c) }
+`
+
+const (
+	git_ref_v010                    = "2c482f4"
+	git_ref_v020_no_custom_versions = "349d66d"
+)

pkg/invoke/invoke_suite_test.go

@@ -15,13 +15,31 @@
 package invoke_test
 
 import (
-	. "github.com/onsi/ginkgo"
-	. "github.com/onsi/gomega"
-
 	"testing"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"github.com/onsi/gomega/gexec"
 )
 
 func TestInvoke(t *testing.T) {
 	RegisterFailHandler(Fail)
 	RunSpecs(t, "Invoke Suite")
 }
+
+const packagePath = "github.com/containernetworking/cni/plugins/test/noop"
+
+var pathToPlugin string
+
+var _ = SynchronizedBeforeSuite(func() []byte {
+	var err error
+	pathToPlugin, err = gexec.Build(packagePath)
+	Expect(err).NotTo(HaveOccurred())
+	return []byte(pathToPlugin)
+}, func(crossNodeData []byte) {
+	pathToPlugin = string(crossNodeData)
+})
+
+var _ = SynchronizedAfterSuite(func() {}, func() {
+	gexec.CleanupBuildArtifacts()
+})

pkg/invoke/os_unix.go

@@ -0,0 +1,21 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build darwin || dragonfly || freebsd || linux || netbsd || openbsd || solaris
+// +build darwin dragonfly freebsd linux netbsd openbsd solaris
+
+package invoke
+
+// Valid file extensions for plugin executables.
+var ExecutableFileExtensions = []string{""}

pkg/invoke/os_windows.go

@@ -0,0 +1,18 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package invoke
+
+// Valid file extensions for plugin executables.
+var ExecutableFileExtensions = []string{".exe", ""}

pkg/invoke/raw_exec.go

@@ -0,0 +1,88 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package invoke
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os/exec"
+	"strings"
+	"time"
+
+	"github.com/containernetworking/cni/pkg/types"
+)
+
+type RawExec struct {
+	Stderr io.Writer
+}
+
+func (e *RawExec) ExecPlugin(ctx context.Context, pluginPath string, stdinData []byte, environ []string) ([]byte, error) {
+	stdout := &bytes.Buffer{}
+	stderr := &bytes.Buffer{}
+	c := exec.CommandContext(ctx, pluginPath)
+	c.Env = environ
+	c.Stdin = bytes.NewBuffer(stdinData)
+	c.Stdout = stdout
+	c.Stderr = stderr
+
+	// Retry the command on "text file busy" errors
+	for i := 0; i <= 5; i++ {
+		err := c.Run()
+
+		// Command succeeded
+		if err == nil {
+			break
+		}
+
+		// If the plugin is currently about to be written, then we wait a
+		// second and try it again
+		if strings.Contains(err.Error(), "text file busy") {
+			time.Sleep(time.Second)
+			continue
+		}
+
+		// All other errors except than the busy text file
+		return nil, e.pluginErr(err, stdout.Bytes(), stderr.Bytes())
+	}
+
+	// Copy stderr to caller's buffer in case plugin printed to both
+	// stdout and stderr for some reason. Ignore failures as stderr is
+	// only informational.
+	if e.Stderr != nil && stderr.Len() > 0 {
+		_, _ = stderr.WriteTo(e.Stderr)
+	}
+	return stdout.Bytes(), nil
+}
+
+func (e *RawExec) pluginErr(err error, stdout, stderr []byte) error {
+	emsg := types.Error{}
+	if len(stdout) == 0 {
+		if len(stderr) == 0 {
+			emsg.Msg = fmt.Sprintf("netplugin failed with no error message: %v", err)
+		} else {
+			emsg.Msg = fmt.Sprintf("netplugin failed: %q", string(stderr))
+		}
+	} else if perr := json.Unmarshal(stdout, &emsg); perr != nil {
+		emsg.Msg = fmt.Sprintf("netplugin failed but error parsing its diagnostic message %q: %v", string(stdout), perr)
+	}
+	return &emsg
+}
+
+func (e *RawExec) FindInPath(plugin string, paths []string) (string, error) {
+	return FindInPath(plugin, paths)
+}

pkg/invoke/raw_exec_test.go

@@ -0,0 +1,149 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package invoke_test
+
+import (
+	"bytes"
+	"context"
+	"os"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	"github.com/containernetworking/cni/pkg/invoke"
+	noop_debug "github.com/containernetworking/cni/plugins/test/noop/debug"
+)
+
+var _ = Describe("RawExec", func() {
+	var (
+		debugFileName string
+		debug         *noop_debug.Debug
+		environ       []string
+		stdin         []byte
+		execer        *invoke.RawExec
+		ctx           context.Context
+	)
+
+	const reportResult = `{ "some": "result" }`
+
+	BeforeEach(func() {
+		debugFile, err := os.CreateTemp("", "cni_debug")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(debugFile.Close()).To(Succeed())
+		debugFileName = debugFile.Name()
+
+		debug = &noop_debug.Debug{
+			ReportResult: reportResult,
+			ReportStderr: "some stderr message",
+		}
+		Expect(debug.WriteDebug(debugFileName)).To(Succeed())
+
+		environ = []string{
+			"CNI_COMMAND=ADD",
+			"CNI_CONTAINERID=some-container-id",
+			"CNI_ARGS=DEBUG=" + debugFileName,
+			"CNI_NETNS=/some/netns/path",
+			"CNI_PATH=/some/bin/path",
+			"CNI_IFNAME=some-eth0",
+		}
+		stdin = []byte(`{"name": "raw-exec-test", "some":"stdin-json", "cniVersion": "0.3.1"}`)
+		execer = &invoke.RawExec{}
+		ctx = context.TODO()
+	})
+
+	AfterEach(func() {
+		Expect(os.Remove(debugFileName)).To(Succeed())
+	})
+
+	It("runs the plugin with the given stdin and environment", func() {
+		_, err := execer.ExecPlugin(ctx, pathToPlugin, stdin, environ)
+		Expect(err).NotTo(HaveOccurred())
+
+		debug, err := noop_debug.ReadDebug(debugFileName)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(debug.Command).To(Equal("ADD"))
+		Expect(debug.CmdArgs.StdinData).To(Equal(stdin))
+		Expect(debug.CmdArgs.Netns).To(Equal("/some/netns/path"))
+	})
+
+	It("returns the resulting stdout as bytes", func() {
+		resultBytes, err := execer.ExecPlugin(ctx, pathToPlugin, stdin, environ)
+		Expect(err).NotTo(HaveOccurred())
+
+		Expect(resultBytes).To(BeEquivalentTo(reportResult))
+	})
+
+	Context("when the Stderr writer is set", func() {
+		var stderrBuffer *bytes.Buffer
+
+		BeforeEach(func() {
+			stderrBuffer = &bytes.Buffer{}
+			execer.Stderr = stderrBuffer
+		})
+
+		It("forwards any stderr bytes to the Stderr writer", func() {
+			_, err := execer.ExecPlugin(ctx, pathToPlugin, stdin, environ)
+			Expect(err).NotTo(HaveOccurred())
+
+			Expect(stderrBuffer.String()).To(Equal("some stderr message"))
+		})
+	})
+
+	Context("when the plugin errors", func() {
+		BeforeEach(func() {
+			debug.ReportResult = ""
+		})
+
+		Context("and writes valid error JSON to stdout", func() {
+			It("wraps and returns the error", func() {
+				debug.ReportError = "banana"
+				Expect(debug.WriteDebug(debugFileName)).To(Succeed())
+				_, err := execer.ExecPlugin(ctx, pathToPlugin, stdin, environ)
+				Expect(err).To(HaveOccurred())
+				Expect(err).To(MatchError("banana"))
+			})
+		})
+
+		Context("and writes to stderr", func() {
+			It("returns an error message with stderr output", func() {
+				debug.ExitWithCode = 1
+				Expect(debug.WriteDebug(debugFileName)).To(Succeed())
+				_, err := execer.ExecPlugin(ctx, pathToPlugin, stdin, environ)
+				Expect(err).To(HaveOccurred())
+				Expect(err).To(MatchError(`netplugin failed: "some stderr message"`))
+			})
+		})
+	})
+
+	Context("when the plugin errors with no output on stdout or stderr", func() {
+		It("returns the exec error message", func() {
+			debug.ExitWithCode = 1
+			debug.ReportResult = ""
+			debug.ReportStderr = ""
+			Expect(debug.WriteDebug(debugFileName)).To(Succeed())
+			_, err := execer.ExecPlugin(ctx, pathToPlugin, stdin, environ)
+			Expect(err).To(HaveOccurred())
+			Expect(err).To(MatchError("netplugin failed with no error message: exit status 1"))
+		})
+	})
+
+	Context("when the system is unable to execute the plugin", func() {
+		It("returns the error", func() {
+			_, err := execer.ExecPlugin(ctx, "/tmp/some/invalid/plugin/path", stdin, environ)
+			Expect(err).To(HaveOccurred())
+			Expect(err).To(MatchError(ContainSubstring("/tmp/some/invalid/plugin/path")))
+		})
+	})
+})

pkg/ip/cidr.go

@@ -1,51 +0,0 @@
-// Copyright 2015 CNI authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package ip
-
-import (
-	"math/big"
-	"net"
-)
-
-// NextIP returns IP incremented by 1
-func NextIP(ip net.IP) net.IP {
-	i := ipToInt(ip)
-	return intToIP(i.Add(i, big.NewInt(1)))
-}
-
-// PrevIP returns IP decremented by 1
-func PrevIP(ip net.IP) net.IP {
-	i := ipToInt(ip)
-	return intToIP(i.Sub(i, big.NewInt(1)))
-}
-
-func ipToInt(ip net.IP) *big.Int {
-	if v := ip.To4(); v != nil {
-		return big.NewInt(0).SetBytes(v)
-	}
-	return big.NewInt(0).SetBytes(ip.To16())
-}
-
-func intToIP(i *big.Int) net.IP {
-	return net.IP(i.Bytes())
-}
-
-// Network masks off the host portion of the IP
-func Network(ipn *net.IPNet) *net.IPNet {
-	return &net.IPNet{
-		IP:   ipn.IP.Mask(ipn.Mask),
-		Mask: ipn.Mask,
-	}
-}

pkg/ip/ipforward.go

@@ -1,31 +0,0 @@
-// Copyright 2015 CNI authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package ip
-
-import (
-	"io/ioutil"
-)
-
-func EnableIP4Forward() error {
-	return echo1("/proc/sys/net/ipv4/ip_forward")
-}
-
-func EnableIP6Forward() error {
-	return echo1("/proc/sys/net/ipv6/conf/all/forwarding")
-}
-
-func echo1(f string) error {
-	return ioutil.WriteFile(f, []byte("1"), 0644)
-}

pkg/ip/ipmasq.go

@@ -1,66 +0,0 @@
-// Copyright 2015 CNI authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package ip
-
-import (
-	"fmt"
-	"net"
-
-	"github.com/coreos/go-iptables/iptables"
-)
-
-// SetupIPMasq installs iptables rules to masquerade traffic
-// coming from ipn and going outside of it
-func SetupIPMasq(ipn *net.IPNet, chain string, comment string) error {
-	ipt, err := iptables.New()
-	if err != nil {
-		return fmt.Errorf("failed to locate iptables: %v", err)
-	}
-
-	if err = ipt.NewChain("nat", chain); err != nil {
-		if err.(*iptables.Error).ExitStatus() != 1 {
-			// TODO(eyakubovich): assumes exit status 1 implies chain exists
-			return err
-		}
-	}
-
-	if err = ipt.AppendUnique("nat", chain, "-d", ipn.String(), "-j", "ACCEPT", "-m", "comment", "--comment", comment); err != nil {
-		return err
-	}
-
-	if err = ipt.AppendUnique("nat", chain, "!", "-d", "224.0.0.0/4", "-j", "MASQUERADE", "-m", "comment", "--comment", comment); err != nil {
-		return err
-	}
-
-	return ipt.AppendUnique("nat", "POSTROUTING", "-s", ipn.String(), "-j", chain, "-m", "comment", "--comment", comment)
-}
-
-// TeardownIPMasq undoes the effects of SetupIPMasq
-func TeardownIPMasq(ipn *net.IPNet, chain string, comment string) error {
-	ipt, err := iptables.New()
-	if err != nil {
-		return fmt.Errorf("failed to locate iptables: %v", err)
-	}
-
-	if err = ipt.Delete("nat", "POSTROUTING", "-s", ipn.String(), "-j", chain, "-m", "comment", "--comment", comment); err != nil {
-		return err
-	}
-
-	if err = ipt.ClearChain("nat", chain); err != nil {
-		return err
-	}
-
-	return ipt.DeleteChain("nat", chain)
-}

pkg/ip/link.go

@@ -1,153 +0,0 @@
-// Copyright 2015 CNI authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package ip
-
-import (
-	"crypto/rand"
-	"fmt"
-	"net"
-	"os"
-
-	"github.com/containernetworking/cni/pkg/ns"
-	"github.com/vishvananda/netlink"
-)
-
-func makeVethPair(name, peer string, mtu int) (netlink.Link, error) {
-	veth := &netlink.Veth{
-		LinkAttrs: netlink.LinkAttrs{
-			Name:  name,
-			Flags: net.FlagUp,
-			MTU:   mtu,
-		},
-		PeerName: peer,
-	}
-	if err := netlink.LinkAdd(veth); err != nil {
-		return nil, err
-	}
-
-	return veth, nil
-}
-
-func makeVeth(name string, mtu int) (peerName string, veth netlink.Link, err error) {
-	for i := 0; i < 10; i++ {
-		peerName, err = RandomVethName()
-		if err != nil {
-			return
-		}
-
-		veth, err = makeVethPair(name, peerName, mtu)
-		switch {
-		case err == nil:
-			return
-
-		case os.IsExist(err):
-			continue
-
-		default:
-			err = fmt.Errorf("failed to make veth pair: %v", err)
-			return
-		}
-	}
-
-	// should really never be hit
-	err = fmt.Errorf("failed to find a unique veth name")
-	return
-}
-
-// RandomVethName returns string "veth" with random prefix (hashed from entropy)
-func RandomVethName() (string, error) {
-	entropy := make([]byte, 4)
-	_, err := rand.Reader.Read(entropy)
-	if err != nil {
-		return "", fmt.Errorf("failed to generate random veth name: %v", err)
-	}
-
-	// NetworkManager (recent versions) will ignore veth devices that start with "veth"
-	return fmt.Sprintf("veth%x", entropy), nil
-}
-
-// SetupVeth sets up a virtual ethernet link.
-// Should be in container netns, and will switch back to hostNS to set the host
-// veth end up.
-func SetupVeth(contVethName string, mtu int, hostNS ns.NetNS) (hostVeth, contVeth netlink.Link, err error) {
-	var hostVethName string
-	hostVethName, contVeth, err = makeVeth(contVethName, mtu)
-	if err != nil {
-		return
-	}
-
-	if err = netlink.LinkSetUp(contVeth); err != nil {
-		err = fmt.Errorf("failed to set %q up: %v", contVethName, err)
-		return
-	}
-
-	hostVeth, err = netlink.LinkByName(hostVethName)
-	if err != nil {
-		err = fmt.Errorf("failed to lookup %q: %v", hostVethName, err)
-		return
-	}
-
-	if err = netlink.LinkSetNsFd(hostVeth, int(hostNS.Fd())); err != nil {
-		err = fmt.Errorf("failed to move veth to host netns: %v", err)
-		return
-	}
-
-	err = hostNS.Do(func(_ ns.NetNS) error {
-		hostVeth, err := netlink.LinkByName(hostVethName)
-		if err != nil {
-			return fmt.Errorf("failed to lookup %q in %q: %v", hostVethName, hostNS.Path(), err)
-		}
-
-		if err = netlink.LinkSetUp(hostVeth); err != nil {
-			return fmt.Errorf("failed to set %q up: %v", hostVethName, err)
-		}
-		return nil
-	})
-	return
-}
-
-// DelLinkByName removes an interface link.
-func DelLinkByName(ifName string) error {
-	iface, err := netlink.LinkByName(ifName)
-	if err != nil {
-		return fmt.Errorf("failed to lookup %q: %v", ifName, err)
-	}
-
-	if err = netlink.LinkDel(iface); err != nil {
-		return fmt.Errorf("failed to delete %q: %v", ifName, err)
-	}
-
-	return nil
-}
-
-// DelLinkByNameAddr remove an interface returns its IP address
-// of the specified family
-func DelLinkByNameAddr(ifName string, family int) (*net.IPNet, error) {
-	iface, err := netlink.LinkByName(ifName)
-	if err != nil {
-		return nil, fmt.Errorf("failed to lookup %q: %v", ifName, err)
-	}
-
-	addrs, err := netlink.AddrList(iface, family)
-	if err != nil || len(addrs) == 0 {
-		return nil, fmt.Errorf("failed to get IP addresses for %q: %v", ifName, err)
-	}
-
-	if err = netlink.LinkDel(iface); err != nil {
-		return nil, fmt.Errorf("failed to delete %q: %v", ifName, err)
-	}
-
-	return addrs[0].IPNet, nil
-}

pkg/ip/route.go

@@ -1,47 +0,0 @@
-// Copyright 2015 CNI authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package ip
-
-import (
-	"net"
-
-	"github.com/vishvananda/netlink"
-)
-
-// AddDefaultRoute sets the default route on the given gateway.
-func AddDefaultRoute(gw net.IP, dev netlink.Link) error {
-	_, defNet, _ := net.ParseCIDR("0.0.0.0/0")
-	return AddRoute(defNet, gw, dev)
-}
-
-// AddRoute adds a universally-scoped route to a device.
-func AddRoute(ipn *net.IPNet, gw net.IP, dev netlink.Link) error {
-	return netlink.RouteAdd(&netlink.Route{
-		LinkIndex: dev.Attrs().Index,
-		Scope:     netlink.SCOPE_UNIVERSE,
-		Dst:       ipn,
-		Gw:        gw,
-	})
-}
-
-// AddHostRoute adds a host-scoped route to a device.
-func AddHostRoute(ipn *net.IPNet, gw net.IP, dev netlink.Link) error {
-	return netlink.RouteAdd(&netlink.Route{
-		LinkIndex: dev.Attrs().Index,
-		Scope:     netlink.SCOPE_HOST,
-		Dst:       ipn,
-		Gw:        gw,
-	})
-}

pkg/ipam/ipam.go

@@ -1,68 +0,0 @@
-// Copyright 2015 CNI authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package ipam
-
-import (
-	"fmt"
-	"os"
-
-	"github.com/containernetworking/cni/pkg/invoke"
-	"github.com/containernetworking/cni/pkg/ip"
-	"github.com/containernetworking/cni/pkg/types"
-
-	"github.com/vishvananda/netlink"
-)
-
-func ExecAdd(plugin string, netconf []byte) (*types.Result, error) {
-	return invoke.DelegateAdd(plugin, netconf)
-}
-
-func ExecDel(plugin string, netconf []byte) error {
-	return invoke.DelegateDel(plugin, netconf)
-}
-
-// ConfigureIface takes the result of IPAM plugin and
-// applies to the ifName interface
-func ConfigureIface(ifName string, res *types.Result) error {
-	link, err := netlink.LinkByName(ifName)
-	if err != nil {
-		return fmt.Errorf("failed to lookup %q: %v", ifName, err)
-	}
-
-	if err := netlink.LinkSetUp(link); err != nil {
-		return fmt.Errorf("failed to set %q UP: %v", ifName, err)
-	}
-
-	// TODO(eyakubovich): IPv6
-	addr := &netlink.Addr{IPNet: &res.IP4.IP, Label: ""}
-	if err = netlink.AddrAdd(link, addr); err != nil {
-		return fmt.Errorf("failed to add IP addr to %q: %v", ifName, err)
-	}
-
-	for _, r := range res.IP4.Routes {
-		gw := r.GW
-		if gw == nil {
-			gw = res.IP4.Gateway
-		}
-		if err = ip.AddRoute(&r.Dst, gw, link); err != nil {
-			// we skip over duplicate routes as we assume the first one wins
-			if !os.IsExist(err) {
-				return fmt.Errorf("failed to add route '%v via %v dev %v': %v", r.Dst, gw, ifName, err)
-			}
-		}
-	}
-
-	return nil
-}

pkg/ns/README.md

@@ -1,31 +0,0 @@
-### Namespaces, Threads, and Go
-On Linux each OS thread can have a different network namespace.  Go's thread scheduling model switches goroutines between OS threads based on OS thread load and whether the goroutine would block other goroutines.  This can result in a goroutine switching network namespaces without notice and lead to errors in your code.
-
-### Namespace Switching
-Switching namespaces with the `ns.Set()` method is not recommended without additional strategies to prevent unexpected namespace changes when your goroutines switch OS threads.
-
-Go provides the `runtime.LockOSThread()` function to ensure a specific goroutine executes on its current OS thread and prevents any other goroutine from running in that thread until the locked one exits.  Careful usage of `LockOSThread()` and goroutines can provide good control over which network namespace a given goroutine executes in.
-
-For example, you cannot rely on the `ns.Set()` namespace being the current namespace after the `Set()` call unless you do two things.  First, the goroutine calling `Set()` must have previously called `LockOSThread()`.  Second, you must ensure `runtime.UnlockOSThread()` is not called somewhere in-between.  You also cannot rely on the initial network namespace remaining the current network namespace if any other code in your program switches namespaces, unless you have already called `LockOSThread()` in that goroutine.  Note that `LockOSThread()` prevents the Go scheduler from optimally scheduling goroutines for best performance, so `LockOSThread()` should only be used in small, isolated goroutines that release the lock quickly.
-
-### Do() The Recommended Thing
-The `ns.Do()` method provides control over network namespaces for you by implementing these strategies. All code dependent on a particular network namespace should be wrapped in the `ns.Do()` method to ensure the correct namespace is selected for the duration of your code.  For example:
-
-```go
-targetNs, err := ns.NewNS()
-if err != nil {
-    return err
-}
-err = targetNs.Do(func(hostNs ns.NetNS) error {
-	dummy := &netlink.Dummy{
-		LinkAttrs: netlink.LinkAttrs{
-			Name: "dummy0",
-		},
-	}
-	return netlink.LinkAdd(dummy)
-})
-```
-
-### Further Reading
- - https://github.com/golang/go/wiki/LockOSThread
- - http://morsmachine.dk/go-scheduler

pkg/ns/ns.go

@@ -1,237 +0,0 @@
-// Copyright 2015 CNI authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package ns
-
-import (
-	"crypto/rand"
-	"fmt"
-	"os"
-	"path"
-	"runtime"
-	"sync"
-
-	"golang.org/x/sys/unix"
-)
-
-type NetNS interface {
-	// Executes the passed closure in this object's network namespace,
-	// attemtping to restore the original namespace before returning.
-	// However, since each OS thread can have a different network namespace,
-	// and Go's thread scheduling is highly variable, callers cannot
-	// guarantee any specific namespace is set unless operations that
-	// require that namespace are wrapped with Do().  Also, no code called
-	// from Do() should call runtime.UnlockOSThread(), or the risk
-	// of executing code in an incorrect namespace will be greater.  See
-	// https://github.com/golang/go/wiki/LockOSThread for further details.
-	Do(toRun func(NetNS) error) error
-
-	// Sets the current network namespace to this object's network namespace.
-	// Note that since Go's thread scheduling is highly variable, callers
-	// cannot guarantee the requested namespace will be the current namespace
-	// after this function is called; to ensure this wrap operations that
-	// require the namespace with Do() instead.
-	Set() error
-
-	// Returns the filesystem path representing this object's network namespace
-	Path() string
-
-	// Returns a file descriptor representing this object's network namespace
-	Fd() uintptr
-
-	// Cleans up this instance of the network namespace; if this instance
-	// is the last user the namespace will be destroyed
-	Close() error
-}
-
-type netNS struct {
-	file    *os.File
-	mounted bool
-}
-
-func getCurrentThreadNetNSPath() string {
-	// /proc/self/ns/net returns the namespace of the main thread, not
-	// of whatever thread this goroutine is running on.  Make sure we
-	// use the thread's net namespace since the thread is switching around
-	return fmt.Sprintf("/proc/%d/task/%d/ns/net", os.Getpid(), unix.Gettid())
-}
-
-// Returns an object representing the current OS thread's network namespace
-func GetCurrentNS() (NetNS, error) {
-	return GetNS(getCurrentThreadNetNSPath())
-}
-
-// Returns an object representing the namespace referred to by @path
-func GetNS(nspath string) (NetNS, error) {
-	fd, err := os.Open(nspath)
-	if err != nil {
-		return nil, err
-	}
-	return &netNS{file: fd}, nil
-}
-
-// Creates a new persistent network namespace and returns an object
-// representing that namespace, without switching to it
-func NewNS() (NetNS, error) {
-	const nsRunDir = "/var/run/netns"
-
-	b := make([]byte, 16)
-	_, err := rand.Reader.Read(b)
-	if err != nil {
-		return nil, fmt.Errorf("failed to generate random netns name: %v", err)
-	}
-
-	err = os.MkdirAll(nsRunDir, 0755)
-	if err != nil {
-		return nil, err
-	}
-
-	// create an empty file at the mount point
-	nsName := fmt.Sprintf("cni-%x-%x-%x-%x-%x", b[0:4], b[4:6], b[6:8], b[8:10], b[10:])
-	nsPath := path.Join(nsRunDir, nsName)
-	mountPointFd, err := os.Create(nsPath)
-	if err != nil {
-		return nil, err
-	}
-	mountPointFd.Close()
-
-	// Ensure the mount point is cleaned up on errors; if the namespace
-	// was successfully mounted this will have no effect because the file
-	// is in-use
-	defer os.RemoveAll(nsPath)
-
-	var wg sync.WaitGroup
-	wg.Add(1)
-
-	// do namespace work in a dedicated goroutine, so that we can safely
-	// Lock/Unlock OSThread without upsetting the lock/unlock state of
-	// the caller of this function
-	var fd *os.File
-	go (func() {
-		defer wg.Done()
-		runtime.LockOSThread()
-
-		var origNS NetNS
-		origNS, err = GetNS(getCurrentThreadNetNSPath())
-		if err != nil {
-			return
-		}
-		defer origNS.Close()
-
-		// create a new netns on the current thread
-		err = unix.Unshare(unix.CLONE_NEWNET)
-		if err != nil {
-			return
-		}
-		defer origNS.Set()
-
-		// bind mount the new netns from the current thread onto the mount point
-		err = unix.Mount(getCurrentThreadNetNSPath(), nsPath, "none", unix.MS_BIND, "")
-		if err != nil {
-			return
-		}
-
-		fd, err = os.Open(nsPath)
-		if err != nil {
-			return
-		}
-	})()
-	wg.Wait()
-
-	if err != nil {
-		unix.Unmount(nsPath, unix.MNT_DETACH)
-		return nil, fmt.Errorf("failed to create namespace: %v", err)
-	}
-
-	return &netNS{file: fd, mounted: true}, nil
-}
-
-func (ns *netNS) Path() string {
-	return ns.file.Name()
-}
-
-func (ns *netNS) Fd() uintptr {
-	return ns.file.Fd()
-}
-
-func (ns *netNS) Close() error {
-	ns.file.Close()
-
-	if ns.mounted {
-		if err := unix.Unmount(ns.file.Name(), unix.MNT_DETACH); err != nil {
-			return fmt.Errorf("Failed to unmount namespace %s: %v", ns.file.Name(), err)
-		}
-		if err := os.RemoveAll(ns.file.Name()); err != nil {
-			return fmt.Errorf("Failed to clean up namespace %s: %v", ns.file.Name(), err)
-		}
-	}
-	return nil
-}
-
-func (ns *netNS) Do(toRun func(NetNS) error) error {
-	containedCall := func(hostNS NetNS) error {
-		threadNS, err := GetNS(getCurrentThreadNetNSPath())
-		if err != nil {
-			return fmt.Errorf("failed to open current netns: %v", err)
-		}
-		defer threadNS.Close()
-
-		// switch to target namespace
-		if err = ns.Set(); err != nil {
-			return fmt.Errorf("error switching to ns %v: %v", ns.file.Name(), err)
-		}
-		defer threadNS.Set() // switch back
-
-		return toRun(hostNS)
-	}
-
-	// save a handle to current network namespace
-	hostNS, err := GetNS(getCurrentThreadNetNSPath())
-	if err != nil {
-		return fmt.Errorf("Failed to open current namespace: %v", err)
-	}
-	defer hostNS.Close()
-
-	var wg sync.WaitGroup
-	wg.Add(1)
-
-	var innerError error
-	go func() {
-		defer wg.Done()
-		runtime.LockOSThread()
-		innerError = containedCall(hostNS)
-	}()
-	wg.Wait()
-
-	return innerError
-}
-
-func (ns *netNS) Set() error {
-	if _, _, err := unix.Syscall(unix.SYS_SETNS, ns.Fd(), uintptr(unix.CLONE_NEWNET), 0); err != 0 {
-		return fmt.Errorf("Error switching to ns %v: %v", ns.file.Name(), err)
-	}
-
-	return nil
-}
-
-// WithNetNSPath executes the passed closure under the given network
-// namespace, restoring the original namespace afterwards.
-func WithNetNSPath(nspath string, toRun func(NetNS) error) error {
-	ns, err := GetNS(nspath)
-	if err != nil {
-		return fmt.Errorf("Failed to open %v: %v", nspath, err)
-	}
-	defer ns.Close()
-	return ns.Do(toRun)
-}

pkg/ns/ns_darwin.go

@@ -0,0 +1,21 @@
+// Copyright 2022 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package ns
+
+import "github.com/containernetworking/cni/pkg/types"
+
+func CheckNetNS(nsPath string) (bool, *types.Error) {
+	return false, nil
+}

pkg/ns/ns_linux.go

@@ -0,0 +1,50 @@
+// Copyright 2022 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package ns
+
+import (
+	"runtime"
+
+	"github.com/vishvananda/netns"
+
+	"github.com/containernetworking/cni/pkg/types"
+)
+
+// Returns an object representing the current OS thread's network namespace
+func getCurrentNS() (netns.NsHandle, error) {
+	// Lock the thread in case other goroutine executes in it and changes its
+	// network namespace after getCurrentThreadNetNSPath(), otherwise it might
+	// return an unexpected network namespace.
+	runtime.LockOSThread()
+	defer runtime.UnlockOSThread()
+	return netns.Get()
+}
+
+func CheckNetNS(nsPath string) (bool, *types.Error) {
+	ns, err := netns.GetFromPath(nsPath)
+	// Let plugins check whether nsPath from args is valid. Also support CNI DEL for empty nsPath as already-deleted nsPath.
+	if err != nil {
+		return false, nil
+	}
+	defer ns.Close()
+
+	pluginNS, err := getCurrentNS()
+	if err != nil {
+		return false, types.NewError(types.ErrInvalidNetNS, "get plugin's netns failed", "")
+	}
+	defer pluginNS.Close()
+
+	return pluginNS.Equal(ns), nil
+}

pkg/ns/ns_test.go

@@ -1,181 +0,0 @@
-// Copyright 2016 CNI authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package ns_test
-
-import (
-	"errors"
-	"fmt"
-	"os"
-	"path/filepath"
-
-	"github.com/containernetworking/cni/pkg/ns"
-	. "github.com/onsi/ginkgo"
-	. "github.com/onsi/gomega"
-	"golang.org/x/sys/unix"
-)
-
-func getInodeCurNetNS() (uint64, error) {
-	curNS, err := ns.GetCurrentNS()
-	if err != nil {
-		return 0, err
-	}
-	defer curNS.Close()
-	return getInodeNS(curNS)
-}
-
-func getInodeNS(netns ns.NetNS) (uint64, error) {
-	return getInodeFd(int(netns.Fd()))
-}
-
-func getInode(path string) (uint64, error) {
-	file, err := os.Open(path)
-	if err != nil {
-		return 0, err
-	}
-	defer file.Close()
-	return getInodeFd(int(file.Fd()))
-}
-
-func getInodeFd(fd int) (uint64, error) {
-	stat := &unix.Stat_t{}
-	err := unix.Fstat(fd, stat)
-	return stat.Ino, err
-}
-
-var _ = Describe("Linux namespace operations", func() {
-	Describe("WithNetNS", func() {
-		var (
-			originalNetNS ns.NetNS
-			targetNetNS   ns.NetNS
-		)
-
-		BeforeEach(func() {
-			var err error
-
-			originalNetNS, err = ns.NewNS()
-			Expect(err).NotTo(HaveOccurred())
-
-			targetNetNS, err = ns.NewNS()
-			Expect(err).NotTo(HaveOccurred())
-		})
-
-		AfterEach(func() {
-			Expect(targetNetNS.Close()).To(Succeed())
-			Expect(originalNetNS.Close()).To(Succeed())
-		})
-
-		It("executes the callback within the target network namespace", func() {
-			expectedInode, err := getInodeNS(targetNetNS)
-			Expect(err).NotTo(HaveOccurred())
-
-			err = targetNetNS.Do(func(ns.NetNS) error {
-				defer GinkgoRecover()
-
-				actualInode, err := getInodeCurNetNS()
-				Expect(err).NotTo(HaveOccurred())
-				Expect(actualInode).To(Equal(expectedInode))
-				return nil
-			})
-			Expect(err).NotTo(HaveOccurred())
-		})
-
-		It("provides the original namespace as the argument to the callback", func() {
-			// Ensure we start in originalNetNS
-			err := originalNetNS.Do(func(ns.NetNS) error {
-				defer GinkgoRecover()
-
-				origNSInode, err := getInodeNS(originalNetNS)
-				Expect(err).NotTo(HaveOccurred())
-
-				err = targetNetNS.Do(func(hostNS ns.NetNS) error {
-					defer GinkgoRecover()
-
-					hostNSInode, err := getInodeNS(hostNS)
-					Expect(err).NotTo(HaveOccurred())
-					Expect(hostNSInode).To(Equal(origNSInode))
-					return nil
-				})
-				return nil
-			})
-			Expect(err).NotTo(HaveOccurred())
-		})
-
-		Context("when the callback returns an error", func() {
-			It("restores the calling thread to the original namespace before returning", func() {
-				err := originalNetNS.Do(func(ns.NetNS) error {
-					defer GinkgoRecover()
-
-					preTestInode, err := getInodeCurNetNS()
-					Expect(err).NotTo(HaveOccurred())
-
-					_ = targetNetNS.Do(func(ns.NetNS) error {
-						return errors.New("potato")
-					})
-
-					postTestInode, err := getInodeCurNetNS()
-					Expect(err).NotTo(HaveOccurred())
-					Expect(postTestInode).To(Equal(preTestInode))
-					return nil
-				})
-				Expect(err).NotTo(HaveOccurred())
-			})
-
-			It("returns the error from the callback", func() {
-				err := targetNetNS.Do(func(ns.NetNS) error {
-					return errors.New("potato")
-				})
-				Expect(err).To(MatchError("potato"))
-			})
-		})
-
-		Describe("validating inode mapping to namespaces", func() {
-			It("checks that different namespaces have different inodes", func() {
-				origNSInode, err := getInodeNS(originalNetNS)
-				Expect(err).NotTo(HaveOccurred())
-
-				testNsInode, err := getInodeNS(targetNetNS)
-				Expect(err).NotTo(HaveOccurred())
-
-				Expect(testNsInode).NotTo(Equal(0))
-				Expect(testNsInode).NotTo(Equal(origNSInode))
-			})
-
-			It("should not leak a closed netns onto any threads in the process", func() {
-				By("creating a new netns")
-				createdNetNS, err := ns.NewNS()
-				Expect(err).NotTo(HaveOccurred())
-
-				By("discovering the inode of the created netns")
-				createdNetNSInode, err := getInodeNS(createdNetNS)
-				Expect(err).NotTo(HaveOccurred())
-				createdNetNS.Close()
-
-				By("comparing against the netns inode of every thread in the process")
-				for _, netnsPath := range allNetNSInCurrentProcess() {
-					netnsInode, err := getInode(netnsPath)
-					Expect(err).NotTo(HaveOccurred())
-					Expect(netnsInode).NotTo(Equal(createdNetNSInode))
-				}
-			})
-		})
-	})
-})
-
-func allNetNSInCurrentProcess() []string {
-	pid := unix.Getpid()
-	paths, err := filepath.Glob(fmt.Sprintf("/proc/%d/task/*/ns/net", pid))
-	Expect(err).NotTo(HaveOccurred())
-	return paths
-}

pkg/ns/ns_windows.go

@@ -0,0 +1,21 @@
+// Copyright 2022 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package ns
+
+import "github.com/containernetworking/cni/pkg/types"
+
+func CheckNetNS(nsPath string) (bool, *types.Error) {
+	return false, nil
+}

pkg/skel/skel.go

@@ -1,4 +1,4 @@
-// Copyright 2014 CNI authors
+// Copyright 2014-2016 CNI authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -17,101 +17,423 @@
 package skel
 
 import (
+	"bytes"
+	"encoding/json"
+	"errors"
 	"fmt"
-	"io/ioutil"
+	"io"
 	"log"
 	"os"
+	"strings"
 
+	"github.com/containernetworking/cni/pkg/ns"
 	"github.com/containernetworking/cni/pkg/types"
+	"github.com/containernetworking/cni/pkg/utils"
+	"github.com/containernetworking/cni/pkg/version"
 )
 
 // CmdArgs captures all the arguments passed in to the plugin
 // via both env vars and stdin
 type CmdArgs struct {
-	ContainerID string
-	Netns       string
-	IfName      string
-	Args        string
-	Path        string
-	StdinData   []byte
+	ContainerID   string
+	Netns         string
+	IfName        string
+	Args          string
+	Path          string
+	NetnsOverride string
+	StdinData     []byte
 }
 
-// PluginMain is the "main" for a plugin. It accepts
-// two callback functions for add and del commands.
-func PluginMain(cmdAdd, cmdDel func(_ *CmdArgs) error) {
-	var cmd, contID, netns, ifName, args, path string
+type dispatcher struct {
+	Getenv func(string) string
+	Stdin  io.Reader
+	Stdout io.Writer
+	Stderr io.Writer
+
+	ConfVersionDecoder version.ConfigDecoder
+	VersionReconciler  version.Reconciler
+}
+
+type reqForCmdEntry map[string]bool
+
+func (t *dispatcher) getCmdArgsFromEnv() (string, *CmdArgs, *types.Error) {
+	var cmd, contID, netns, ifName, args, path, netnsOverride string
 
 	vars := []struct {
-		name string
-		val  *string
-		req  bool
+		name       string
+		val        *string
+		reqForCmd  reqForCmdEntry
+		validateFn func(string) *types.Error
 	}{
-		{"CNI_COMMAND", &cmd, true},
-		{"CNI_CONTAINERID", &contID, false},
-		{"CNI_NETNS", &netns, true},
-		{"CNI_IFNAME", &ifName, true},
-		{"CNI_ARGS", &args, false},
-		{"CNI_PATH", &path, true},
+		{
+			"CNI_COMMAND",
+			&cmd,
+			reqForCmdEntry{
+				"ADD":    true,
+				"CHECK":  true,
+				"DEL":    true,
+				"GC":     true,
+				"STATUS": true,
+			},
+			nil,
+		},
+		{
+			"CNI_CONTAINERID",
+			&contID,
+			reqForCmdEntry{
+				"ADD":   true,
+				"CHECK": true,
+				"DEL":   true,
+			},
+			utils.ValidateContainerID,
+		},
+		{
+			"CNI_NETNS",
+			&netns,
+			reqForCmdEntry{
+				"ADD":   true,
+				"CHECK": true,
+				"DEL":   false,
+			},
+			nil,
+		},
+		{
+			"CNI_IFNAME",
+			&ifName,
+			reqForCmdEntry{
+				"ADD":   true,
+				"CHECK": true,
+				"DEL":   true,
+			},
+			utils.ValidateInterfaceName,
+		},
+		{
+			"CNI_ARGS",
+			&args,
+			reqForCmdEntry{
+				"ADD":   false,
+				"CHECK": false,
+				"DEL":   false,
+			},
+			nil,
+		},
+		{
+			"CNI_PATH",
+			&path,
+			reqForCmdEntry{
+				"ADD":    true,
+				"CHECK":  true,
+				"DEL":    true,
+				"GC":     true,
+				"STATUS": true,
+			},
+			nil,
+		},
+		{
+			"CNI_NETNS_OVERRIDE",
+			&netnsOverride,
+			reqForCmdEntry{
+				"ADD":   false,
+				"CHECK": false,
+				"DEL":   false,
+			},
+			nil,
+		},
 	}
 
-	argsMissing := false
+	argsMissing := make([]string, 0)
 	for _, v := range vars {
-		*v.val = os.Getenv(v.name)
-		if v.req && *v.val == "" {
-			log.Printf("%v env variable missing", v.name)
-			argsMissing = true
+		*v.val = t.Getenv(v.name)
+		if *v.val == "" {
+			if v.reqForCmd[cmd] || v.name == "CNI_COMMAND" {
+				argsMissing = append(argsMissing, v.name)
+			}
+		} else if v.reqForCmd[cmd] && v.validateFn != nil {
+			if err := v.validateFn(*v.val); err != nil {
+				return "", nil, err
+			}
 		}
 	}
 
-	if argsMissing {
-		dieMsg("required env variables missing")
+	if len(argsMissing) > 0 {
+		joined := strings.Join(argsMissing, ",")
+		return "", nil, types.NewError(types.ErrInvalidEnvironmentVariables, fmt.Sprintf("required env variables [%s] missing", joined), "")
 	}
 
-	stdinData, err := ioutil.ReadAll(os.Stdin)
+	if cmd == "VERSION" {
+		t.Stdin = bytes.NewReader(nil)
+	}
+
+	stdinData, err := io.ReadAll(t.Stdin)
 	if err != nil {
-		dieMsg("error reading from stdin: %v", err)
+		return "", nil, types.NewError(types.ErrIOFailure, fmt.Sprintf("error reading from stdin: %v", err), "")
+	}
+
+	if cmd != "VERSION" {
+		if err := validateConfig(stdinData); err != nil {
+			return "", nil, err
+		}
 	}
 
 	cmdArgs := &CmdArgs{
-		ContainerID: contID,
-		Netns:       netns,
-		IfName:      ifName,
-		Args:        args,
-		Path:        path,
-		StdinData:   stdinData,
+		ContainerID:   contID,
+		Netns:         netns,
+		IfName:        ifName,
+		Args:          args,
+		Path:          path,
+		StdinData:     stdinData,
+		NetnsOverride: netnsOverride,
+	}
+	return cmd, cmdArgs, nil
+}
+
+func (t *dispatcher) checkVersionAndCall(cmdArgs *CmdArgs, pluginVersionInfo version.PluginInfo, toCall func(*CmdArgs) error) *types.Error {
+	configVersion, err := t.ConfVersionDecoder.Decode(cmdArgs.StdinData)
+	if err != nil {
+		return types.NewError(types.ErrDecodingFailure, err.Error(), "")
+	}
+	verErr := t.VersionReconciler.Check(configVersion, pluginVersionInfo)
+	if verErr != nil {
+		return types.NewError(types.ErrIncompatibleCNIVersion, "incompatible CNI versions", verErr.Details())
+	}
+
+	if toCall == nil {
+		return nil
+	}
+
+	if err = toCall(cmdArgs); err != nil {
+		var e *types.Error
+		if errors.As(err, &e) {
+			// don't wrap Error in Error
+			return e
+		}
+		return types.NewError(types.ErrInternal, err.Error(), "")
+	}
+
+	return nil
+}
+
+func validateConfig(jsonBytes []byte) *types.Error {
+	var conf struct {
+		Name string `json:"name"`
+	}
+	if err := json.Unmarshal(jsonBytes, &conf); err != nil {
+		return types.NewError(types.ErrDecodingFailure, fmt.Sprintf("error unmarshall network config: %v", err), "")
+	}
+	if conf.Name == "" {
+		return types.NewError(types.ErrInvalidNetworkConfig, "missing network name", "")
+	}
+	if err := utils.ValidateNetworkName(conf.Name); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (t *dispatcher) pluginMain(funcs CNIFuncs, versionInfo version.PluginInfo, about string) *types.Error {
+	cmd, cmdArgs, err := t.getCmdArgsFromEnv()
+	if err != nil {
+		// Print the about string to stderr when no command is set
+		if err.Code == types.ErrInvalidEnvironmentVariables && t.Getenv("CNI_COMMAND") == "" && about != "" {
+			_, _ = fmt.Fprintln(t.Stderr, about)
+			_, _ = fmt.Fprintf(t.Stderr, "CNI protocol versions supported: %s\n", strings.Join(versionInfo.SupportedVersions(), ", "))
+			return nil
+		}
+		return err
 	}
 
 	switch cmd {
 	case "ADD":
-		err = cmdAdd(cmdArgs)
-
-	case "DEL":
-		err = cmdDel(cmdArgs)
-
-	default:
-		dieMsg("unknown CNI_COMMAND: %v", cmd)
-	}
-
-	if err != nil {
-		if e, ok := err.(*types.Error); ok {
-			// don't wrap Error in Error
-			dieErr(e)
+		err = t.checkVersionAndCall(cmdArgs, versionInfo, funcs.Add)
+		if err != nil {
+			return err
 		}
-		dieMsg(err.Error())
+		if strings.ToUpper(cmdArgs.NetnsOverride) != "TRUE" && cmdArgs.NetnsOverride != "1" {
+			isPluginNetNS, checkErr := ns.CheckNetNS(cmdArgs.Netns)
+			if checkErr != nil {
+				return checkErr
+			} else if isPluginNetNS {
+				return types.NewError(types.ErrInvalidNetNS, "plugin's netns and netns from CNI_NETNS should not be the same", "")
+			}
+		}
+	case "CHECK":
+		configVersion, err := t.ConfVersionDecoder.Decode(cmdArgs.StdinData)
+		if err != nil {
+			return types.NewError(types.ErrDecodingFailure, err.Error(), "")
+		}
+		if gtet, err := version.GreaterThanOrEqualTo(configVersion, "0.4.0"); err != nil {
+			return types.NewError(types.ErrDecodingFailure, err.Error(), "")
+		} else if !gtet {
+			return types.NewError(types.ErrIncompatibleCNIVersion, "config version does not allow CHECK", "")
+		}
+		for _, pluginVersion := range versionInfo.SupportedVersions() {
+			gtet, err := version.GreaterThanOrEqualTo(pluginVersion, configVersion)
+			if err != nil {
+				return types.NewError(types.ErrDecodingFailure, err.Error(), "")
+			} else if gtet {
+				if err := t.checkVersionAndCall(cmdArgs, versionInfo, funcs.Check); err != nil {
+					return err
+				}
+				return nil
+			}
+		}
+		return types.NewError(types.ErrIncompatibleCNIVersion, "plugin version does not allow CHECK", "")
+	case "DEL":
+		err = t.checkVersionAndCall(cmdArgs, versionInfo, funcs.Del)
+		if err != nil {
+			return err
+		}
+		if strings.ToUpper(cmdArgs.NetnsOverride) != "TRUE" && cmdArgs.NetnsOverride != "1" {
+			isPluginNetNS, checkErr := ns.CheckNetNS(cmdArgs.Netns)
+			if checkErr != nil {
+				return checkErr
+			} else if isPluginNetNS {
+				return types.NewError(types.ErrInvalidNetNS, "plugin's netns and netns from CNI_NETNS should not be the same", "")
+			}
+		}
+	case "GC":
+		configVersion, err := t.ConfVersionDecoder.Decode(cmdArgs.StdinData)
+		if err != nil {
+			return types.NewError(types.ErrDecodingFailure, err.Error(), "")
+		}
+		if gtet, err := version.GreaterThanOrEqualTo(configVersion, "1.1.0"); err != nil {
+			return types.NewError(types.ErrDecodingFailure, err.Error(), "")
+		} else if !gtet {
+			return types.NewError(types.ErrIncompatibleCNIVersion, "config version does not allow GC", "")
+		}
+		for _, pluginVersion := range versionInfo.SupportedVersions() {
+			gtet, err := version.GreaterThanOrEqualTo(pluginVersion, configVersion)
+			if err != nil {
+				return types.NewError(types.ErrDecodingFailure, err.Error(), "")
+			} else if gtet {
+				if err := t.checkVersionAndCall(cmdArgs, versionInfo, funcs.GC); err != nil {
+					return err
+				}
+				return nil
+			}
+		}
+		return types.NewError(types.ErrIncompatibleCNIVersion, "plugin version does not allow GC", "")
+	case "STATUS":
+		configVersion, err := t.ConfVersionDecoder.Decode(cmdArgs.StdinData)
+		if err != nil {
+			return types.NewError(types.ErrDecodingFailure, err.Error(), "")
+		}
+		if gtet, err := version.GreaterThanOrEqualTo(configVersion, "1.1.0"); err != nil {
+			return types.NewError(types.ErrDecodingFailure, err.Error(), "")
+		} else if !gtet {
+			return types.NewError(types.ErrIncompatibleCNIVersion, "config version does not allow STATUS", "")
+		}
+		for _, pluginVersion := range versionInfo.SupportedVersions() {
+			gtet, err := version.GreaterThanOrEqualTo(pluginVersion, configVersion)
+			if err != nil {
+				return types.NewError(types.ErrDecodingFailure, err.Error(), "")
+			} else if gtet {
+				if err := t.checkVersionAndCall(cmdArgs, versionInfo, funcs.Status); err != nil {
+					return err
+				}
+				return nil
+			}
+		}
+		return types.NewError(types.ErrIncompatibleCNIVersion, "plugin version does not allow STATUS", "")
+	case "VERSION":
+		if err := versionInfo.Encode(t.Stdout); err != nil {
+			return types.NewError(types.ErrIOFailure, err.Error(), "")
+		}
+	default:
+		return types.NewError(types.ErrInvalidEnvironmentVariables, fmt.Sprintf("unknown CNI_COMMAND: %v", cmd), "")
+	}
+
+	return err
+}
+
+// PluginMainWithError is the core "main" for a plugin. It accepts
+// callback functions for add, check, and del CNI commands and returns an error.
+//
+// The caller must also specify what CNI spec versions the plugin supports.
+//
+// It is the responsibility of the caller to check for non-nil error return.
+//
+// For a plugin to comply with the CNI spec, it must print any error to stdout
+// as JSON and then exit with nonzero status code.
+//
+// To let this package automatically handle errors and call os.Exit(1) for you,
+// use PluginMain() instead.
+//
+// Deprecated: Use github.com/containernetworking/cni/pkg/skel.PluginMainFuncsWithError instead.
+func PluginMainWithError(cmdAdd, cmdCheck, cmdDel func(_ *CmdArgs) error, versionInfo version.PluginInfo, about string) *types.Error {
+	return PluginMainFuncsWithError(CNIFuncs{Add: cmdAdd, Check: cmdCheck, Del: cmdDel}, versionInfo, about)
+}
+
+// CNIFuncs contains a group of callback command funcs to be passed in as
+// parameters to the core "main" for a plugin.
+type CNIFuncs struct {
+	Add    func(_ *CmdArgs) error
+	Del    func(_ *CmdArgs) error
+	Check  func(_ *CmdArgs) error
+	GC     func(_ *CmdArgs) error
+	Status func(_ *CmdArgs) error
+}
+
+// PluginMainFuncsWithError is the core "main" for a plugin. It accepts
+// callback functions defined within CNIFuncs and returns an error.
+//
+// The caller must also specify what CNI spec versions the plugin supports.
+//
+// It is the responsibility of the caller to check for non-nil error return.
+//
+// For a plugin to comply with the CNI spec, it must print any error to stdout
+// as JSON and then exit with nonzero status code.
+//
+// To let this package automatically handle errors and call os.Exit(1) for you,
+// use PluginMainFuncs() instead.
+func PluginMainFuncsWithError(funcs CNIFuncs, versionInfo version.PluginInfo, about string) *types.Error {
+	return (&dispatcher{
+		Getenv: os.Getenv,
+		Stdin:  os.Stdin,
+		Stdout: os.Stdout,
+		Stderr: os.Stderr,
+	}).pluginMain(funcs, versionInfo, about)
+}
+
+// PluginMainFuncs is the core "main" for a plugin which includes automatic error handling.
+// This is a newer alternative func to PluginMain which abstracts CNI commands within a
+// CNIFuncs interface.
+//
+// The caller must also specify what CNI spec versions the plugin supports.
+//
+// The caller can specify an "about" string, which is printed on stderr
+// when no CNI_COMMAND is specified. The recommended output is "CNI plugin <foo> v<version>"
+//
+// When an error occurs in any func in CNIFuncs, PluginMainFuncs will print the error
+// as JSON to stdout and call os.Exit(1).
+//
+// To have more control over error handling, use PluginMainFuncsWithError() instead.
+func PluginMainFuncs(funcs CNIFuncs, versionInfo version.PluginInfo, about string) {
+	if e := PluginMainFuncsWithError(funcs, versionInfo, about); e != nil {
+		if err := e.Print(); err != nil {
+			log.Print("Error writing error JSON to stdout: ", err)
+		}
+		os.Exit(1)
 	}
 }
 
-func dieMsg(f string, args ...interface{}) {
-	e := &types.Error{
-		Code: 100,
-		Msg:  fmt.Sprintf(f, args...),
+// PluginMain is the core "main" for a plugin which includes automatic error handling.
+//
+// The caller must also specify what CNI spec versions the plugin supports.
+//
+// The caller can specify an "about" string, which is printed on stderr
+// when no CNI_COMMAND is specified. The recommended output is "CNI plugin <foo> v<version>"
+//
+// When an error occurs in either cmdAdd, cmdCheck, or cmdDel, PluginMain will print the error
+// as JSON to stdout and call os.Exit(1).
+//
+// To have more control over error handling, use PluginMainWithError() instead.
+//
+// Deprecated: Use github.com/containernetworking/cni/pkg/skel.PluginMainFuncs instead.
+func PluginMain(cmdAdd, cmdCheck, cmdDel func(_ *CmdArgs) error, versionInfo version.PluginInfo, about string) {
+	if e := PluginMainWithError(cmdAdd, cmdCheck, cmdDel, versionInfo, about); e != nil {
+		if err := e.Print(); err != nil {
+			log.Print("Error writing error JSON to stdout: ", err)
+		}
+		os.Exit(1)
 	}
-	dieErr(e)
-}
-
-func dieErr(e *types.Error) {
-	if err := e.Print(); err != nil {
-		log.Print("Error writing error JSON to stdout: ", err)
-	}
-	os.Exit(1)
 }

pkg/skel/skel_suite_test.go

@@ -15,10 +15,10 @@
 package skel
 
 import (
-	. "github.com/onsi/ginkgo"
-	. "github.com/onsi/gomega"
-
 	"testing"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
 )
 
 func TestSkel(t *testing.T) {

pkg/skel/skel_test.go

@@ -15,61 +15,719 @@
 package skel
 
 import (
-	"os"
+	"bytes"
+	"errors"
+	"fmt"
+	"strings"
 
-	. "github.com/onsi/ginkgo"
+	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
+
+	"github.com/containernetworking/cni/pkg/types"
+	"github.com/containernetworking/cni/pkg/version"
 )
 
-var _ = Describe("Skel", func() {
+type fakeCmd struct {
+	CallCount int
+	Returns   struct {
+		Error error
+	}
+	Received struct {
+		CmdArgs *CmdArgs
+	}
+}
+
+func (c *fakeCmd) Func(args *CmdArgs) error {
+	c.CallCount++
+	c.Received.CmdArgs = args
+	return c.Returns.Error
+}
+
+var _ = Describe("dispatching to the correct callback", func() {
 	var (
-		fNoop = func(_ *CmdArgs) error { return nil }
-		// fErr    = func(_ *CmdArgs) error { return errors.New("dummy") }
-		envVars = []struct {
-			name string
-			val  string
-		}{
-			{"CNI_CONTAINERID", "dummy"},
-			{"CNI_NETNS", "dummy"},
-			{"CNI_IFNAME", "dummy"},
-			{"CNI_ARGS", "dummy"},
-			{"CNI_PATH", "dummy"},
-		}
+		environment                     map[string]string
+		stdinData                       string
+		stdout, stderr                  *bytes.Buffer
+		cmdAdd, cmdCheck, cmdDel, cmdGC *fakeCmd
+		dispatch                        *dispatcher
+		expectedCmdArgs                 *CmdArgs
+		versionInfo                     version.PluginInfo
+		funcs                           CNIFuncs
 	)
 
-	It("Must be possible to set the env vars", func() {
-		for _, v := range envVars {
-			err := os.Setenv(v.name, v.val)
-			Expect(err).NotTo(HaveOccurred())
+	BeforeEach(func() {
+		environment = map[string]string{
+			"CNI_COMMAND":     "ADD",
+			"CNI_CONTAINERID": "some-container-id",
+			"CNI_NETNS":       "/some/netns/path",
+			"CNI_IFNAME":      "eth0",
+			"CNI_ARGS":        "some;extra;args",
+			"CNI_PATH":        "/some/cni/path",
+		}
+
+		stdinData = `{ "name":"skel-test", "some": "config", "cniVersion": "9.8.7" }`
+		stdout = &bytes.Buffer{}
+		stderr = &bytes.Buffer{}
+		versionInfo = version.PluginSupports("9.8.7", "10.0.0")
+		dispatch = &dispatcher{
+			Getenv: func(key string) string { return environment[key] },
+			Stdin:  strings.NewReader(stdinData),
+			Stdout: stdout,
+			Stderr: stderr,
+		}
+		cmdAdd = &fakeCmd{}
+		cmdCheck = &fakeCmd{}
+		cmdDel = &fakeCmd{}
+		cmdGC = &fakeCmd{}
+		funcs = CNIFuncs{
+			Add:   cmdAdd.Func,
+			Del:   cmdDel.Func,
+			Check: cmdCheck.Func,
+			GC:    cmdGC.Func,
+		}
+
+		expectedCmdArgs = &CmdArgs{
+			ContainerID: "some-container-id",
+			Netns:       "/some/netns/path",
+			IfName:      "eth0",
+			Args:        "some;extra;args",
+			Path:        "/some/cni/path",
+			StdinData:   []byte(stdinData),
 		}
 	})
 
-	Context("When dummy environment variables are passed", func() {
+	envVarChecker := func(envVar string, isRequired bool) {
+		delete(environment, envVar)
 
-		It("should not fail with ADD and noop callback", func() {
-			err := os.Setenv("CNI_COMMAND", "ADD")
+		err := dispatch.pluginMain(funcs, versionInfo, "")
+		if isRequired {
+			Expect(err).To(Equal(&types.Error{
+				Code: types.ErrInvalidEnvironmentVariables,
+				Msg:  "required env variables [" + envVar + "] missing",
+			}))
+		} else {
 			Expect(err).NotTo(HaveOccurred())
-			PluginMain(fNoop, nil)
+		}
+	}
+
+	Context("when the CNI_COMMAND is ADD", func() {
+		expectedCmdArgs = &CmdArgs{
+			ContainerID: "some-container-id",
+			Netns:       "/some/netns/path",
+			IfName:      "eth0",
+			Args:        "some;extra;args",
+			Path:        "/some/cni/path",
+			StdinData:   []byte(stdinData),
+		}
+
+		It("extracts env vars and stdin data and calls cmdAdd", func() {
+			err := dispatch.pluginMain(funcs, versionInfo, "")
+
+			Expect(err).NotTo(HaveOccurred())
+			Expect(cmdAdd.CallCount).To(Equal(1))
+			Expect(cmdCheck.CallCount).To(Equal(0))
+			Expect(cmdDel.CallCount).To(Equal(0))
+			Expect(cmdAdd.Received.CmdArgs).To(Equal(expectedCmdArgs))
 		})
 
-		// TODO: figure out howto mock printing and os.Exit()
-		// It("should fail with ADD and error callback", func() {
-		// 	err := os.Setenv("CNI_COMMAND", "ADD")
-		// 	Expect(err).NotTo(HaveOccurred())
-		// 	PluginMain(fErr, nil)
-		// })
-
-		It("should not fail with DEL and noop callback", func() {
-			err := os.Setenv("CNI_COMMAND", "DEL")
-			Expect(err).NotTo(HaveOccurred())
-			PluginMain(nil, fNoop)
+		It("returns an error when containerID has invalid characters", func() {
+			environment["CNI_CONTAINERID"] = "some-%%container-id"
+			err := dispatch.pluginMain(funcs, versionInfo, "")
+			Expect(err).To(HaveOccurred())
+			Expect(err).To(Equal(&types.Error{
+				Code:    types.ErrInvalidEnvironmentVariables,
+				Msg:     "invalid characters in containerID",
+				Details: "some-%%container-id",
+			}))
 		})
 
-		// TODO: figure out howto mock printing and os.Exit()
-		// It("should fail with DEL and error callback", func() {
-		// 	err := os.Setenv("CNI_COMMAND", "DEL")
-		// 	Expect(err).NotTo(HaveOccurred())
-		// 	PluginMain(fErr, nil)
-		// })
+		Context("return errors when interface name is invalid", func() {
+			It("interface name is too long", func() {
+				environment["CNI_IFNAME"] = "1234567890123456"
+
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+				Expect(err).To(HaveOccurred())
+				Expect(err).To(Equal(&types.Error{
+					Code:    types.ErrInvalidEnvironmentVariables,
+					Msg:     "interface name is too long",
+					Details: "interface name should be less than 16 characters",
+				}))
+			})
+
+			It("interface name is .", func() {
+				environment["CNI_IFNAME"] = "."
+
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+				Expect(err).To(HaveOccurred())
+				Expect(err).To(Equal(&types.Error{
+					Code:    types.ErrInvalidEnvironmentVariables,
+					Msg:     "interface name is . or ..",
+					Details: "",
+				}))
+			})
+
+			It("interface name is ..", func() {
+				environment["CNI_IFNAME"] = ".."
+
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+				Expect(err).To(HaveOccurred())
+				Expect(err).To(Equal(&types.Error{
+					Code:    types.ErrInvalidEnvironmentVariables,
+					Msg:     "interface name is . or ..",
+					Details: "",
+				}))
+			})
+
+			It("interface name contains invalid characters /", func() {
+				environment["CNI_IFNAME"] = "test/test"
+
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+				Expect(err).To(HaveOccurred())
+				Expect(err).To(Equal(&types.Error{
+					Code:    types.ErrInvalidEnvironmentVariables,
+					Msg:     "interface name contains / or : or whitespace characters",
+					Details: "",
+				}))
+			})
+
+			It("interface name contains invalid characters :", func() {
+				environment["CNI_IFNAME"] = "test:test"
+
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+				Expect(err).To(HaveOccurred())
+				Expect(err).To(Equal(&types.Error{
+					Code:    types.ErrInvalidEnvironmentVariables,
+					Msg:     "interface name contains / or : or whitespace characters",
+					Details: "",
+				}))
+			})
+
+			It("interface name contains invalid characters whitespace", func() {
+				environment["CNI_IFNAME"] = "test test"
+
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+				Expect(err).To(HaveOccurred())
+				Expect(err).To(Equal(&types.Error{
+					Code:    types.ErrInvalidEnvironmentVariables,
+					Msg:     "interface name contains / or : or whitespace characters",
+					Details: "",
+				}))
+			})
+		})
+
+		It("does not call cmdCheck or cmdDel", func() {
+			err := dispatch.pluginMain(funcs, versionInfo, "")
+
+			Expect(err).NotTo(HaveOccurred())
+			Expect(cmdCheck.CallCount).To(Equal(0))
+			Expect(cmdDel.CallCount).To(Equal(0))
+		})
+
+		DescribeTable("required / optional env vars", envVarChecker,
+			Entry("command", "CNI_COMMAND", true),
+			Entry("container id", "CNI_CONTAINERID", true),
+			Entry("net ns", "CNI_NETNS", true),
+			Entry("if name", "CNI_IFNAME", true),
+			Entry("args", "CNI_ARGS", false),
+			Entry("path", "CNI_PATH", true),
+		)
+
+		Context("when multiple required env vars are missing", func() {
+			BeforeEach(func() {
+				delete(environment, "CNI_NETNS")
+				delete(environment, "CNI_IFNAME")
+				delete(environment, "CNI_PATH")
+			})
+
+			It("reports that all of them are missing, not just the first", func() {
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+				Expect(err).To(HaveOccurred())
+
+				Expect(err).To(Equal(&types.Error{
+					Code: types.ErrInvalidEnvironmentVariables,
+					Msg:  "required env variables [CNI_NETNS,CNI_IFNAME,CNI_PATH] missing",
+				}))
+			})
+		})
+
+		Context("when the stdin data is missing the required cniVersion config", func() {
+			BeforeEach(func() {
+				dispatch.Stdin = strings.NewReader(`{ "name": "skel-test", "some": "config" }`)
+			})
+
+			Context("when the plugin supports version 0.1.0", func() {
+				BeforeEach(func() {
+					versionInfo = version.PluginSupports("0.1.0")
+					expectedCmdArgs.StdinData = []byte(`{ "name": "skel-test", "some": "config" }`)
+				})
+
+				It("infers the config is 0.1.0 and calls the cmdAdd callback", func() {
+					err := dispatch.pluginMain(funcs, versionInfo, "")
+					Expect(err).NotTo(HaveOccurred())
+
+					Expect(cmdAdd.CallCount).To(Equal(1))
+					Expect(cmdAdd.Received.CmdArgs).To(Equal(expectedCmdArgs))
+				})
+			})
+
+			Context("when the plugin does not support 0.1.0", func() {
+				BeforeEach(func() {
+					versionInfo = version.PluginSupports("4.3.2")
+				})
+
+				It("immediately returns a useful error", func() {
+					err := dispatch.pluginMain(funcs, versionInfo, "")
+					Expect(err.Code).To(Equal(types.ErrIncompatibleCNIVersion)) // see https://github.com/containernetworking/cni/blob/main/SPEC.md#well-known-error-codes
+					Expect(err.Msg).To(Equal("incompatible CNI versions"))
+					Expect(err.Details).To(Equal(`config is "0.1.0", plugin supports ["4.3.2"]`))
+				})
+
+				It("does not call either callback", func() {
+					err := dispatch.pluginMain(funcs, versionInfo, "")
+					Expect(err).To(HaveOccurred())
+					Expect(cmdAdd.CallCount).To(Equal(0))
+					Expect(cmdCheck.CallCount).To(Equal(0))
+					Expect(cmdDel.CallCount).To(Equal(0))
+				})
+			})
+		})
+	})
+
+	Context("when the CNI_COMMAND is CHECK", func() {
+		BeforeEach(func() {
+			environment["CNI_COMMAND"] = "CHECK"
+		})
+
+		It("extracts env vars and stdin data and calls cmdCheck", func() {
+			err := dispatch.pluginMain(funcs, versionInfo, "")
+
+			Expect(err).NotTo(HaveOccurred())
+			Expect(cmdAdd.CallCount).To(Equal(0))
+			Expect(cmdCheck.CallCount).To(Equal(1))
+			Expect(cmdDel.CallCount).To(Equal(0))
+			Expect(cmdCheck.Received.CmdArgs).To(Equal(expectedCmdArgs))
+		})
+
+		It("does not call cmdAdd or cmdDel", func() {
+			err := dispatch.pluginMain(funcs, versionInfo, "")
+
+			Expect(err).NotTo(HaveOccurred())
+			Expect(cmdAdd.CallCount).To(Equal(0))
+			Expect(cmdDel.CallCount).To(Equal(0))
+		})
+
+		DescribeTable("required / optional env vars", envVarChecker,
+			Entry("command", "CNI_COMMAND", true),
+			Entry("container id", "CNI_CONTAINERID", true),
+			Entry("net ns", "CNI_NETNS", true),
+			Entry("if name", "CNI_IFNAME", true),
+			Entry("args", "CNI_ARGS", false),
+			Entry("path", "CNI_PATH", true),
+		)
+
+		Context("when multiple required env vars are missing", func() {
+			BeforeEach(func() {
+				delete(environment, "CNI_NETNS")
+				delete(environment, "CNI_IFNAME")
+				delete(environment, "CNI_PATH")
+			})
+
+			It("reports that all of them are missing, not just the first", func() {
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+				Expect(err).To(HaveOccurred())
+
+				Expect(err).To(Equal(&types.Error{
+					Code: types.ErrInvalidEnvironmentVariables,
+					Msg:  "required env variables [CNI_NETNS,CNI_IFNAME,CNI_PATH] missing",
+				}))
+			})
+		})
+
+		Context("when cniVersion is less than 0.4.0", func() {
+			It("immediately returns a useful error", func() {
+				dispatch.Stdin = strings.NewReader(`{ "name": "skel-test", "cniVersion": "0.3.0", "some": "config" }`)
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+				Expect(err.Code).To(Equal(types.ErrIncompatibleCNIVersion)) // see https://github.com/containernetworking/cni/blob/main/SPEC.md#well-known-error-codes
+				Expect(err.Msg).To(Equal("config version does not allow CHECK"))
+				Expect(cmdAdd.CallCount).To(Equal(0))
+				Expect(cmdCheck.CallCount).To(Equal(0))
+				Expect(cmdDel.CallCount).To(Equal(0))
+			})
+		})
+
+		Context("when plugin does not support 0.4.0", func() {
+			It("immediately returns a useful error", func() {
+				dispatch.Stdin = strings.NewReader(`{ "name": "skel-test", "cniVersion": "0.4.0", "some": "config" }`)
+				versionInfo = version.PluginSupports("0.1.0", "0.2.0", "0.3.0")
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+				Expect(err.Code).To(Equal(types.ErrIncompatibleCNIVersion)) // see https://github.com/containernetworking/cni/blob/main/SPEC.md#well-known-error-codes
+				Expect(err.Msg).To(Equal("plugin version does not allow CHECK"))
+				Expect(cmdAdd.CallCount).To(Equal(0))
+				Expect(cmdCheck.CallCount).To(Equal(0))
+				Expect(cmdDel.CallCount).To(Equal(0))
+			})
+		})
+
+		Context("when the config has a bad version", func() {
+			It("immediately returns a useful error", func() {
+				dispatch.Stdin = strings.NewReader(`{ "cniVersion": "adsfsadf", "some": "config", "name": "test" }`)
+				versionInfo = version.PluginSupports("0.1.0", "0.2.0", "0.3.0")
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+				Expect(err.Code).To(Equal(types.ErrDecodingFailure))
+				Expect(cmdAdd.CallCount).To(Equal(0))
+				Expect(cmdCheck.CallCount).To(Equal(0))
+				Expect(cmdDel.CallCount).To(Equal(0))
+			})
+		})
+
+		Context("when the config has a bad name", func() {
+			It("immediately returns invalid network config", func() {
+				dispatch.Stdin = strings.NewReader(`{ "cniVersion": "0.4.0", "some": "config", "name": "te%%st" }`)
+				versionInfo = version.PluginSupports("0.1.0", "0.2.0", "0.3.0", "0.4.0")
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+				Expect(err.Code).To(Equal(types.ErrInvalidNetworkConfig))
+				Expect(cmdAdd.CallCount).To(Equal(0))
+				Expect(cmdCheck.CallCount).To(Equal(0))
+				Expect(cmdDel.CallCount).To(Equal(0))
+			})
+		})
+
+		Context("when the plugin has a bad version", func() {
+			It("immediately returns a useful error", func() {
+				dispatch.Stdin = strings.NewReader(`{ "cniVersion": "0.4.0", "some": "config", "name": "test" }`)
+				versionInfo = version.PluginSupports("0.1.0", "0.2.0", "adsfasdf")
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+				Expect(err.Code).To(Equal(types.ErrDecodingFailure))
+				Expect(cmdAdd.CallCount).To(Equal(0))
+				Expect(cmdCheck.CallCount).To(Equal(0))
+				Expect(cmdDel.CallCount).To(Equal(0))
+			})
+		})
+	})
+
+	Context("when the CNI_COMMAND is GC", func() {
+		BeforeEach(func() {
+			environment["CNI_COMMAND"] = "GC"
+			delete(environment, "CNI_NETNS")
+			delete(environment, "CNI_IFNAME")
+			delete(environment, "CNI_CONTAINERID")
+			delete(environment, "CNI_ARGS")
+
+			expectedCmdArgs = &CmdArgs{
+				Path:      "/some/cni/path",
+				StdinData: []byte(stdinData),
+			}
+
+			dispatch = &dispatcher{
+				Getenv: func(key string) string {
+					return environment[key]
+				},
+				Stdin:  strings.NewReader(stdinData),
+				Stdout: stdout,
+				Stderr: stderr,
+			}
+		})
+
+		It("extracts env vars and stdin data and calls cmdGC", func() {
+			err := dispatch.pluginMain(funcs, versionInfo, "")
+
+			Expect(err).NotTo(HaveOccurred())
+			Expect(cmdAdd.CallCount).To(Equal(0))
+			Expect(cmdCheck.CallCount).To(Equal(0))
+			Expect(cmdDel.CallCount).To(Equal(0))
+			Expect(cmdGC.CallCount).To(Equal(1))
+			Expect(cmdGC.Received.CmdArgs).To(Equal(expectedCmdArgs))
+		})
+
+		It("does not call cmdAdd or cmdDel", func() {
+			err := dispatch.pluginMain(funcs, versionInfo, "")
+
+			Expect(err).NotTo(HaveOccurred())
+			Expect(cmdAdd.CallCount).To(Equal(0))
+			Expect(cmdDel.CallCount).To(Equal(0))
+		})
+
+		DescribeTable("required / optional env vars", envVarChecker,
+			Entry("command", "CNI_COMMAND", true),
+			Entry("container id", "CNI_CONTAINERID", false),
+			Entry("net ns", "CNI_NETNS", false),
+			Entry("if name", "CNI_IFNAME", false),
+			Entry("args", "CNI_ARGS", false),
+			Entry("path", "CNI_PATH", true),
+		)
+
+		Context("when multiple required env vars are missing", func() {
+			BeforeEach(func() {
+				delete(environment, "CNI_PATH")
+			})
+
+			It("reports that all of them are missing, not just the first", func() {
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+				Expect(err).To(HaveOccurred())
+
+				Expect(err).To(Equal(&types.Error{
+					Code: types.ErrInvalidEnvironmentVariables,
+					Msg:  "required env variables [CNI_PATH] missing",
+				}))
+			})
+		})
+
+		Context("when cniVersion is less than 1.1.0", func() {
+			It("immediately returns a useful error", func() {
+				dispatch.Stdin = strings.NewReader(`{ "name": "skel-test", "cniVersion": "0.3.0", "some": "config" }`)
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+				Expect(err.Code).To(Equal(types.ErrIncompatibleCNIVersion)) // see https://github.com/containernetworking/cni/blob/main/SPEC.md#well-known-error-codes
+				Expect(err.Msg).To(Equal("config version does not allow GC"))
+				Expect(cmdGC.CallCount).To(Equal(0))
+			})
+		})
+
+		Context("when plugin does not support 1.1.0", func() {
+			It("immediately returns a useful error", func() {
+				dispatch.Stdin = strings.NewReader(`{ "name": "skel-test", "cniVersion": "1.1.0", "some": "config" }`)
+				versionInfo = version.PluginSupports("0.1.0", "0.2.0", "0.3.0")
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+				Expect(err.Code).To(Equal(types.ErrIncompatibleCNIVersion)) // see https://github.com/containernetworking/cni/blob/main/SPEC.md#well-known-error-codes
+				Expect(err.Msg).To(Equal("plugin version does not allow GC"))
+				Expect(cmdGC.CallCount).To(Equal(0))
+			})
+		})
+
+		Context("when the config has a bad version", func() {
+			It("immediately returns a useful error", func() {
+				dispatch.Stdin = strings.NewReader(`{ "cniVersion": "adsfsadf", "some": "config", "name": "test" }`)
+				versionInfo = version.PluginSupports("1.1.0")
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+				Expect(err.Code).To(Equal(types.ErrDecodingFailure))
+				Expect(cmdGC.CallCount).To(Equal(0))
+			})
+		})
+
+		Context("when the config has a bad name", func() {
+			It("immediately returns invalid network config", func() {
+				dispatch.Stdin = strings.NewReader(`{ "cniVersion": "0.4.0", "some": "config", "name": "te%%st" }`)
+				versionInfo = version.PluginSupports("1.1.0")
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+				Expect(err.Code).To(Equal(types.ErrInvalidNetworkConfig))
+				Expect(cmdGC.CallCount).To(Equal(0))
+			})
+		})
+
+		Context("when the plugin has a bad version", func() {
+			It("immediately returns a useful error", func() {
+				dispatch.Stdin = strings.NewReader(`{ "cniVersion": "1.1.0", "some": "config", "name": "test" }`)
+				versionInfo = version.PluginSupports("0.1.0", "0.2.0", "adsfasdf")
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+				Expect(err.Code).To(Equal(types.ErrDecodingFailure))
+				Expect(cmdGC.CallCount).To(Equal(0))
+			})
+		})
+	})
+
+	Context("when the CNI_COMMAND is DEL", func() {
+		BeforeEach(func() {
+			environment["CNI_COMMAND"] = "DEL"
+		})
+
+		It("calls cmdDel with the env vars and stdin data", func() {
+			err := dispatch.pluginMain(funcs, versionInfo, "")
+
+			Expect(err).NotTo(HaveOccurred())
+			Expect(cmdDel.CallCount).To(Equal(1))
+			Expect(cmdDel.Received.CmdArgs).To(Equal(expectedCmdArgs))
+		})
+
+		It("does not call cmdAdd", func() {
+			err := dispatch.pluginMain(funcs, versionInfo, "")
+
+			Expect(err).NotTo(HaveOccurred())
+			Expect(cmdAdd.CallCount).To(Equal(0))
+		})
+
+		DescribeTable("required / optional env vars", envVarChecker,
+			Entry("command", "CNI_COMMAND", true),
+			Entry("container id", "CNI_CONTAINERID", true),
+			Entry("net ns", "CNI_NETNS", false),
+			Entry("if name", "CNI_IFNAME", true),
+			Entry("args", "CNI_ARGS", false),
+			Entry("path", "CNI_PATH", true),
+		)
+	})
+
+	Context("when the CNI_COMMAND is VERSION", func() {
+		BeforeEach(func() {
+			environment["CNI_COMMAND"] = "VERSION"
+		})
+
+		It("prints the version to stdout", func() {
+			err := dispatch.pluginMain(funcs, versionInfo, "")
+
+			Expect(err).NotTo(HaveOccurred())
+			Expect(stdout).To(MatchJSON(fmt.Sprintf(`{
+				"cniVersion": "%s",
+				"supportedVersions": ["9.8.7", "10.0.0"]
+			}`, version.Current())))
+		})
+
+		It("does not call cmdAdd or cmdDel", func() {
+			err := dispatch.pluginMain(funcs, versionInfo, "")
+
+			Expect(err).NotTo(HaveOccurred())
+			Expect(cmdAdd.CallCount).To(Equal(0))
+			Expect(cmdDel.CallCount).To(Equal(0))
+		})
+
+		DescribeTable("VERSION does not need the usual env vars", envVarChecker,
+			Entry("command", "CNI_COMMAND", true),
+			Entry("container id", "CNI_CONTAINERID", false),
+			Entry("net ns", "CNI_NETNS", false),
+			Entry("if name", "CNI_IFNAME", false),
+			Entry("args", "CNI_ARGS", false),
+			Entry("path", "CNI_PATH", false),
+		)
+
+		It("does not read from Stdin", func() {
+			r := &BadReader{}
+			dispatch.Stdin = r
+
+			err := dispatch.pluginMain(funcs, versionInfo, "")
+
+			Expect(err).NotTo(HaveOccurred())
+			Expect(r.ReadCount).To(Equal(0))
+			Expect(stdout).To(MatchJSON(fmt.Sprintf(`{
+				"cniVersion": "%s",
+				"supportedVersions": ["9.8.7", "10.0.0"]
+			}`, version.Current())))
+		})
+	})
+
+	Context("when the CNI_COMMAND is unrecognized", func() {
+		BeforeEach(func() {
+			environment["CNI_COMMAND"] = "NOPE"
+		})
+
+		It("does not call any cmd callback", func() {
+			err := dispatch.pluginMain(funcs, versionInfo, "")
+			Expect(err).To(HaveOccurred())
+			Expect(cmdAdd.CallCount).To(Equal(0))
+			Expect(cmdDel.CallCount).To(Equal(0))
+		})
+
+		It("returns an error", func() {
+			err := dispatch.pluginMain(funcs, versionInfo, "")
+
+			Expect(err).To(Equal(&types.Error{
+				Code: types.ErrInvalidEnvironmentVariables,
+				Msg:  "unknown CNI_COMMAND: NOPE",
+			}))
+		})
+
+		It("prints the about string when the command is blank", func() {
+			environment["CNI_COMMAND"] = ""
+			err := dispatch.pluginMain(funcs, versionInfo, "test framework v42")
+			Expect(err).NotTo(HaveOccurred())
+			Expect(stderr.String()).To(ContainSubstring("test framework v42"))
+		})
+	})
+
+	Context("when the CNI_COMMAND is missing", func() {
+		It("prints the about string to stderr", func() {
+			environment = map[string]string{}
+			err := dispatch.pluginMain(funcs, versionInfo, "AWESOME PLUGIN")
+			Expect(err).NotTo(HaveOccurred())
+
+			Expect(cmdAdd.CallCount).To(Equal(0))
+			Expect(cmdDel.CallCount).To(Equal(0))
+			log := stderr.String()
+			Expect(log).To(Equal("AWESOME PLUGIN\nCNI protocol versions supported: 9.8.7, 10.0.0\n"))
+		})
+
+		It("fails if there is no about string", func() {
+			environment = map[string]string{}
+			err := dispatch.pluginMain(funcs, versionInfo, "")
+			Expect(err).To(HaveOccurred())
+
+			Expect(cmdAdd.CallCount).To(Equal(0))
+			Expect(cmdDel.CallCount).To(Equal(0))
+			Expect(err).To(Equal(&types.Error{
+				Code: types.ErrInvalidEnvironmentVariables,
+				Msg:  "required env variables [CNI_COMMAND] missing",
+			}))
+		})
+	})
+
+	Context("when stdin cannot be read", func() {
+		BeforeEach(func() {
+			dispatch.Stdin = &BadReader{}
+		})
+
+		It("does not call any cmd callback", func() {
+			err := dispatch.pluginMain(funcs, versionInfo, "")
+			Expect(err).To(HaveOccurred())
+			Expect(cmdAdd.CallCount).To(Equal(0))
+			Expect(cmdDel.CallCount).To(Equal(0))
+		})
+
+		It("wraps and returns the error", func() {
+			err := dispatch.pluginMain(funcs, versionInfo, "")
+
+			Expect(err).To(Equal(&types.Error{
+				Code: types.ErrIOFailure,
+				Msg:  "error reading from stdin: banana",
+			}))
+		})
+	})
+
+	Context("when the callback returns an error", func() {
+		Context("when it is a typed Error", func() {
+			BeforeEach(func() {
+				cmdAdd.Returns.Error = &types.Error{
+					Code: 1234,
+					Msg:  "insufficient something",
+				}
+			})
+
+			It("returns the error as-is", func() {
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+
+				Expect(err).To(Equal(&types.Error{
+					Code: 1234,
+					Msg:  "insufficient something",
+				}))
+			})
+		})
+
+		Context("when it is an unknown error", func() {
+			BeforeEach(func() {
+				cmdAdd.Returns.Error = errors.New("potato")
+			})
+
+			It("wraps and returns the error", func() {
+				err := dispatch.pluginMain(funcs, versionInfo, "")
+
+				Expect(err).To(Equal(&types.Error{
+					Code: types.ErrInternal,
+					Msg:  "potato",
+				}))
+			})
+		})
 	})
 })
+
+// BadReader is an io.Reader which always errors
+type BadReader struct {
+	Error     error
+	ReadCount int
+}
+
+func (r *BadReader) Read(buffer []byte) (int, error) {
+	r.ReadCount++
+	if r.Error != nil {
+		return 0, r.Error
+	}
+	return 0, errors.New("banana")
+}
+
+func (r *BadReader) Close() error {
+	return nil
+}

pkg/testutils/cmd.go

@@ -1,77 +0,0 @@
-// Copyright 2016 CNI authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package testutils
-
-import (
-	"encoding/json"
-	"io/ioutil"
-	"os"
-
-	"github.com/containernetworking/cni/pkg/types"
-)
-
-func envCleanup() {
-	os.Unsetenv("CNI_COMMAND")
-	os.Unsetenv("CNI_PATH")
-	os.Unsetenv("CNI_NETNS")
-	os.Unsetenv("CNI_IFNAME")
-}
-
-func CmdAddWithResult(cniNetns, cniIfname string, f func() error) (*types.Result, error) {
-	os.Setenv("CNI_COMMAND", "ADD")
-	os.Setenv("CNI_PATH", os.Getenv("PATH"))
-	os.Setenv("CNI_NETNS", cniNetns)
-	os.Setenv("CNI_IFNAME", cniIfname)
-	defer envCleanup()
-
-	// Redirect stdout to capture plugin result
-	oldStdout := os.Stdout
-	r, w, err := os.Pipe()
-	if err != nil {
-		return nil, err
-	}
-
-	os.Stdout = w
-	err = f()
-	w.Close()
-	if err != nil {
-		return nil, err
-	}
-
-	// parse the result
-	out, err := ioutil.ReadAll(r)
-	os.Stdout = oldStdout
-	if err != nil {
-		return nil, err
-	}
-
-	result := types.Result{}
-	err = json.Unmarshal(out, &result)
-	if err != nil {
-		return nil, err
-	}
-
-	return &result, nil
-}
-
-func CmdDelWithResult(cniNetns, cniIfname string, f func() error) error {
-	os.Setenv("CNI_COMMAND", "DEL")
-	os.Setenv("CNI_PATH", os.Getenv("PATH"))
-	os.Setenv("CNI_NETNS", cniNetns)
-	os.Setenv("CNI_IFNAME", cniIfname)
-	defer envCleanup()
-
-	return f()
-}

pkg/types/020/types.go

@@ -0,0 +1,189 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package types020
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net"
+	"os"
+
+	"github.com/containernetworking/cni/pkg/types"
+	convert "github.com/containernetworking/cni/pkg/types/internal"
+)
+
+const ImplementedSpecVersion string = "0.2.0"
+
+var supportedVersions = []string{"", "0.1.0", ImplementedSpecVersion}
+
+// Register converters for all versions less than the implemented spec version
+func init() {
+	convert.RegisterConverter("0.1.0", []string{ImplementedSpecVersion}, convertFrom010)
+	convert.RegisterConverter(ImplementedSpecVersion, []string{"0.1.0"}, convertTo010)
+
+	// Creator
+	convert.RegisterCreator(supportedVersions, NewResult)
+}
+
+// Compatibility types for CNI version 0.1.0 and 0.2.0
+
+// NewResult creates a new Result object from JSON data. The JSON data
+// must be compatible with the CNI versions implemented by this type.
+func NewResult(data []byte) (types.Result, error) {
+	result := &Result{}
+	if err := json.Unmarshal(data, result); err != nil {
+		return nil, err
+	}
+	for _, v := range supportedVersions {
+		if result.CNIVersion == v {
+			if result.CNIVersion == "" {
+				result.CNIVersion = "0.1.0"
+			}
+			return result, nil
+		}
+	}
+	return nil, fmt.Errorf("result type supports %v but unmarshalled CNIVersion is %q",
+		supportedVersions, result.CNIVersion)
+}
+
+// GetResult converts the given Result object to the ImplementedSpecVersion
+// and returns the concrete type or an error
+func GetResult(r types.Result) (*Result, error) {
+	result020, err := convert.Convert(r, ImplementedSpecVersion)
+	if err != nil {
+		return nil, err
+	}
+	result, ok := result020.(*Result)
+	if !ok {
+		return nil, fmt.Errorf("failed to convert result")
+	}
+	return result, nil
+}
+
+func convertFrom010(from types.Result, toVersion string) (types.Result, error) {
+	if toVersion != "0.2.0" {
+		panic("only converts to version 0.2.0")
+	}
+	fromResult := from.(*Result)
+	return &Result{
+		CNIVersion: ImplementedSpecVersion,
+		IP4:        fromResult.IP4.Copy(),
+		IP6:        fromResult.IP6.Copy(),
+		DNS:        *fromResult.DNS.Copy(),
+	}, nil
+}
+
+func convertTo010(from types.Result, toVersion string) (types.Result, error) {
+	if toVersion != "0.1.0" {
+		panic("only converts to version 0.1.0")
+	}
+	fromResult := from.(*Result)
+	return &Result{
+		CNIVersion: "0.1.0",
+		IP4:        fromResult.IP4.Copy(),
+		IP6:        fromResult.IP6.Copy(),
+		DNS:        *fromResult.DNS.Copy(),
+	}, nil
+}
+
+// Result is what gets returned from the plugin (via stdout) to the caller
+type Result struct {
+	CNIVersion string    `json:"cniVersion,omitempty"`
+	IP4        *IPConfig `json:"ip4,omitempty"`
+	IP6        *IPConfig `json:"ip6,omitempty"`
+	DNS        types.DNS `json:"dns,omitempty"`
+}
+
+func (r *Result) Version() string {
+	return r.CNIVersion
+}
+
+func (r *Result) GetAsVersion(version string) (types.Result, error) {
+	// If the creator of the result did not set the CNIVersion, assume it
+	// should be the highest spec version implemented by this Result
+	if r.CNIVersion == "" {
+		r.CNIVersion = ImplementedSpecVersion
+	}
+	return convert.Convert(r, version)
+}
+
+func (r *Result) Print() error {
+	return r.PrintTo(os.Stdout)
+}
+
+func (r *Result) PrintTo(writer io.Writer) error {
+	data, err := json.MarshalIndent(r, "", "    ")
+	if err != nil {
+		return err
+	}
+	_, err = writer.Write(data)
+	return err
+}
+
+// IPConfig contains values necessary to configure an interface
+type IPConfig struct {
+	IP      net.IPNet
+	Gateway net.IP
+	Routes  []types.Route
+}
+
+func (i *IPConfig) Copy() *IPConfig {
+	if i == nil {
+		return nil
+	}
+
+	var routes []types.Route
+	for _, fromRoute := range i.Routes {
+		routes = append(routes, *fromRoute.Copy())
+	}
+	return &IPConfig{
+		IP:      i.IP,
+		Gateway: i.Gateway,
+		Routes:  routes,
+	}
+}
+
+// net.IPNet is not JSON (un)marshallable so this duality is needed
+// for our custom IPNet type
+
+// JSON (un)marshallable types
+type ipConfig struct {
+	IP      types.IPNet   `json:"ip"`
+	Gateway net.IP        `json:"gateway,omitempty"`
+	Routes  []types.Route `json:"routes,omitempty"`
+}
+
+func (c *IPConfig) MarshalJSON() ([]byte, error) {
+	ipc := ipConfig{
+		IP:      types.IPNet(c.IP),
+		Gateway: c.Gateway,
+		Routes:  c.Routes,
+	}
+
+	return json.Marshal(ipc)
+}
+
+func (c *IPConfig) UnmarshalJSON(data []byte) error {
+	ipc := ipConfig{}
+	if err := json.Unmarshal(data, &ipc); err != nil {
+		return err
+	}
+
+	c.IP = net.IPNet(ipc.IP)
+	c.Gateway = ipc.Gateway
+	c.Routes = ipc.Routes
+	return nil
+}

pkg/types/020/types_suite_test.go

@@ -12,16 +12,16 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package utils_test
+package types020_test
 
 import (
-	. "github.com/onsi/ginkgo"
-	. "github.com/onsi/gomega"
-
 	"testing"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
 )
 
-func TestUtils(t *testing.T) {
+func TestTypes010(t *testing.T) {
 	RegisterFailHandler(Fail)
-	RunSpecs(t, "Utils Suite")
+	RunSpecs(t, "0.1.0/0.2.0 Types Suite")
 }

pkg/types/020/types_test.go

@@ -0,0 +1,157 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package types020_test
+
+import (
+	"encoding/json"
+	"fmt"
+	"net"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	"github.com/containernetworking/cni/pkg/types"
+	"github.com/containernetworking/cni/pkg/types/020"
+	"github.com/containernetworking/cni/pkg/types/create"
+)
+
+func testResult(resultCNIVersion, jsonCNIVersion string) (*types020.Result, string) {
+	ipv4, err := types.ParseCIDR("1.2.3.30/24")
+	Expect(err).NotTo(HaveOccurred())
+	Expect(ipv4).NotTo(BeNil())
+
+	routegwv4, routev4, err := net.ParseCIDR("15.5.6.8/24")
+	Expect(err).NotTo(HaveOccurred())
+	Expect(routev4).NotTo(BeNil())
+	Expect(routegwv4).NotTo(BeNil())
+
+	ipv6, err := types.ParseCIDR("abcd:1234:ffff::cdde/64")
+	Expect(err).NotTo(HaveOccurred())
+	Expect(ipv6).NotTo(BeNil())
+
+	routegwv6, routev6, err := net.ParseCIDR("1111:dddd::aaaa/80")
+	Expect(err).NotTo(HaveOccurred())
+	Expect(routev6).NotTo(BeNil())
+	Expect(routegwv6).NotTo(BeNil())
+
+	// Set every field of the struct to ensure source compatibility
+	res := &types020.Result{
+		CNIVersion: resultCNIVersion,
+		IP4: &types020.IPConfig{
+			IP:      *ipv4,
+			Gateway: net.ParseIP("1.2.3.1"),
+			Routes: []types.Route{
+				{Dst: *routev4, GW: routegwv4},
+			},
+		},
+		IP6: &types020.IPConfig{
+			IP:      *ipv6,
+			Gateway: net.ParseIP("abcd:1234:ffff::1"),
+			Routes: []types.Route{
+				{Dst: *routev6, GW: routegwv6},
+			},
+		},
+		DNS: types.DNS{
+			Nameservers: []string{"1.2.3.4", "1::cafe"},
+			Domain:      "acompany.com",
+			Search:      []string{"somedomain.com", "otherdomain.net"},
+			Options:     []string{"foo", "bar"},
+		},
+	}
+
+	json := fmt.Sprintf(`{
+    "cniVersion": "%s",
+    "ip4": {
+        "ip": "1.2.3.30/24",
+        "gateway": "1.2.3.1",
+        "routes": [
+            {
+                "dst": "15.5.6.0/24",
+                "gw": "15.5.6.8"
+            }
+        ]
+    },
+    "ip6": {
+        "ip": "abcd:1234:ffff::cdde/64",
+        "gateway": "abcd:1234:ffff::1",
+        "routes": [
+            {
+                "dst": "1111:dddd::/80",
+                "gw": "1111:dddd::aaaa"
+            }
+        ]
+    },
+    "dns": {
+        "nameservers": [
+            "1.2.3.4",
+            "1::cafe"
+        ],
+        "domain": "acompany.com",
+        "search": [
+            "somedomain.com",
+            "otherdomain.net"
+        ],
+        "options": [
+            "foo",
+            "bar"
+        ]
+    }
+}`, jsonCNIVersion)
+
+	return res, json
+}
+
+var _ = Describe("Ensures compatibility with the 0.1.0/0.2.0 spec", func() {
+	It("correctly encodes a 0.2.0 Result", func() {
+		res, expectedJSON := testResult(types020.ImplementedSpecVersion, types020.ImplementedSpecVersion)
+		out, err := json.Marshal(res)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(out).To(MatchJSON(expectedJSON))
+	})
+
+	It("correctly encodes a 0.1.0 Result", func() {
+		res, expectedJSON := testResult("0.1.0", "0.1.0")
+		out, err := json.Marshal(res)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(out).To(MatchJSON(expectedJSON))
+	})
+
+	It("converts a 0.2.0 result to 0.1.0", func() {
+		res, expectedJSON := testResult(types020.ImplementedSpecVersion, "0.1.0")
+		res010, err := res.GetAsVersion("0.1.0")
+		Expect(err).NotTo(HaveOccurred())
+		out, err := json.Marshal(res010)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(out).To(MatchJSON(expectedJSON))
+	})
+
+	It("converts a 0.1.0 result to 0.2.0", func() {
+		res, expectedJSON := testResult("0.1.0", types020.ImplementedSpecVersion)
+		res020, err := res.GetAsVersion(types020.ImplementedSpecVersion)
+		Expect(err).NotTo(HaveOccurred())
+		out, err := json.Marshal(res020)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(out).To(MatchJSON(expectedJSON))
+	})
+
+	It("creates a 0.1.0 result passing CNIVersion ''", func() {
+		_, expectedJSON := testResult("", "")
+		resT, err := create.Create("", []byte(expectedJSON))
+		Expect(err).NotTo(HaveOccurred())
+		res010, ok := resT.(*types020.Result)
+		Expect(ok).To(BeTrue())
+		Expect(res010.CNIVersion).To(Equal("0.1.0"))
+	})
+})

pkg/types/040/types.go

@@ -0,0 +1,306 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package types040
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net"
+	"os"
+
+	"github.com/containernetworking/cni/pkg/types"
+	types020 "github.com/containernetworking/cni/pkg/types/020"
+	convert "github.com/containernetworking/cni/pkg/types/internal"
+)
+
+const ImplementedSpecVersion string = "0.4.0"
+
+var supportedVersions = []string{"0.3.0", "0.3.1", ImplementedSpecVersion}
+
+// Register converters for all versions less than the implemented spec version
+func init() {
+	// Up-converters
+	convert.RegisterConverter("0.1.0", supportedVersions, convertFrom02x)
+	convert.RegisterConverter("0.2.0", supportedVersions, convertFrom02x)
+	convert.RegisterConverter("0.3.0", supportedVersions, convertInternal)
+	convert.RegisterConverter("0.3.1", supportedVersions, convertInternal)
+
+	// Down-converters
+	convert.RegisterConverter("0.4.0", []string{"0.3.0", "0.3.1"}, convertInternal)
+	convert.RegisterConverter("0.4.0", []string{"0.1.0", "0.2.0"}, convertTo02x)
+	convert.RegisterConverter("0.3.1", []string{"0.1.0", "0.2.0"}, convertTo02x)
+	convert.RegisterConverter("0.3.0", []string{"0.1.0", "0.2.0"}, convertTo02x)
+
+	// Creator
+	convert.RegisterCreator(supportedVersions, NewResult)
+}
+
+func NewResult(data []byte) (types.Result, error) {
+	result := &Result{}
+	if err := json.Unmarshal(data, result); err != nil {
+		return nil, err
+	}
+	for _, v := range supportedVersions {
+		if result.CNIVersion == v {
+			return result, nil
+		}
+	}
+	return nil, fmt.Errorf("result type supports %v but unmarshalled CNIVersion is %q",
+		supportedVersions, result.CNIVersion)
+}
+
+func GetResult(r types.Result) (*Result, error) {
+	resultCurrent, err := r.GetAsVersion(ImplementedSpecVersion)
+	if err != nil {
+		return nil, err
+	}
+	result, ok := resultCurrent.(*Result)
+	if !ok {
+		return nil, fmt.Errorf("failed to convert result")
+	}
+	return result, nil
+}
+
+func NewResultFromResult(result types.Result) (*Result, error) {
+	newResult, err := convert.Convert(result, ImplementedSpecVersion)
+	if err != nil {
+		return nil, err
+	}
+	return newResult.(*Result), nil
+}
+
+// Result is what gets returned from the plugin (via stdout) to the caller
+type Result struct {
+	CNIVersion string         `json:"cniVersion,omitempty"`
+	Interfaces []*Interface   `json:"interfaces,omitempty"`
+	IPs        []*IPConfig    `json:"ips,omitempty"`
+	Routes     []*types.Route `json:"routes,omitempty"`
+	DNS        types.DNS      `json:"dns,omitempty"`
+}
+
+func convert020IPConfig(from *types020.IPConfig, ipVersion string) *IPConfig {
+	return &IPConfig{
+		Version: ipVersion,
+		Address: from.IP,
+		Gateway: from.Gateway,
+	}
+}
+
+func convertFrom02x(from types.Result, toVersion string) (types.Result, error) {
+	fromResult := from.(*types020.Result)
+	toResult := &Result{
+		CNIVersion: toVersion,
+		DNS:        *fromResult.DNS.Copy(),
+		Routes:     []*types.Route{},
+	}
+	if fromResult.IP4 != nil {
+		toResult.IPs = append(toResult.IPs, convert020IPConfig(fromResult.IP4, "4"))
+		for _, fromRoute := range fromResult.IP4.Routes {
+			toResult.Routes = append(toResult.Routes, fromRoute.Copy())
+		}
+	}
+
+	if fromResult.IP6 != nil {
+		toResult.IPs = append(toResult.IPs, convert020IPConfig(fromResult.IP6, "6"))
+		for _, fromRoute := range fromResult.IP6.Routes {
+			toResult.Routes = append(toResult.Routes, fromRoute.Copy())
+		}
+	}
+
+	return toResult, nil
+}
+
+func convertInternal(from types.Result, toVersion string) (types.Result, error) {
+	fromResult := from.(*Result)
+	toResult := &Result{
+		CNIVersion: toVersion,
+		DNS:        *fromResult.DNS.Copy(),
+		Routes:     []*types.Route{},
+	}
+	for _, fromIntf := range fromResult.Interfaces {
+		toResult.Interfaces = append(toResult.Interfaces, fromIntf.Copy())
+	}
+	for _, fromIPC := range fromResult.IPs {
+		toResult.IPs = append(toResult.IPs, fromIPC.Copy())
+	}
+	for _, fromRoute := range fromResult.Routes {
+		toResult.Routes = append(toResult.Routes, fromRoute.Copy())
+	}
+	return toResult, nil
+}
+
+func convertTo02x(from types.Result, toVersion string) (types.Result, error) {
+	fromResult := from.(*Result)
+	toResult := &types020.Result{
+		CNIVersion: toVersion,
+		DNS:        *fromResult.DNS.Copy(),
+	}
+
+	for _, fromIP := range fromResult.IPs {
+		// Only convert the first IP address of each version as 0.2.0
+		// and earlier cannot handle multiple IP addresses
+		if fromIP.Version == "4" && toResult.IP4 == nil {
+			toResult.IP4 = &types020.IPConfig{
+				IP:      fromIP.Address,
+				Gateway: fromIP.Gateway,
+			}
+		} else if fromIP.Version == "6" && toResult.IP6 == nil {
+			toResult.IP6 = &types020.IPConfig{
+				IP:      fromIP.Address,
+				Gateway: fromIP.Gateway,
+			}
+		}
+		if toResult.IP4 != nil && toResult.IP6 != nil {
+			break
+		}
+	}
+
+	for _, fromRoute := range fromResult.Routes {
+		is4 := fromRoute.Dst.IP.To4() != nil
+		if is4 && toResult.IP4 != nil {
+			toResult.IP4.Routes = append(toResult.IP4.Routes, types.Route{
+				Dst: fromRoute.Dst,
+				GW:  fromRoute.GW,
+			})
+		} else if !is4 && toResult.IP6 != nil {
+			toResult.IP6.Routes = append(toResult.IP6.Routes, types.Route{
+				Dst: fromRoute.Dst,
+				GW:  fromRoute.GW,
+			})
+		}
+	}
+
+	// 0.2.0 and earlier require at least one IP address in the Result
+	if toResult.IP4 == nil && toResult.IP6 == nil {
+		return nil, fmt.Errorf("cannot convert: no valid IP addresses")
+	}
+
+	return toResult, nil
+}
+
+func (r *Result) Version() string {
+	return r.CNIVersion
+}
+
+func (r *Result) GetAsVersion(version string) (types.Result, error) {
+	// If the creator of the result did not set the CNIVersion, assume it
+	// should be the highest spec version implemented by this Result
+	if r.CNIVersion == "" {
+		r.CNIVersion = ImplementedSpecVersion
+	}
+	return convert.Convert(r, version)
+}
+
+func (r *Result) Print() error {
+	return r.PrintTo(os.Stdout)
+}
+
+func (r *Result) PrintTo(writer io.Writer) error {
+	data, err := json.MarshalIndent(r, "", "    ")
+	if err != nil {
+		return err
+	}
+	_, err = writer.Write(data)
+	return err
+}
+
+// Interface contains values about the created interfaces
+type Interface struct {
+	Name    string `json:"name"`
+	Mac     string `json:"mac,omitempty"`
+	Sandbox string `json:"sandbox,omitempty"`
+}
+
+func (i *Interface) String() string {
+	return fmt.Sprintf("%+v", *i)
+}
+
+func (i *Interface) Copy() *Interface {
+	if i == nil {
+		return nil
+	}
+	newIntf := *i
+	return &newIntf
+}
+
+// Int returns a pointer to the int value passed in.  Used to
+// set the IPConfig.Interface field.
+func Int(v int) *int {
+	return &v
+}
+
+// IPConfig contains values necessary to configure an IP address on an interface
+type IPConfig struct {
+	// IP version, either "4" or "6"
+	Version string
+	// Index into Result structs Interfaces list
+	Interface *int
+	Address   net.IPNet
+	Gateway   net.IP
+}
+
+func (i *IPConfig) String() string {
+	return fmt.Sprintf("%+v", *i)
+}
+
+func (i *IPConfig) Copy() *IPConfig {
+	if i == nil {
+		return nil
+	}
+
+	ipc := &IPConfig{
+		Version: i.Version,
+		Address: i.Address,
+		Gateway: i.Gateway,
+	}
+	if i.Interface != nil {
+		intf := *i.Interface
+		ipc.Interface = &intf
+	}
+	return ipc
+}
+
+// JSON (un)marshallable types
+type ipConfig struct {
+	Version   string      `json:"version"`
+	Interface *int        `json:"interface,omitempty"`
+	Address   types.IPNet `json:"address"`
+	Gateway   net.IP      `json:"gateway,omitempty"`
+}
+
+func (c *IPConfig) MarshalJSON() ([]byte, error) {
+	ipc := ipConfig{
+		Version:   c.Version,
+		Interface: c.Interface,
+		Address:   types.IPNet(c.Address),
+		Gateway:   c.Gateway,
+	}
+
+	return json.Marshal(ipc)
+}
+
+func (c *IPConfig) UnmarshalJSON(data []byte) error {
+	ipc := ipConfig{}
+	if err := json.Unmarshal(data, &ipc); err != nil {
+		return err
+	}
+
+	c.Version = ipc.Version
+	c.Interface = ipc.Interface
+	c.Address = net.IPNet(ipc.Address)
+	c.Gateway = ipc.Gateway
+	return nil
+}

pkg/types/040/types_suite_test.go

@@ -12,16 +12,16 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package main
+package types040_test
 
 import (
-	. "github.com/onsi/ginkgo"
-	. "github.com/onsi/gomega"
-
 	"testing"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
 )
 
-func TestMacvlan(t *testing.T) {
+func TestTypesCurrent(t *testing.T) {
 	RegisterFailHandler(Fail)
-	RunSpecs(t, "macvlan Suite")
+	RunSpecs(t, "Current Types Suite")
 }

pkg/types/040/types_test.go

@@ -0,0 +1,387 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package types040_test
+
+import (
+	"encoding/json"
+	"io"
+	"net"
+	"os"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	"github.com/containernetworking/cni/pkg/types"
+	types020 "github.com/containernetworking/cni/pkg/types/020"
+	types040 "github.com/containernetworking/cni/pkg/types/040"
+)
+
+func testResult() *types040.Result {
+	ipv4, err := types.ParseCIDR("1.2.3.30/24")
+	Expect(err).NotTo(HaveOccurred())
+	Expect(ipv4).NotTo(BeNil())
+
+	routegwv4, routev4, err := net.ParseCIDR("15.5.6.8/24")
+	Expect(err).NotTo(HaveOccurred())
+	Expect(routev4).NotTo(BeNil())
+	Expect(routegwv4).NotTo(BeNil())
+
+	ipv6, err := types.ParseCIDR("abcd:1234:ffff::cdde/64")
+	Expect(err).NotTo(HaveOccurred())
+	Expect(ipv6).NotTo(BeNil())
+
+	routegwv6, routev6, err := net.ParseCIDR("1111:dddd::aaaa/80")
+	Expect(err).NotTo(HaveOccurred())
+	Expect(routev6).NotTo(BeNil())
+	Expect(routegwv6).NotTo(BeNil())
+
+	// Set every field of the struct to ensure source compatibility
+	return &types040.Result{
+		CNIVersion: "0.3.1",
+		Interfaces: []*types040.Interface{
+			{
+				Name:    "eth0",
+				Mac:     "00:11:22:33:44:55",
+				Sandbox: "/proc/3553/ns/net",
+			},
+		},
+		IPs: []*types040.IPConfig{
+			{
+				Version:   "4",
+				Interface: types040.Int(0),
+				Address:   *ipv4,
+				Gateway:   net.ParseIP("1.2.3.1"),
+			},
+			{
+				Version:   "6",
+				Interface: types040.Int(0),
+				Address:   *ipv6,
+				Gateway:   net.ParseIP("abcd:1234:ffff::1"),
+			},
+		},
+		Routes: []*types.Route{
+			{Dst: *routev4, GW: routegwv4},
+			{Dst: *routev6, GW: routegwv6},
+		},
+		DNS: types.DNS{
+			Nameservers: []string{"1.2.3.4", "1::cafe"},
+			Domain:      "acompany.com",
+			Search:      []string{"somedomain.com", "otherdomain.net"},
+			Options:     []string{"foo", "bar"},
+		},
+	}
+}
+
+var _ = Describe("040 types operations", func() {
+	It("correctly encodes a 0.3.x Result", func() {
+		res := testResult()
+
+		// Redirect stdout to capture JSON result
+		oldStdout := os.Stdout
+		r, w, err := os.Pipe()
+		Expect(err).NotTo(HaveOccurred())
+
+		os.Stdout = w
+		err = res.Print()
+		w.Close()
+		Expect(err).NotTo(HaveOccurred())
+
+		// parse the result
+		out, err := io.ReadAll(r)
+		os.Stdout = oldStdout
+		Expect(err).NotTo(HaveOccurred())
+
+		Expect(string(out)).To(MatchJSON(`{
+    "cniVersion": "0.3.1",
+    "interfaces": [
+        {
+            "name": "eth0",
+            "mac": "00:11:22:33:44:55",
+            "sandbox": "/proc/3553/ns/net"
+        }
+    ],
+    "ips": [
+        {
+            "version": "4",
+            "interface": 0,
+            "address": "1.2.3.30/24",
+            "gateway": "1.2.3.1"
+        },
+        {
+            "version": "6",
+            "interface": 0,
+            "address": "abcd:1234:ffff::cdde/64",
+            "gateway": "abcd:1234:ffff::1"
+        }
+    ],
+    "routes": [
+        {
+            "dst": "15.5.6.0/24",
+            "gw": "15.5.6.8"
+        },
+        {
+            "dst": "1111:dddd::/80",
+            "gw": "1111:dddd::aaaa"
+        }
+    ],
+    "dns": {
+        "nameservers": [
+            "1.2.3.4",
+            "1::cafe"
+        ],
+        "domain": "acompany.com",
+        "search": [
+            "somedomain.com",
+            "otherdomain.net"
+        ],
+        "options": [
+            "foo",
+            "bar"
+        ]
+    }
+}`))
+	})
+
+	It("correctly encodes a 0.1.0 Result", func() {
+		res, err := testResult().GetAsVersion("0.1.0")
+		Expect(err).NotTo(HaveOccurred())
+
+		// Redirect stdout to capture JSON result
+		oldStdout := os.Stdout
+		r, w, err := os.Pipe()
+		Expect(err).NotTo(HaveOccurred())
+
+		os.Stdout = w
+		err = res.Print()
+		w.Close()
+		Expect(err).NotTo(HaveOccurred())
+
+		// parse the result
+		out, err := io.ReadAll(r)
+		os.Stdout = oldStdout
+		Expect(err).NotTo(HaveOccurred())
+
+		Expect(string(out)).To(MatchJSON(`{
+    "cniVersion": "0.1.0",
+    "ip4": {
+        "ip": "1.2.3.30/24",
+        "gateway": "1.2.3.1",
+        "routes": [
+            {
+                "dst": "15.5.6.0/24",
+                "gw": "15.5.6.8"
+            }
+        ]
+    },
+    "ip6": {
+        "ip": "abcd:1234:ffff::cdde/64",
+        "gateway": "abcd:1234:ffff::1",
+        "routes": [
+            {
+                "dst": "1111:dddd::/80",
+                "gw": "1111:dddd::aaaa"
+            }
+        ]
+    },
+    "dns": {
+        "nameservers": [
+            "1.2.3.4",
+            "1::cafe"
+        ],
+        "domain": "acompany.com",
+        "search": [
+            "somedomain.com",
+            "otherdomain.net"
+        ],
+        "options": [
+            "foo",
+            "bar"
+        ]
+    }
+}`))
+	})
+
+	It("correctly round-trips a 0.2.0 Result with route gateways", func() {
+		ipv4, err := types.ParseCIDR("1.2.3.30/24")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(ipv4).NotTo(BeNil())
+
+		routegwv4, routev4, err := net.ParseCIDR("15.5.6.8/24")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(routev4).NotTo(BeNil())
+		Expect(routegwv4).NotTo(BeNil())
+
+		ipv6, err := types.ParseCIDR("abcd:1234:ffff::cdde/64")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(ipv6).NotTo(BeNil())
+
+		routegwv6, routev6, err := net.ParseCIDR("1111:dddd::aaaa/80")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(routev6).NotTo(BeNil())
+		Expect(routegwv6).NotTo(BeNil())
+
+		// Set every field of the struct to ensure source compatibility
+		res := &types020.Result{
+			CNIVersion: types020.ImplementedSpecVersion,
+			IP4: &types020.IPConfig{
+				IP:      *ipv4,
+				Gateway: net.ParseIP("1.2.3.1"),
+				Routes: []types.Route{
+					{Dst: *routev4, GW: routegwv4},
+				},
+			},
+			IP6: &types020.IPConfig{
+				IP:      *ipv6,
+				Gateway: net.ParseIP("abcd:1234:ffff::1"),
+				Routes: []types.Route{
+					{Dst: *routev6, GW: routegwv6},
+				},
+			},
+			DNS: types.DNS{
+				Nameservers: []string{"1.2.3.4", "1::cafe"},
+				Domain:      "acompany.com",
+				Search:      []string{"somedomain.com", "otherdomain.net"},
+				Options:     []string{"foo", "bar"},
+			},
+		}
+
+		// Convert to 040
+		newRes, err := types040.NewResultFromResult(res)
+		Expect(err).NotTo(HaveOccurred())
+		// Convert back to 0.2.0
+		oldRes, err := newRes.GetAsVersion("0.2.0")
+		Expect(err).NotTo(HaveOccurred())
+
+		// Match JSON so we can figure out what's wrong if something fails the test
+		origJson, err := json.Marshal(res)
+		Expect(err).NotTo(HaveOccurred())
+		oldJson, err := json.Marshal(oldRes)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(oldJson).To(MatchJSON(origJson))
+	})
+
+	It("correctly round-trips a 0.2.0 Result without route gateways", func() {
+		ipv4, err := types.ParseCIDR("1.2.3.30/24")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(ipv4).NotTo(BeNil())
+
+		_, routev4, err := net.ParseCIDR("15.5.6.0/24")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(routev4).NotTo(BeNil())
+
+		ipv6, err := types.ParseCIDR("abcd:1234:ffff::cdde/64")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(ipv6).NotTo(BeNil())
+
+		_, routev6, err := net.ParseCIDR("1111:dddd::aaaa/80")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(routev6).NotTo(BeNil())
+
+		// Set every field of the struct to ensure source compatibility
+		res := &types020.Result{
+			CNIVersion: types020.ImplementedSpecVersion,
+			IP4: &types020.IPConfig{
+				IP:      *ipv4,
+				Gateway: net.ParseIP("1.2.3.1"),
+				Routes: []types.Route{
+					{Dst: *routev4},
+				},
+			},
+			IP6: &types020.IPConfig{
+				IP:      *ipv6,
+				Gateway: net.ParseIP("abcd:1234:ffff::1"),
+				Routes: []types.Route{
+					{Dst: *routev6},
+				},
+			},
+			DNS: types.DNS{
+				Nameservers: []string{"1.2.3.4", "1::cafe"},
+				Domain:      "acompany.com",
+				Search:      []string{"somedomain.com", "otherdomain.net"},
+				Options:     []string{"foo", "bar"},
+			},
+		}
+
+		// Convert to 040
+		newRes, err := types040.NewResultFromResult(res)
+		Expect(err).NotTo(HaveOccurred())
+		// Convert back to 0.2.0
+		oldRes, err := newRes.GetAsVersion("0.2.0")
+		Expect(err).NotTo(HaveOccurred())
+
+		// Match JSON so we can figure out what's wrong if something fails the test
+		origJson, err := json.Marshal(res)
+		Expect(err).NotTo(HaveOccurred())
+		oldJson, err := json.Marshal(oldRes)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(oldJson).To(MatchJSON(origJson))
+	})
+
+	It("correctly marshals and unmarshals interface index 0", func() {
+		ipc := &types040.IPConfig{
+			Version:   "4",
+			Interface: types040.Int(0),
+			Address: net.IPNet{
+				IP:   net.ParseIP("10.1.2.3"),
+				Mask: net.IPv4Mask(255, 255, 255, 0),
+			},
+		}
+
+		jsonBytes, err := json.Marshal(ipc)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(jsonBytes).To(MatchJSON(`{
+    "version": "4",
+    "interface": 0,
+    "address": "10.1.2.3/24"
+}`))
+
+		recovered := &types040.IPConfig{}
+		Expect(json.Unmarshal(jsonBytes, recovered)).To(Succeed())
+		Expect(recovered).To(Equal(ipc))
+	})
+
+	It("fails when downconverting a config to 0.2.0 that has no IPs", func() {
+		res := testResult()
+		res.IPs = nil
+		res.Routes = nil
+		_, err := res.GetAsVersion("0.2.0")
+		Expect(err).To(MatchError("cannot convert: no valid IP addresses"))
+	})
+
+	Context("when unmarshalling json fails", func() {
+		It("returns an error", func() {
+			recovered := &types040.IPConfig{}
+			err := json.Unmarshal([]byte(`{"address": 5}`), recovered)
+			Expect(err).To(MatchError(HavePrefix("json: cannot unmarshal")))
+		})
+	})
+
+	It("correctly marshals a missing interface index", func() {
+		ipc := &types040.IPConfig{
+			Version: "4",
+			Address: net.IPNet{
+				IP:   net.ParseIP("10.1.2.3"),
+				Mask: net.IPv4Mask(255, 255, 255, 0),
+			},
+		}
+
+		json, err := json.Marshal(ipc)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(json).To(MatchJSON(`{
+    "version": "4",
+    "address": "10.1.2.3/24"
+}`))
+	})
+})

pkg/types/100/types.go

@@ -0,0 +1,352 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package types100
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net"
+	"os"
+
+	"github.com/containernetworking/cni/pkg/types"
+	types040 "github.com/containernetworking/cni/pkg/types/040"
+	convert "github.com/containernetworking/cni/pkg/types/internal"
+)
+
+// The types did not change between v1.0 and v1.1
+const ImplementedSpecVersion string = "1.1.0"
+
+var supportedVersions = []string{"1.0.0", "1.1.0"}
+
+// Register converters for all versions less than the implemented spec version
+func init() {
+	// Up-converters
+	convert.RegisterConverter("0.1.0", supportedVersions, convertFrom02x)
+	convert.RegisterConverter("0.2.0", supportedVersions, convertFrom02x)
+	convert.RegisterConverter("0.3.0", supportedVersions, convertFrom04x)
+	convert.RegisterConverter("0.3.1", supportedVersions, convertFrom04x)
+	convert.RegisterConverter("0.4.0", supportedVersions, convertFrom04x)
+	convert.RegisterConverter("1.0.0", []string{"1.1.0"}, convertFrom100)
+
+	// Down-converters
+	convert.RegisterConverter("1.0.0", []string{"0.3.0", "0.3.1", "0.4.0"}, convertTo04x)
+	convert.RegisterConverter("1.0.0", []string{"0.1.0", "0.2.0"}, convertTo02x)
+	convert.RegisterConverter("1.1.0", []string{"0.3.0", "0.3.1", "0.4.0"}, convertTo04x)
+	convert.RegisterConverter("1.1.0", []string{"0.1.0", "0.2.0"}, convertTo02x)
+	convert.RegisterConverter("1.1.0", []string{"1.0.0"}, convertFrom100)
+
+	// Creator
+	convert.RegisterCreator(supportedVersions, NewResult)
+}
+
+func NewResult(data []byte) (types.Result, error) {
+	result := &Result{}
+	if err := json.Unmarshal(data, result); err != nil {
+		return nil, err
+	}
+	for _, v := range supportedVersions {
+		if result.CNIVersion == v {
+			return result, nil
+		}
+	}
+	return nil, fmt.Errorf("result type supports %v but unmarshalled CNIVersion is %q",
+		supportedVersions, result.CNIVersion)
+}
+
+func GetResult(r types.Result) (*Result, error) {
+	resultCurrent, err := r.GetAsVersion(ImplementedSpecVersion)
+	if err != nil {
+		return nil, err
+	}
+	result, ok := resultCurrent.(*Result)
+	if !ok {
+		return nil, fmt.Errorf("failed to convert result")
+	}
+	return result, nil
+}
+
+func NewResultFromResult(result types.Result) (*Result, error) {
+	newResult, err := convert.Convert(result, ImplementedSpecVersion)
+	if err != nil {
+		return nil, err
+	}
+	return newResult.(*Result), nil
+}
+
+// Result is what gets returned from the plugin (via stdout) to the caller
+type Result struct {
+	CNIVersion string         `json:"cniVersion,omitempty"`
+	Interfaces []*Interface   `json:"interfaces,omitempty"`
+	IPs        []*IPConfig    `json:"ips,omitempty"`
+	Routes     []*types.Route `json:"routes,omitempty"`
+	DNS        types.DNS      `json:"dns,omitempty"`
+}
+
+// Note: DNS should be omit if DNS is empty but default Marshal function
+// will output empty structure hence need to write a Marshal function
+func (r *Result) MarshalJSON() ([]byte, error) {
+	// use type alias to escape recursion for json.Marshal() to MarshalJSON()
+	type fixObjType = Result
+
+	bytes, err := json.Marshal(fixObjType(*r)) //nolint:all
+	if err != nil {
+		return nil, err
+	}
+
+	fixupObj := make(map[string]interface{})
+	if err := json.Unmarshal(bytes, &fixupObj); err != nil {
+		return nil, err
+	}
+
+	if r.DNS.IsEmpty() {
+		delete(fixupObj, "dns")
+	}
+
+	return json.Marshal(fixupObj)
+}
+
+// convertFrom100 does nothing except set the version; the types are the same
+func convertFrom100(from types.Result, toVersion string) (types.Result, error) {
+	fromResult := from.(*Result)
+
+	result := &Result{
+		CNIVersion: toVersion,
+		Interfaces: fromResult.Interfaces,
+		IPs:        fromResult.IPs,
+		Routes:     fromResult.Routes,
+		DNS:        fromResult.DNS,
+	}
+	return result, nil
+}
+
+func convertFrom02x(from types.Result, toVersion string) (types.Result, error) {
+	result040, err := convert.Convert(from, "0.4.0")
+	if err != nil {
+		return nil, err
+	}
+	result100, err := convertFrom04x(result040, toVersion)
+	if err != nil {
+		return nil, err
+	}
+	return result100, nil
+}
+
+func convertIPConfigFrom040(from *types040.IPConfig) *IPConfig {
+	to := &IPConfig{
+		Address: from.Address,
+		Gateway: from.Gateway,
+	}
+	if from.Interface != nil {
+		intf := *from.Interface
+		to.Interface = &intf
+	}
+	return to
+}
+
+func convertInterfaceFrom040(from *types040.Interface) *Interface {
+	return &Interface{
+		Name:    from.Name,
+		Mac:     from.Mac,
+		Sandbox: from.Sandbox,
+	}
+}
+
+func convertFrom04x(from types.Result, toVersion string) (types.Result, error) {
+	fromResult := from.(*types040.Result)
+	toResult := &Result{
+		CNIVersion: toVersion,
+		DNS:        *fromResult.DNS.Copy(),
+		Routes:     []*types.Route{},
+	}
+	for _, fromIntf := range fromResult.Interfaces {
+		toResult.Interfaces = append(toResult.Interfaces, convertInterfaceFrom040(fromIntf))
+	}
+	for _, fromIPC := range fromResult.IPs {
+		toResult.IPs = append(toResult.IPs, convertIPConfigFrom040(fromIPC))
+	}
+	for _, fromRoute := range fromResult.Routes {
+		toResult.Routes = append(toResult.Routes, fromRoute.Copy())
+	}
+	return toResult, nil
+}
+
+func convertIPConfigTo040(from *IPConfig) *types040.IPConfig {
+	version := "6"
+	if from.Address.IP.To4() != nil {
+		version = "4"
+	}
+	to := &types040.IPConfig{
+		Version: version,
+		Address: from.Address,
+		Gateway: from.Gateway,
+	}
+	if from.Interface != nil {
+		intf := *from.Interface
+		to.Interface = &intf
+	}
+	return to
+}
+
+func convertInterfaceTo040(from *Interface) *types040.Interface {
+	return &types040.Interface{
+		Name:    from.Name,
+		Mac:     from.Mac,
+		Sandbox: from.Sandbox,
+	}
+}
+
+func convertTo04x(from types.Result, toVersion string) (types.Result, error) {
+	fromResult := from.(*Result)
+	toResult := &types040.Result{
+		CNIVersion: toVersion,
+		DNS:        *fromResult.DNS.Copy(),
+		Routes:     []*types.Route{},
+	}
+	for _, fromIntf := range fromResult.Interfaces {
+		toResult.Interfaces = append(toResult.Interfaces, convertInterfaceTo040(fromIntf))
+	}
+	for _, fromIPC := range fromResult.IPs {
+		toResult.IPs = append(toResult.IPs, convertIPConfigTo040(fromIPC))
+	}
+	for _, fromRoute := range fromResult.Routes {
+		toResult.Routes = append(toResult.Routes, fromRoute.Copy())
+	}
+	return toResult, nil
+}
+
+func convertTo02x(from types.Result, toVersion string) (types.Result, error) {
+	// First convert to 0.4.0
+	result040, err := convertTo04x(from, "0.4.0")
+	if err != nil {
+		return nil, err
+	}
+	result02x, err := convert.Convert(result040, toVersion)
+	if err != nil {
+		return nil, err
+	}
+	return result02x, nil
+}
+
+func (r *Result) Version() string {
+	return r.CNIVersion
+}
+
+func (r *Result) GetAsVersion(version string) (types.Result, error) {
+	// If the creator of the result did not set the CNIVersion, assume it
+	// should be the highest spec version implemented by this Result
+	if r.CNIVersion == "" {
+		r.CNIVersion = ImplementedSpecVersion
+	}
+	return convert.Convert(r, version)
+}
+
+func (r *Result) Print() error {
+	return r.PrintTo(os.Stdout)
+}
+
+func (r *Result) PrintTo(writer io.Writer) error {
+	data, err := json.MarshalIndent(r, "", "    ")
+	if err != nil {
+		return err
+	}
+	_, err = writer.Write(data)
+	return err
+}
+
+// Interface contains values about the created interfaces
+type Interface struct {
+	Name       string `json:"name"`
+	Mac        string `json:"mac,omitempty"`
+	Mtu        int    `json:"mtu,omitempty"`
+	Sandbox    string `json:"sandbox,omitempty"`
+	SocketPath string `json:"socketPath,omitempty"`
+	PciID      string `json:"pciID,omitempty"`
+}
+
+func (i *Interface) String() string {
+	return fmt.Sprintf("%+v", *i)
+}
+
+func (i *Interface) Copy() *Interface {
+	if i == nil {
+		return nil
+	}
+	newIntf := *i
+	return &newIntf
+}
+
+// Int returns a pointer to the int value passed in.  Used to
+// set the IPConfig.Interface field.
+func Int(v int) *int {
+	return &v
+}
+
+// IPConfig contains values necessary to configure an IP address on an interface
+type IPConfig struct {
+	// Index into Result structs Interfaces list
+	Interface *int
+	Address   net.IPNet
+	Gateway   net.IP
+}
+
+func (i *IPConfig) String() string {
+	return fmt.Sprintf("%+v", *i)
+}
+
+func (i *IPConfig) Copy() *IPConfig {
+	if i == nil {
+		return nil
+	}
+
+	ipc := &IPConfig{
+		Address: i.Address,
+		Gateway: i.Gateway,
+	}
+	if i.Interface != nil {
+		intf := *i.Interface
+		ipc.Interface = &intf
+	}
+	return ipc
+}
+
+// JSON (un)marshallable types
+type ipConfig struct {
+	Interface *int        `json:"interface,omitempty"`
+	Address   types.IPNet `json:"address"`
+	Gateway   net.IP      `json:"gateway,omitempty"`
+}
+
+func (c *IPConfig) MarshalJSON() ([]byte, error) {
+	ipc := ipConfig{
+		Interface: c.Interface,
+		Address:   types.IPNet(c.Address),
+		Gateway:   c.Gateway,
+	}
+
+	return json.Marshal(ipc)
+}
+
+func (c *IPConfig) UnmarshalJSON(data []byte) error {
+	ipc := ipConfig{}
+	if err := json.Unmarshal(data, &ipc); err != nil {
+		return err
+	}
+
+	c.Interface = ipc.Interface
+	c.Address = net.IPNet(ipc.Address)
+	c.Gateway = ipc.Gateway
+	return nil
+}

pkg/types/100/types_suite_test.go

@@ -12,16 +12,16 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package main
+package types100_test
 
 import (
-	. "github.com/onsi/ginkgo"
-	. "github.com/onsi/gomega"
-
 	"testing"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
 )
 
-func TestBridge(t *testing.T) {
+func TestTypesCurrent(t *testing.T) {
 	RegisterFailHandler(Fail)
-	RunSpecs(t, "bridge Suite")
+	RunSpecs(t, "Current Types Suite")
 }

pkg/types/100/types_test.go

@@ -0,0 +1,345 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package types100_test
+
+import (
+	"encoding/json"
+	"io"
+	"net"
+	"os"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	"github.com/containernetworking/cni/pkg/types"
+	current "github.com/containernetworking/cni/pkg/types/100"
+)
+
+func testResult() *current.Result {
+	ipv4, err := types.ParseCIDR("1.2.3.30/24")
+	Expect(err).NotTo(HaveOccurred())
+	Expect(ipv4).NotTo(BeNil())
+
+	routegwv4, routev4, err := net.ParseCIDR("15.5.6.8/24")
+	Expect(err).NotTo(HaveOccurred())
+	Expect(routev4).NotTo(BeNil())
+	Expect(routegwv4).NotTo(BeNil())
+
+	ipv6, err := types.ParseCIDR("abcd:1234:ffff::cdde/64")
+	Expect(err).NotTo(HaveOccurred())
+	Expect(ipv6).NotTo(BeNil())
+
+	routegwv6, routev6, err := net.ParseCIDR("1111:dddd::aaaa/80")
+	Expect(err).NotTo(HaveOccurred())
+	Expect(routev6).NotTo(BeNil())
+	Expect(routegwv6).NotTo(BeNil())
+	// Set every field of the struct to ensure source compatibility
+	return &current.Result{
+		CNIVersion: current.ImplementedSpecVersion,
+		Interfaces: []*current.Interface{
+			{
+				Name:       "eth0",
+				Mac:        "00:11:22:33:44:55",
+				Mtu:        1500,
+				Sandbox:    "/proc/3553/ns/net",
+				PciID:      "8086:9a01",
+				SocketPath: "/path/to/vhost/fd",
+			},
+		},
+		IPs: []*current.IPConfig{
+			{
+				Interface: current.Int(0),
+				Address:   *ipv4,
+				Gateway:   net.ParseIP("1.2.3.1"),
+			},
+			{
+				Interface: current.Int(0),
+				Address:   *ipv6,
+				Gateway:   net.ParseIP("abcd:1234:ffff::1"),
+			},
+		},
+		Routes: []*types.Route{
+			{Dst: *routev4, GW: routegwv4},
+			{Dst: *routev6, GW: routegwv6},
+		},
+		DNS: types.DNS{
+			Nameservers: []string{"1.2.3.4", "1::cafe"},
+			Domain:      "acompany.com",
+			Search:      []string{"somedomain.com", "otherdomain.net"},
+			Options:     []string{"foo", "bar"},
+		},
+	}
+}
+
+var _ = Describe("Current types operations", func() {
+	It("correctly encodes a 1.1.0 Result", func() {
+		res := testResult()
+
+		// Redirect stdout to capture JSON result
+		oldStdout := os.Stdout
+		r, w, err := os.Pipe()
+		Expect(err).NotTo(HaveOccurred())
+
+		os.Stdout = w
+		err = res.Print()
+		w.Close()
+		Expect(err).NotTo(HaveOccurred())
+
+		// parse the result
+		out, err := io.ReadAll(r)
+		os.Stdout = oldStdout
+		Expect(err).NotTo(HaveOccurred())
+
+		Expect(string(out)).To(MatchJSON(`{
+    "cniVersion": "` + current.ImplementedSpecVersion + `",
+    "interfaces": [
+        {
+            "name":        "eth0",
+            "mac":         "00:11:22:33:44:55",
+            "mtu": 1500,
+            "sandbox":     "/proc/3553/ns/net",
+            "pciID": 	   "8086:9a01",
+            "socketPath":  "/path/to/vhost/fd"
+        }
+    ],
+    "ips": [
+        {
+            "interface": 0,
+            "address": "1.2.3.30/24",
+            "gateway": "1.2.3.1"
+        },
+        {
+            "interface": 0,
+            "address": "abcd:1234:ffff::cdde/64",
+            "gateway": "abcd:1234:ffff::1"
+        }
+    ],
+    "routes": [
+        {
+            "dst": "15.5.6.0/24",
+            "gw": "15.5.6.8"
+        },
+        {
+            "dst": "1111:dddd::/80",
+            "gw": "1111:dddd::aaaa"
+        }
+    ],
+    "dns": {
+        "nameservers": [
+            "1.2.3.4",
+            "1::cafe"
+        ],
+        "domain": "acompany.com",
+        "search": [
+            "somedomain.com",
+            "otherdomain.net"
+        ],
+        "options": [
+            "foo",
+            "bar"
+        ]
+    }
+}`))
+	})
+
+	It("correctly converts a 1.0.0 Result to 1.1.0", func() {
+		tr, err := testResult().GetAsVersion("1.0.0")
+		Expect(err).NotTo(HaveOccurred())
+
+		trv1, ok := tr.(*current.Result)
+		Expect(ok).To(BeTrue())
+
+		// 1.0.0 and 1.1.0 should be the same except for CNI version
+		Expect(trv1.CNIVersion).To(Equal("1.0.0"))
+
+		// If we convert 1.0.0 back to 1.1.0 it should be identical
+		trv11, err := trv1.GetAsVersion("1.1.0")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(trv11).To(Equal(testResult()))
+	})
+
+	It("correctly encodes a 0.1.0 Result", func() {
+		res, err := testResult().GetAsVersion("0.1.0")
+		Expect(err).NotTo(HaveOccurred())
+
+		// Redirect stdout to capture JSON result
+		oldStdout := os.Stdout
+		r, w, err := os.Pipe()
+		Expect(err).NotTo(HaveOccurred())
+
+		os.Stdout = w
+		err = res.Print()
+		w.Close()
+		Expect(err).NotTo(HaveOccurred())
+
+		// parse the result
+		out, err := io.ReadAll(r)
+		os.Stdout = oldStdout
+		Expect(err).NotTo(HaveOccurred())
+
+		Expect(string(out)).To(MatchJSON(`{
+    "cniVersion": "0.1.0",
+    "ip4": {
+        "ip": "1.2.3.30/24",
+        "gateway": "1.2.3.1",
+        "routes": [
+            {
+                "dst": "15.5.6.0/24",
+                "gw": "15.5.6.8"
+            }
+        ]
+    },
+    "ip6": {
+        "ip": "abcd:1234:ffff::cdde/64",
+        "gateway": "abcd:1234:ffff::1",
+        "routes": [
+            {
+                "dst": "1111:dddd::/80",
+                "gw": "1111:dddd::aaaa"
+            }
+        ]
+    },
+    "dns": {
+        "nameservers": [
+            "1.2.3.4",
+            "1::cafe"
+        ],
+        "domain": "acompany.com",
+        "search": [
+            "somedomain.com",
+            "otherdomain.net"
+        ],
+        "options": [
+            "foo",
+            "bar"
+        ]
+    }
+}`))
+	})
+
+	It("correctly encodes a 0.4.0 Result", func() {
+		res, err := testResult().GetAsVersion("0.4.0")
+		Expect(err).NotTo(HaveOccurred())
+
+		// Redirect stdout to capture JSON result
+		oldStdout := os.Stdout
+		r, w, err := os.Pipe()
+		Expect(err).NotTo(HaveOccurred())
+
+		os.Stdout = w
+		err = res.Print()
+		w.Close()
+		Expect(err).NotTo(HaveOccurred())
+
+		// parse the result
+		out, err := io.ReadAll(r)
+		os.Stdout = oldStdout
+		Expect(err).NotTo(HaveOccurred())
+
+		Expect(string(out)).To(MatchJSON(`{
+    "cniVersion": "0.4.0",
+    "interfaces": [
+        {
+            "name": "eth0",
+            "mac": "00:11:22:33:44:55",
+            "sandbox": "/proc/3553/ns/net"
+        }
+    ],
+    "ips": [
+        {
+            "interface": 0,
+            "version": "4",
+            "address": "1.2.3.30/24",
+            "gateway": "1.2.3.1"
+        },
+        {
+            "interface": 0,
+            "version": "6",
+            "address": "abcd:1234:ffff::cdde/64",
+            "gateway": "abcd:1234:ffff::1"
+        }
+    ],
+    "routes": [
+        {
+            "dst": "15.5.6.0/24",
+            "gw": "15.5.6.8"
+        },
+        {
+            "dst": "1111:dddd::/80",
+            "gw": "1111:dddd::aaaa"
+        }
+    ],
+    "dns": {
+        "nameservers": [
+            "1.2.3.4",
+            "1::cafe"
+        ],
+        "domain": "acompany.com",
+        "search": [
+            "somedomain.com",
+            "otherdomain.net"
+        ],
+        "options": [
+            "foo",
+            "bar"
+        ]
+    }
+}`))
+	})
+
+	It("correctly marshals and unmarshals interface index 0", func() {
+		ipc := &current.IPConfig{
+			Interface: current.Int(0),
+			Address: net.IPNet{
+				IP:   net.ParseIP("10.1.2.3"),
+				Mask: net.IPv4Mask(255, 255, 255, 0),
+			},
+		}
+
+		jsonBytes, err := json.Marshal(ipc)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(jsonBytes).To(MatchJSON(`{
+    "interface": 0,
+    "address": "10.1.2.3/24"
+}`))
+
+		recovered := &current.IPConfig{}
+		Expect(json.Unmarshal(jsonBytes, recovered)).To(Succeed())
+		Expect(recovered).To(Equal(ipc))
+	})
+
+	Context("when unmarshalling json fails", func() {
+		It("returns an error", func() {
+			recovered := &current.IPConfig{}
+			err := json.Unmarshal([]byte(`{"address": 5}`), recovered)
+			Expect(err).To(MatchError(HavePrefix("json: cannot unmarshal")))
+		})
+	})
+
+	It("correctly marshals a missing interface index", func() {
+		ipc := &current.IPConfig{
+			Address: net.IPNet{
+				IP:   net.ParseIP("10.1.2.3"),
+				Mask: net.IPv4Mask(255, 255, 255, 0),
+			},
+		}
+
+		json, err := json.Marshal(ipc)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(json).To(MatchJSON(`{
+    "address": "10.1.2.3/24"
+}`))
+	})
+})

pkg/types/args.go

@@ -26,8 +26,8 @@ import (
 type UnmarshallableBool bool
 
 // UnmarshalText implements the encoding.TextUnmarshaler interface.
-// Returns boolean true if the string is "1" or "[Tt]rue"
-// Returns boolean false if the string is "0" or "[Ff]alse"
+// Returns boolean true if the string is "1" or "true" or "True"
+// Returns boolean false if the string is "0" or "false" or "False”
 func (b *UnmarshallableBool) UnmarshalText(data []byte) error {
 	s := strings.ToLower(string(data))
 	switch s {
@@ -36,11 +36,21 @@ func (b *UnmarshallableBool) UnmarshalText(data []byte) error {
 	case "0", "false":
 		*b = false
 	default:
-		return fmt.Errorf("Boolean unmarshal error: invalid input %s", s)
+		return fmt.Errorf("boolean unmarshal error: invalid input %s", s)
 	}
 	return nil
 }
 
+// UnmarshallableString typedef for builtin string
+type UnmarshallableString string
+
+// UnmarshalText implements the encoding.TextUnmarshaler interface.
+// Returns the string
+func (s *UnmarshallableString) UnmarshalText(data []byte) error {
+	*s = UnmarshallableString(data)
+	return nil
+}
+
 // CommonArgs contains the IgnoreUnknown argument
 // and must be embedded by all Arg structs
 type CommonArgs struct {
@@ -53,6 +63,12 @@ func GetKeyField(keyString string, v reflect.Value) reflect.Value {
 	return v.Elem().FieldByName(keyString)
 }
 
+// UnmarshalableArgsError is used to indicate error unmarshalling args
+// from the args-string in the form "K=V;K2=V2;..."
+type UnmarshalableArgsError struct {
+	error
+}
+
 // LoadArgs parses args from a string in the form "K=V;K2=V2;..."
 func LoadArgs(args string, container interface{}) error {
 	if args == "" {
@@ -76,10 +92,25 @@ func LoadArgs(args string, container interface{}) error {
 			continue
 		}
 
-		u := keyField.Addr().Interface().(encoding.TextUnmarshaler)
+		var keyFieldInterface interface{}
+		switch {
+		case keyField.Kind() == reflect.Ptr:
+			keyField.Set(reflect.New(keyField.Type().Elem()))
+			keyFieldInterface = keyField.Interface()
+		case keyField.CanAddr() && keyField.Addr().CanInterface():
+			keyFieldInterface = keyField.Addr().Interface()
+		default:
+			return UnmarshalableArgsError{fmt.Errorf("field '%s' has no valid interface", keyString)}
+		}
+		u, ok := keyFieldInterface.(encoding.TextUnmarshaler)
+		if !ok {
+			return UnmarshalableArgsError{fmt.Errorf(
+				"ARGS: cannot unmarshal into field '%s' - type '%s' does not implement encoding.TextUnmarshaler",
+				keyString, reflect.TypeOf(keyFieldInterface))}
+		}
 		err := u.UnmarshalText([]byte(valueString))
 		if err != nil {
-			return fmt.Errorf("ARGS: error parsing value of pair %q: %v)", pair, err)
+			return fmt.Errorf("ARGS: error parsing value of pair %q: %w", pair, err)
 		}
 	}
 

pkg/types/args_test.go

@@ -15,13 +15,13 @@
 package types_test
 
 import (
+	"net"
 	"reflect"
 
-	. "github.com/containernetworking/cni/pkg/types"
-
-	. "github.com/onsi/ginkgo"
-	. "github.com/onsi/ginkgo/extensions/table"
+	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
+
+	. "github.com/containernetworking/cni/pkg/types"
 )
 
 var _ = Describe("UnmarshallableBool UnmarshalText", func() {
@@ -47,6 +47,21 @@ var _ = Describe("UnmarshallableBool UnmarshalText", func() {
 	})
 })
 
+var _ = Describe("UnmarshallableString UnmarshalText", func() {
+	DescribeTable("string to string detection should succeed in all cases",
+		func(inputs []string, expected string) {
+			for _, s := range inputs {
+				var us UnmarshallableString
+				err := us.UnmarshalText([]byte(s))
+				Expect(err).ToNot(HaveOccurred())
+				Expect(string(us)).To(Equal(expected))
+			}
+		},
+		Entry("parse empty string", []string{""}, ""),
+		Entry("parse non-empty string", []string{"notempty"}, "notempty"),
+	)
+})
+
 var _ = Describe("GetKeyField", func() {
 	type testcontainer struct {
 		Valid string `json:"valid,omitempty"`
@@ -103,4 +118,45 @@ var _ = Describe("LoadArgs", func() {
 			Expect(err).NotTo(HaveOccurred())
 		})
 	})
+
+	Context("When known arguments are passed and cannot be unmarshalled", func() {
+		It("LoadArgs should fail", func() {
+			conf := struct {
+				IP IPNet
+			}{}
+			err := LoadArgs("IP=10.0.0.0/24", &conf)
+			Expect(err).To(HaveOccurred())
+		})
+	})
+
+	Context("When loading known arguments", func() {
+		It("should succeed if argument is marshallable value type", func() {
+			conf := struct {
+				IP net.IP
+				CommonArgs
+			}{}
+			err := LoadArgs("IP=10.0.0.0", &conf)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(conf.IP.String()).To(Equal("10.0.0.0"))
+		})
+
+		It("should succeed if argument is marshallable pointer type", func() {
+			conf := struct {
+				IP *net.IP
+				CommonArgs
+			}{}
+			err := LoadArgs("IP=10.0.0.0", &conf)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(conf.IP.String()).To(Equal("10.0.0.0"))
+		})
+
+		It("should fail if argument is pointer of marshallable pointer type", func() {
+			conf := struct {
+				IP **net.IP
+				CommonArgs
+			}{}
+			err := LoadArgs("IP=10.0.0.0", &conf)
+			Expect(err).To(HaveOccurred())
+		})
+	})
 })

pkg/types/create/create.go

@@ -0,0 +1,59 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package create
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"github.com/containernetworking/cni/pkg/types"
+	_ "github.com/containernetworking/cni/pkg/types/020"
+	_ "github.com/containernetworking/cni/pkg/types/040"
+	_ "github.com/containernetworking/cni/pkg/types/100"
+	convert "github.com/containernetworking/cni/pkg/types/internal"
+)
+
+// DecodeVersion returns the CNI version from CNI configuration or result JSON,
+// or an error if the operation could not be performed.
+func DecodeVersion(jsonBytes []byte) (string, error) {
+	var conf struct {
+		CNIVersion string `json:"cniVersion"`
+	}
+	err := json.Unmarshal(jsonBytes, &conf)
+	if err != nil {
+		return "", fmt.Errorf("decoding version from network config: %w", err)
+	}
+	if conf.CNIVersion == "" {
+		return "0.1.0", nil
+	}
+	return conf.CNIVersion, nil
+}
+
+// Create creates a CNI Result using the given JSON with the expected
+// version, or an error if the creation could not be performed
+func Create(version string, bytes []byte) (types.Result, error) {
+	return convert.Create(version, bytes)
+}
+
+// CreateFromBytes creates a CNI Result from the given JSON, automatically
+// detecting the CNI spec version of the result. An error is returned if the
+// operation could not be performed.
+func CreateFromBytes(bytes []byte) (types.Result, error) {
+	version, err := DecodeVersion(bytes)
+	if err != nil {
+		return nil, err
+	}
+	return convert.Create(version, bytes)
+}

pkg/types/internal/convert.go

@@ -0,0 +1,92 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package convert
+
+import (
+	"fmt"
+
+	"github.com/containernetworking/cni/pkg/types"
+)
+
+// ConvertFn should convert from the given arbitrary Result type into a
+// Result implementing CNI specification version passed in toVersion.
+// The function is guaranteed to be passed a Result type matching the
+// fromVersion it was registered with, and is guaranteed to be
+// passed a toVersion matching one of the toVersions it was registered with.
+type ConvertFn func(from types.Result, toVersion string) (types.Result, error)
+
+type converter struct {
+	// fromVersion is the CNI Result spec version that convertFn accepts
+	fromVersion string
+	// toVersions is a list of versions that convertFn can convert to
+	toVersions []string
+	convertFn  ConvertFn
+}
+
+var converters []*converter
+
+func findConverter(fromVersion, toVersion string) *converter {
+	for _, c := range converters {
+		if c.fromVersion == fromVersion {
+			for _, v := range c.toVersions {
+				if v == toVersion {
+					return c
+				}
+			}
+		}
+	}
+	return nil
+}
+
+// Convert converts a CNI Result to the requested CNI specification version,
+// or returns an error if the conversion could not be performed or failed
+func Convert(from types.Result, toVersion string) (types.Result, error) {
+	if toVersion == "" {
+		toVersion = "0.1.0"
+	}
+
+	fromVersion := from.Version()
+
+	// Shortcut for same version
+	if fromVersion == toVersion {
+		return from, nil
+	}
+
+	// Otherwise find the right converter
+	c := findConverter(fromVersion, toVersion)
+	if c == nil {
+		return nil, fmt.Errorf("no converter for CNI result version %s to %s",
+			fromVersion, toVersion)
+	}
+	return c.convertFn(from, toVersion)
+}
+
+// RegisterConverter registers a CNI Result converter. SHOULD NOT BE CALLED
+// EXCEPT FROM CNI ITSELF.
+func RegisterConverter(fromVersion string, toVersions []string, convertFn ConvertFn) {
+	// Make sure there is no converter already registered for these
+	// from and to versions
+	for _, v := range toVersions {
+		if findConverter(fromVersion, v) != nil {
+			panic(fmt.Sprintf("converter already registered for %s to %s",
+				fromVersion, v))
+		}
+	}
+	converters = append(converters, &converter{
+		fromVersion: fromVersion,
+		toVersions:  toVersions,
+		convertFn:   convertFn,
+	})
+}

pkg/types/internal/create.go

@@ -0,0 +1,66 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package convert
+
+import (
+	"fmt"
+
+	"github.com/containernetworking/cni/pkg/types"
+)
+
+type ResultFactoryFunc func([]byte) (types.Result, error)
+
+type creator struct {
+	// CNI Result spec versions that createFn can create a Result for
+	versions []string
+	createFn ResultFactoryFunc
+}
+
+var creators []*creator
+
+func findCreator(version string) *creator {
+	for _, c := range creators {
+		for _, v := range c.versions {
+			if v == version {
+				return c
+			}
+		}
+	}
+	return nil
+}
+
+// Create creates a CNI Result using the given JSON, or an error if the creation
+// could not be performed
+func Create(version string, bytes []byte) (types.Result, error) {
+	if c := findCreator(version); c != nil {
+		return c.createFn(bytes)
+	}
+	return nil, fmt.Errorf("unsupported CNI result version %q", version)
+}
+
+// RegisterCreator registers a CNI Result creator. SHOULD NOT BE CALLED
+// EXCEPT FROM CNI ITSELF.
+func RegisterCreator(versions []string, createFn ResultFactoryFunc) {
+	// Make sure there is no creator already registered for these versions
+	for _, v := range versions {
+		if findCreator(v) != nil {
+			panic(fmt.Sprintf("creator already registered for %s", v))
+		}
+	}
+	creators = append(creators, &creator{
+		versions: versions,
+		createFn: createFn,
+	})
+}

pkg/types/types.go

@@ -17,6 +17,7 @@ package types
 import (
 	"encoding/json"
 	"fmt"
+	"io"
 	"net"
 	"os"
 )
@@ -55,46 +56,97 @@ func (n *IPNet) UnmarshalJSON(data []byte) error {
 	return nil
 }
 
-// NetConf describes a network.
-type NetConf struct {
-	Name string `json:"name,omitempty"`
+// Use PluginConf instead of NetConf, the NetConf
+// backwards-compat alias will be removed in a future release.
+type NetConf = PluginConf
+
+// PluginConf describes a plugin configuration for a specific network.
+type PluginConf struct {
+	CNIVersion string `json:"cniVersion,omitempty"`
+
+	Name         string          `json:"name,omitempty"`
+	Type         string          `json:"type,omitempty"`
+	Capabilities map[string]bool `json:"capabilities,omitempty"`
+	IPAM         IPAM            `json:"ipam,omitempty"`
+	DNS          DNS             `json:"dns,omitempty"`
+
+	RawPrevResult map[string]interface{} `json:"prevResult,omitempty"`
+	PrevResult    Result                 `json:"-"`
+
+	// ValidAttachments is only supplied when executing a GC operation
+	ValidAttachments []GCAttachment `json:"cni.dev/valid-attachments,omitempty"`
+}
+
+// GCAttachment is the parameters to a GC call -- namely,
+// the container ID and ifname pair that represents a
+// still-valid attachment.
+type GCAttachment struct {
+	ContainerID string `json:"containerID"`
+	IfName      string `json:"ifname"`
+}
+
+// Note: DNS should be omit if DNS is empty but default Marshal function
+// will output empty structure hence need to write a Marshal function
+func (n *PluginConf) MarshalJSON() ([]byte, error) {
+	bytes, err := json.Marshal(*n)
+	if err != nil {
+		return nil, err
+	}
+
+	fixupObj := make(map[string]interface{})
+	if err := json.Unmarshal(bytes, &fixupObj); err != nil {
+		return nil, err
+	}
+
+	if n.DNS.IsEmpty() {
+		delete(fixupObj, "dns")
+	}
+
+	return json.Marshal(fixupObj)
+}
+
+type IPAM struct {
 	Type string `json:"type,omitempty"`
-	IPAM struct {
-		Type string `json:"type,omitempty"`
-	} `json:"ipam,omitempty"`
-	DNS DNS `json:"dns"`
 }
 
-// Result is what gets returned from the plugin (via stdout) to the caller
-type Result struct {
-	IP4 *IPConfig `json:"ip4,omitempty"`
-	IP6 *IPConfig `json:"ip6,omitempty"`
-	DNS DNS       `json:"dns,omitempty"`
+// IsEmpty returns true if IPAM structure has no value, otherwise return false
+func (i *IPAM) IsEmpty() bool {
+	return i.Type == ""
 }
 
-func (r *Result) Print() error {
-	return prettyPrint(r)
+// NetConfList describes an ordered list of networks.
+type NetConfList struct {
+	CNIVersion string `json:"cniVersion,omitempty"`
+
+	Name         string        `json:"name,omitempty"`
+	DisableCheck bool          `json:"disableCheck,omitempty"`
+	DisableGC    bool          `json:"disableGC,omitempty"`
+	Plugins      []*PluginConf `json:"plugins,omitempty"`
 }
 
-// String returns a formatted string in the form of "[IP4: $1,][ IP6: $2,] DNS: $3" where
-// $1 represents the receiver's IPv4, $2 represents the receiver's IPv6 and $3 the
-// receiver's DNS. If $1 or $2 are nil, they won't be present in the returned string.
-func (r *Result) String() string {
-	var str string
-	if r.IP4 != nil {
-		str = fmt.Sprintf("IP4:%+v, ", *r.IP4)
+// Result is an interface that provides the result of plugin execution
+type Result interface {
+	// The highest CNI specification result version the result supports
+	// without having to convert
+	Version() string
+
+	// Returns the result converted into the requested CNI specification
+	// result version, or an error if conversion failed
+	GetAsVersion(version string) (Result, error)
+
+	// Prints the result in JSON format to stdout
+	Print() error
+
+	// Prints the result in JSON format to provided writer
+	PrintTo(writer io.Writer) error
+}
+
+func PrintResult(result Result, version string) error {
+	newResult, err := result.GetAsVersion(version)
+	if err != nil {
+		return err
 	}
-	if r.IP6 != nil {
-		str += fmt.Sprintf("IP6:%+v, ", *r.IP6)
-	}
-	return fmt.Sprintf("%sDNS:%+v", str, r.DNS)
-}
-
-// IPConfig contains values necessary to configure an interface
-type IPConfig struct {
-	IP      net.IPNet
-	Gateway net.IP
-	Routes  []Route
+	return newResult.Print()
 }
 
 // DNS contains values interesting for DNS resolvers
@@ -105,19 +157,115 @@ type DNS struct {
 	Options     []string `json:"options,omitempty"`
 }
 
-type Route struct {
-	Dst net.IPNet
-	GW  net.IP
+// IsEmpty returns true if DNS structure has no value, otherwise return false
+func (d *DNS) IsEmpty() bool {
+	if len(d.Nameservers) == 0 && d.Domain == "" && len(d.Search) == 0 && len(d.Options) == 0 {
+		return true
+	}
+	return false
 }
 
+func (d *DNS) Copy() *DNS {
+	if d == nil {
+		return nil
+	}
+
+	to := &DNS{Domain: d.Domain}
+	to.Nameservers = append(to.Nameservers, d.Nameservers...)
+	to.Search = append(to.Search, d.Search...)
+	to.Options = append(to.Options, d.Options...)
+	return to
+}
+
+type Route struct {
+	Dst      net.IPNet
+	GW       net.IP
+	MTU      int
+	AdvMSS   int
+	Priority int
+	Table    *int
+	Scope    *int
+}
+
+func (r *Route) String() string {
+	table := "<nil>"
+	if r.Table != nil {
+		table = fmt.Sprintf("%d", *r.Table)
+	}
+
+	scope := "<nil>"
+	if r.Scope != nil {
+		scope = fmt.Sprintf("%d", *r.Scope)
+	}
+
+	return fmt.Sprintf("{Dst:%+v GW:%v MTU:%d AdvMSS:%d Priority:%d Table:%s Scope:%s}", r.Dst, r.GW, r.MTU, r.AdvMSS, r.Priority, table, scope)
+}
+
+func (r *Route) Copy() *Route {
+	if r == nil {
+		return nil
+	}
+
+	route := &Route{
+		Dst:      r.Dst,
+		GW:       r.GW,
+		MTU:      r.MTU,
+		AdvMSS:   r.AdvMSS,
+		Priority: r.Priority,
+		Scope:    r.Scope,
+	}
+
+	if r.Table != nil {
+		table := *r.Table
+		route.Table = &table
+	}
+
+	if r.Scope != nil {
+		scope := *r.Scope
+		route.Scope = &scope
+	}
+
+	return route
+}
+
+// Well known error codes
+// see https://github.com/containernetworking/cni/blob/main/SPEC.md#error
+const (
+	ErrUnknown                     uint = iota // 0
+	ErrIncompatibleCNIVersion                  // 1
+	ErrUnsupportedField                        // 2
+	ErrUnknownContainer                        // 3
+	ErrInvalidEnvironmentVariables             // 4
+	ErrIOFailure                               // 5
+	ErrDecodingFailure                         // 6
+	ErrInvalidNetworkConfig                    // 7
+	ErrInvalidNetNS                            // 8
+	ErrTryAgainLater               uint = 11
+	ErrPluginNotAvailable          uint = 50
+	ErrLimitedConnectivity         uint = 51
+	ErrInternal                    uint = 999
+)
+
 type Error struct {
 	Code    uint   `json:"code"`
 	Msg     string `json:"msg"`
 	Details string `json:"details,omitempty"`
 }
 
+func NewError(code uint, msg, details string) *Error {
+	return &Error{
+		Code:    code,
+		Msg:     msg,
+		Details: details,
+	}
+}
+
 func (e *Error) Error() string {
-	return e.Msg
+	details := ""
+	if e.Details != "" {
+		details = fmt.Sprintf("; %v", e.Details)
+	}
+	return fmt.Sprintf("%v%v", e.Msg, details)
 }
 
 func (e *Error) Print() error {
@@ -128,37 +276,14 @@ func (e *Error) Print() error {
 // for our custom IPNet type
 
 // JSON (un)marshallable types
-type ipConfig struct {
-	IP      IPNet   `json:"ip"`
-	Gateway net.IP  `json:"gateway,omitempty"`
-	Routes  []Route `json:"routes,omitempty"`
-}
-
 type route struct {
-	Dst IPNet  `json:"dst"`
-	GW  net.IP `json:"gw,omitempty"`
-}
-
-func (c *IPConfig) MarshalJSON() ([]byte, error) {
-	ipc := ipConfig{
-		IP:      IPNet(c.IP),
-		Gateway: c.Gateway,
-		Routes:  c.Routes,
-	}
-
-	return json.Marshal(ipc)
-}
-
-func (c *IPConfig) UnmarshalJSON(data []byte) error {
-	ipc := ipConfig{}
-	if err := json.Unmarshal(data, &ipc); err != nil {
-		return err
-	}
-
-	c.IP = net.IPNet(ipc.IP)
-	c.Gateway = ipc.Gateway
-	c.Routes = ipc.Routes
-	return nil
+	Dst      IPNet  `json:"dst"`
+	GW       net.IP `json:"gw,omitempty"`
+	MTU      int    `json:"mtu,omitempty"`
+	AdvMSS   int    `json:"advmss,omitempty"`
+	Priority int    `json:"priority,omitempty"`
+	Table    *int   `json:"table,omitempty"`
+	Scope    *int   `json:"scope,omitempty"`
 }
 
 func (r *Route) UnmarshalJSON(data []byte) error {
@@ -169,13 +294,24 @@ func (r *Route) UnmarshalJSON(data []byte) error {
 
 	r.Dst = net.IPNet(rt.Dst)
 	r.GW = rt.GW
+	r.MTU = rt.MTU
+	r.AdvMSS = rt.AdvMSS
+	r.Priority = rt.Priority
+	r.Table = rt.Table
+	r.Scope = rt.Scope
+
 	return nil
 }
 
-func (r *Route) MarshalJSON() ([]byte, error) {
+func (r Route) MarshalJSON() ([]byte, error) {
 	rt := route{
-		Dst: IPNet(r.Dst),
-		GW:  r.GW,
+		Dst:      IPNet(r.Dst),
+		GW:       r.GW,
+		MTU:      r.MTU,
+		AdvMSS:   r.AdvMSS,
+		Priority: r.Priority,
+		Table:    r.Table,
+		Scope:    r.Scope,
 	}
 
 	return json.Marshal(rt)

pkg/types/types_suite_test.go

@@ -15,10 +15,10 @@
 package types_test
 
 import (
-	. "github.com/onsi/ginkgo"
-	. "github.com/onsi/gomega"
-
 	"testing"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
 )
 
 func TestTypes(t *testing.T) {

pkg/types/types_test.go

@@ -0,0 +1,201 @@
+// Copyright 2017 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package types_test
+
+import (
+	"encoding/json"
+	"net"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	"github.com/containernetworking/cni/pkg/types"
+	types040 "github.com/containernetworking/cni/pkg/types/040"
+	current "github.com/containernetworking/cni/pkg/types/100"
+)
+
+var _ = Describe("Types", func() {
+	Describe("ParseCIDR", func() {
+		DescribeTable("Parse and stringify",
+			func(input, expectedIP string, expectedMask int) {
+				ipn, err := types.ParseCIDR(input)
+				Expect(err).NotTo(HaveOccurred())
+				Expect(ipn.String()).To(Equal(input))
+
+				Expect(ipn.IP.String()).To(Equal(expectedIP))
+				ones, _ := ipn.Mask.Size()
+				Expect(ones).To(Equal(expectedMask))
+			},
+			Entry("ipv4", "1.2.3.4/24", "1.2.3.4", 24),
+			Entry("ipv6", "2001:db8::/32", "2001:db8::", 32),
+		)
+		It("returns an error when given invalid inputs", func() {
+			ipn, err := types.ParseCIDR("1.2.3/45")
+			Expect(ipn).To(BeNil())
+			Expect(err).To(MatchError("invalid CIDR address: 1.2.3/45"))
+		})
+	})
+
+	Describe("custom IPNet type", func() {
+		It("marshals and unmarshals to JSON as a string", func() {
+			ipn := types.IPNet{
+				IP:   net.ParseIP("1.2.3.4"),
+				Mask: net.CIDRMask(24, 32),
+			}
+			jsonBytes, err := json.Marshal(ipn)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(jsonBytes).To(MatchJSON(`"1.2.3.4/24"`))
+
+			var unmarshaled types.IPNet
+			Expect(json.Unmarshal(jsonBytes, &unmarshaled)).To(Succeed())
+			Expect(unmarshaled).To(Equal(ipn))
+		})
+
+		Context("when the json data is not syntactically valid", func() {
+			Specify("UnmarshalJSON returns an error", func() {
+				ipn := new(types.IPNet)
+				err := ipn.UnmarshalJSON([]byte("1"))
+				Expect(err).To(MatchError("json: cannot unmarshal number into Go value of type string"))
+			})
+		})
+
+		Context("when the json data is not semantically valid", func() {
+			Specify("UnmarshalJSON returns an error", func() {
+				ipn := new(types.IPNet)
+				err := ipn.UnmarshalJSON([]byte(`"1.2.3.4/99"`))
+				Expect(err).To(MatchError("invalid CIDR address: 1.2.3.4/99"))
+			})
+		})
+	})
+
+	Describe("custom Route type", func() {
+		var example types.Route
+		BeforeEach(func() {
+			example = types.Route{
+				Dst: net.IPNet{
+					IP:   net.ParseIP("1.2.3.0"),
+					Mask: net.CIDRMask(24, 32),
+				},
+				GW:       net.ParseIP("1.2.3.1"),
+				MTU:      1500,
+				AdvMSS:   1340,
+				Priority: 100,
+				Table:    types040.Int(50),
+				Scope:    types040.Int(253),
+			}
+		})
+
+		It("marshals and unmarshals to JSON", func() {
+			jsonBytes, err := json.Marshal(example)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(jsonBytes).To(MatchJSON(`{ "dst": "1.2.3.0/24", "gw": "1.2.3.1", "mtu": 1500, "advmss": 1340, "priority": 100, "table": 50, "scope": 253 }`))
+
+			var unmarshaled types.Route
+			Expect(json.Unmarshal(jsonBytes, &unmarshaled)).To(Succeed())
+			Expect(unmarshaled).To(Equal(example))
+		})
+
+		Context("when the json data is not valid", func() {
+			Specify("UnmarshalJSON returns an error", func() {
+				route := new(types.Route)
+				err := route.UnmarshalJSON([]byte(`{ "dst": "1.2.3.0/24", "gw": "1.2.3.x" }`))
+				Expect(err).To(MatchError("invalid IP address: 1.2.3.x"))
+			})
+		})
+
+		It("formats as a string with a hex mask", func() {
+			Expect(example.String()).To(Equal(`{Dst:{IP:1.2.3.0 Mask:ffffff00} GW:1.2.3.1 MTU:1500 AdvMSS:1340 Priority:100 Table:50 Scope:253}`))
+		})
+	})
+
+	Describe("Error type", func() {
+		var example *types.Error
+		BeforeEach(func() {
+			example = &types.Error{
+				Code:    1234,
+				Msg:     "some message",
+				Details: "some details",
+			}
+		})
+
+		Describe("Error() method (basic string)", func() {
+			It("returns a formatted string", func() {
+				Expect(example.Error()).To(Equal("some message; some details"))
+			})
+			Context("when details are not present", func() {
+				BeforeEach(func() {
+					example.Details = ""
+				})
+				It("returns only the message", func() {
+					Expect(example.Error()).To(Equal("some message"))
+				})
+			})
+		})
+
+		It("NewError method", func() {
+			err := types.NewError(1234, "some message", "some details")
+			Expect(err).To(Equal(example))
+		})
+	})
+
+	Describe("Result conversion", func() {
+		var result *current.Result
+		BeforeEach(func() {
+			ipv4, err := types.ParseCIDR("1.2.3.30/24")
+			Expect(err).NotTo(HaveOccurred())
+			Expect(ipv4).NotTo(BeNil())
+
+			ipv6, err := types.ParseCIDR("abcd:1234:ffff::cdde/64")
+			Expect(err).NotTo(HaveOccurred())
+			Expect(ipv6).NotTo(BeNil())
+			result = &current.Result{
+				CNIVersion: "1.0.0",
+				Interfaces: []*current.Interface{
+					{
+						Name:       "eth0",
+						Mac:        "00:11:22:33:44:55",
+						Sandbox:    "/proc/3553/ns/net",
+						PciID:      "8086:9a01",
+						SocketPath: "/path/to/vhost/fd",
+					},
+				},
+				IPs: []*current.IPConfig{
+					{
+						Interface: current.Int(0),
+						Address:   *ipv4,
+						Gateway:   net.ParseIP("1.2.3.1"),
+					},
+					{
+						Interface: current.Int(0),
+						Address:   *ipv6,
+						Gateway:   net.ParseIP("abcd:1234:ffff::1"),
+					},
+				},
+				DNS: types.DNS{
+					Nameservers: []string{"1.2.3.4", "1::cafe"},
+					Domain:      "acompany.com",
+					Search:      []string{"somedomain.com", "otherdomain.net"},
+					Options:     []string{"foo", "bar"},
+				},
+			}
+		})
+
+		It("can create a CNIVersion '' (0.1.0) result", func() {
+			newResult, err := result.GetAsVersion("")
+			Expect(err).NotTo(HaveOccurred())
+			Expect(newResult.Version()).To(Equal("0.1.0"))
+		})
+	})
+})

pkg/utils/sysctl/sysctl_linux.go

@@ -1,58 +0,0 @@
-// Copyright 2016 CNI authors
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-// build +linux
-
-package sysctl
-
-import (
-	"fmt"
-	"io/ioutil"
-	"path/filepath"
-	"strings"
-)
-
-// Sysctl provides a method to set/get values from /proc/sys - in linux systems
-// new interface to set/get values of variables formerly handled by sysctl syscall
-// If optional `params` have only one string value - this function will
-// set this value into coresponding sysctl variable
-func Sysctl(name string, params ...string) (string, error) {
-	if len(params) > 1 {
-		return "", fmt.Errorf("unexcepted additional parameters")
-	} else if len(params) == 1 {
-		return setSysctl(name, params[0])
-	}
-	return getSysctl(name)
-}
-
-func getSysctl(name string) (string, error) {
-	fullName := filepath.Join("/proc/sys", strings.Replace(name, ".", "/", -1))
-	fullName = filepath.Clean(fullName)
-	data, err := ioutil.ReadFile(fullName)
-	if err != nil {
-		return "", err
-	}
-
-	return string(data[:len(data)-1]), nil
-}
-
-func setSysctl(name, value string) (string, error) {
-	fullName := filepath.Join("/proc/sys", strings.Replace(name, ".", "/", -1))
-	fullName = filepath.Clean(fullName)
-	if err := ioutil.WriteFile(fullName, []byte(value), 0644); err != nil {
-		return "", err
-	}
-
-	return getSysctl(name)
-}