Merge pull request #3 from iolave/staging

More lxc features

Author: iolave

.gitignore

@@ -6,3 +6,5 @@ bin
 cover*
 site/
 docs/go-client/pkg/*
+docs/**/swag*
+docs/**/docs.go

CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [unreleased]
 
+## [v0.6.0]
+### PVE API wrapper
+#### Added
+- `GET /custom-api/v1/lxc/{id}/ip` endpoint.
+- `POST /custom-api/v1/lxc/{id}/exec` endpoint.
+
+#### Fixed
+- pve api wrapper host option is now `--host`.
+- pve api wrapper port option is now `--port`.
+
+### PVE API client
+#### Added
+- `GET /access/permissions` implementation as `PVE.Access.GetPermissions`.
+- `GET /cluster/resources` implementation as `PVE.Cluster.GetVMIDs`, `PVE.Cluster.GetRandomVMID` and `PVE.Cluster.IsVMIDAvailable`.
+- `GET /nodes/{node}/firewall/rules` implementation as `PVE.Node.Firewall.GetRule`.
+- `POST /nodes/{node}/firewall/rules` implementation as `PVE.Node.Firewall.NewRule`.
+- `DELETE /nodes/{node}/firewall/rules/{pos}` implementation as `PVE.Node.Firewall.DeleteRule` and `PVE.Node.Firewall.DeleteRuleByPos`.
+- `GET /nodes/{node}/lxc/{id}/interfaces` implementation as `PVE.LXC.GetInterfaces` and `PVE.LXC.GetInterface` .
+- `GET /nodes/{node}/lxc/{id}/status/current` implementation as `PVE.LXC.GetStatus`.
+- `POST /nodes/{node}/lxc/{id}/status/reboot` implementation as `PVE.LXC.Reboot`.
+- `POST /nodes/{node}/lxc/{id}/status/resume` implementation as `PVE.LXC.Resume`.
+- `POST /nodes/{node}/lxc/{id}/status/shutdown` implementation as `PVE.LXC.Shutdown`.
+- `POST /nodes/{node}/lxc/{id}/status/start` implementation as `PVE.LXC.Start`.
+- `POST /nodes/{node}/lxc/{id}/status/stop` implementation as `PVE.LXC.Stop`.
+- `POST /custom-api/v1/lxc/{id}/exec` implementation as `PVE.LXC.Exec`.
+
+#### Fixed
+- `PVE.LXC.Create` hostname assignment.
+- `PVE.LXC.Create` net assignment.
+- `PVE.LXC.Create` multiple networks support.
+
+#### Changed
+- `PVE.LXC.Create` request's `Features` property is now a struct.
+
 ## [v0.5.0]
 ### PVE API wrapper
 #### Added
@@ -83,7 +117,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Proxmox api token credentials support.
 - Proxmox api version endpoint.
 
-[unreleased]: https://github.com/iolave/go-proxmox/compare/v0.5.0...HEAD
+[unreleased]: https://github.com/iolave/go-proxmox/compare/v0.6.0...staging
+[v0.6.0]: https://github.com/iolave/go-proxmox/releases/tag/v0.6.0
+[v0.5.1]: https://github.com/iolave/go-proxmox/releases/tag/v0.5.1
 [v0.5.0]: https://github.com/iolave/go-proxmox/releases/tag/v0.5.0
 [v0.4.0]: https://github.com/iolave/go-proxmox/releases/tag/v0.4.0
 [v0.3.0]: https://github.com/iolave/go-proxmox/releases/tag/v0.3.0

Makefile

@@ -8,6 +8,10 @@ install-go-test-coverage:
 install-docs-dependencies:
 ./scripts/install-docs-deps.sh
 
+install-dependencies: install-docs-dependencies
+go mod tidy
+
+
 .PHONY: coverage-check
 coverage-check: install-go-test-coverage
 go test -v ./... -coverprofile=./cover.out -covermode=atomic -coverpkg=./...
@@ -22,17 +26,12 @@ coverage:
  ; exit $$rc
 
 generate-docs: install-docs-dependencies
-source /tmp/venv/go-proxmox/bin/activate; \
-rm -rf ./docs/go-client/pkg; \
-mkdir -p ./docs/go-client/pkg/; \
-go run ./cmd/gomarkdoc/main.go; \
-mkdocs build
+bash ./scripts/generate-docs.sh
 
-preview-docs: install-docs-dependencies
-source /tmp/venv/go-proxmox/bin/activate; \
-mkdocs serve
+preview-docs: install-docs-dependencies generate-docs
+bash ./scripts/preview-docs.sh
 
-build:
+build: install-dependencies
 $(eval $@GOOS = linux)
 $(eval $@GOARCH = amd64)
 GOOS=$($@GOOS) GOARCH=$($@GOARCH) go build -o "bin/pve-api-wrapper-$($@GOOS)-$($@GOARCH)" ./cmd/pve_api_wrapper/pve_api_wrapper.go

README.md

@@ -1,5 +1,4 @@
-# GO Proxmox
-Proxmox CLI for remote management and go api client
+# go-proxmox
 
 > [!WARNING]
 > All versions released prior to `v1.0.0` are to be considered [breaking changes](https://semver.org/#how-do-i-know-when-to-release-100)

cmd/pve_api_wrapper/pve_api_wrapper.go

@@ -6,9 +6,23 @@ import (
 "os"
 
 "github.com/alexflint/go-arg"
+_ "github.com/iolave/go-proxmox/docs/api-wrapper"
 "github.com/iolave/go-proxmox/internal/server"
 )
 
+// @title	Proxmox API Wrapper
+// @version	1.0
+// @description	Proxmox api wrapper that provides custom features.
+//
+// @contact.name	Ignacio Olave
+// @contact.url	http://www.github.com/iolave/go-proxmox/issues
+// @contact.email	contact@iolave.com
+// @license.name	Apache 2.0
+// @license.url	http://www.apache.org/licenses/LICENSE-2.0.html
+// @host	localhost:8443
+// @BasePath	/custom-api/v1
+// @externalDocs.description	go-promox docs
+// @externalDocs.url	https://go-proxmox.iolave.com
 func main() {
 var app server.App
 

docs/api-wrapper.md renamed to docs/api-wrapper/index.md

@@ -1,17 +1,19 @@
-The pve api wrapper is an http server ment to be installed on the proxmox host server () that wraps the proxmox api and adds missing features to it.
+The pve api wrapper is an http server ment to be installed on the proxmox host server that wraps the proxmox api and adds missing features to it.
 
-_pve-api-wrapper can definitely be installed somewhere else but some functionalities might not work._
+
+> [!NOTE]
+> pve-api-wrapper can definitely be installed somewhere else by pointing to the corresponding pve host & port, but some functionalities might not work.
 
 ## Features
 - Proper error responses on failed requests,
-- lxc exec command endpoint (not available yet).
+- custom endpoints (for a full list see the [reference])
 
 ## Installation
 ### Latest release
 The installation script installs the `pve-api-wrapper` binary into `/usr/local/bin`.
 
 ```bash
-curl https://raw.githubusercontent.com/iolave/go-proxmox/refs/heads/master/scripts/install.sh | bash
+curl https://raw.githubusercontent.com/iolave/go-proxmox/refs/tags/latest/scripts/install.sh | bash
 ```
 
 _Inspect the installation script code [here]._
@@ -29,7 +31,7 @@ make build
 
 ## Usage
 ```bash
-pve-api-wrapper [--version] [--pve-host PVE-HOST] [--pve-port PVE-PORT] [--pve-host PVE-HOST] [--pve-port PVE-PORT] [--crt CRT] [--key KEY]
+pve-api-wrapper [--version] [--pve-host PVE-HOST] [--pve-port PVE-PORT] [--host HOST] [--port PORT] [--crt CRT] [--key KEY]
 ```
 ### Options
 - `--version` displays the program version.
@@ -40,7 +42,8 @@ pve-api-wrapper [--version] [--pve-host PVE-HOST] [--pve-port PVE-PORT] [--pve-h
 - `--crt` api wrapper tls crt path (default:`/etc/pve/local/pve-ssl.pem`).
 - `--key` api wrapper tls key path (default:`/etc/pve/local/pve-ssl.key`).
 
-[here]: https://github.com/iolave/go-proxmox/blob/master/scripts/install.sh
+[here]: https://github.com/iolave/go-proxmox/blob/latest/scripts/install.sh
+[reference]: https://go-proxmox.iolave.com/api-wrapper/reference/
 <!--
  TODO: host the shell script within the docs https://github.com/squidfunk/mkdocs-material/discussions/3458
 -->

docs/api-wrapper/reference.md

@@ -0,0 +1,2 @@
+# Reference
+!!swagger swagger.json!!

docs/go-client/implemented-endpoints.md

@@ -16,7 +16,7 @@ This is a development-purposed list to keep track of the implemented proxmox [en
 |-------------------------------------------------------------|:------------------:|:--------------:|:-----:|:-:|
 | `/access/acl` |:material-close:||:material-close:|
 | `/access/password` |||:material-close:|
-| `/access/permissions` |:material-close:|
+| `/access/permissions` |:material-check-all:|
 | `/access/ticket` |:material-close:|:material-close:|
 
 ### Users
@@ -69,7 +69,7 @@ This is a development-purposed list to keep track of the implemented proxmox [en
 | `/cluster/log` |:material-close:|
 | `/cluster/nextid` |:material-check-all:|
 | `/cluster/options` |:material-close:||:material-close:|
-| `/cluster/resources` |:material-close:|
+| `/cluster/resources` |:material-check:|
 | `/cluster/status` |:material-close:|
 | `/cluster/tasks` |:material-close:|
 
@@ -340,8 +340,8 @@ This is a development-purposed list to keep track of the implemented proxmox [en
 | Path | GET | POST | PUT | DELETE |
 |-------------------------------------------------------------|:------------------:|:--------------:|:-----:|:-:|
 | `/nodes/:node/firewall` |:material-close:|
-| `/nodes/:node/firewall/rules` |:material-check-all:|:material-close:|
-| `/nodes/:node/firewall/rules/:pos` |:material-check-all:||:material-close:|:material-close:|
+| `/nodes/:node/firewall/rules` |:material-check-all:|:material-check-all:|
+| `/nodes/:node/firewall/rules/:pos` |:material-check-all:||:material-close:|:material-check:|
 | `/nodes/:node/firewall/log` |:material-check:|
 | `/nodes/:node/firewall/options` |:material-close:||:material-close:|
 
@@ -374,17 +374,17 @@ This is a development-purposed list to keep track of the implemented proxmox [en
 | `/nodes/:node/lxc/:vmid/snapshot/:name/config` |:material-close:||:material-close:|
 | `/nodes/:node/lxc/:vmid/snapshot/:name/rollback` ||:material-close:|
 | `/nodes/:node/lxc/:vmid/status` |:material-close:|
-| `/nodes/:node/lxc/:vmid/status/current` |:material-close:|
-| `/nodes/:node/lxc/:vmid/status/reboot` ||:material-close:|
-| `/nodes/:node/lxc/:vmid/status/resume` ||:material-close:|
-| `/nodes/:node/lxc/:vmid/status/shutdown`  ||:material-close:|
-| `/nodes/:node/lxc/:vmid/status/start` ||:material-close:|
-| `/nodes/:node/lxc/:vmid/status/stop`  ||:material-close:|
-| `/nodes/:node/lxc/:vmid/status/suspend` ||:material-close:|
+| `/nodes/:node/lxc/:vmid/status/current` |:material-check-all:|
+| `/nodes/:node/lxc/:vmid/status/reboot` ||:material-check-all:|
+| `/nodes/:node/lxc/:vmid/status/resume` ||:material-check-all:|
+| `/nodes/:check-all/lxc/:vmid/status/shutdown` ||:material-check-all:|
+| `/nodes/:node/lxc/:vmid/status/start` ||:material-check-all:|
+| `/nodes/:check-all/lxc/:vmid/status/stop` ||:material-check-all:|
+| `/nodes/:node/lxc/:vmid/status/suspend` ||:material-check-all:|
 | `/nodes/:node/lxc/:vmid/clone` ||:material-close:|
 | `/nodes/:node/lxc/:vmid/config` |:material-close:||:material-close:|
 | `/nodes/:node/lxc/:vmid/feature` |:material-close:|
-| `/nodes/:node/lxc/:vmid/interfaces` |:material-close:|
+| `/nodes/:node/lxc/:vmid/interfaces` |:material-check-all:|
 | `/nodes/:node/lxc/:vmid/migrate` ||:material-close:|
 | `/nodes/:node/lxc/:vmid/move_volume` ||:material-close:|
 | `/nodes/:node/lxc/:vmid/mtunnel` ||:material-close:|

go.mod

@@ -4,24 +4,37 @@ go 1.22.2
 
 require (
 github.com/alexflint/go-arg v1.5.1
+github.com/ggicci/httpin v0.19.0
+github.com/google/uuid v1.6.0
 github.com/princjef/gomarkdoc v1.1.0
+github.com/swaggo/swag v1.16.4
 )
 
 require (
+github.com/KyleBanks/depth v1.2.1 // indirect
 github.com/Microsoft/go-winio v0.5.0 // indirect
+github.com/PuerkitoBio/purell v1.1.1 // indirect
+github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578 // indirect
 github.com/VividCortex/ewma v1.2.0 // indirect
 github.com/alexflint/go-scalar v1.2.0 // indirect
 github.com/cheggaaa/pb/v3 v3.0.8 // indirect
 github.com/emirpasic/gods v1.12.0 // indirect
 github.com/fatih/color v1.11.0 // indirect
+github.com/ggicci/owl v0.8.2 // indirect
 github.com/go-git/gcfg v1.5.0 // indirect
 github.com/go-git/go-billy/v5 v5.3.1 // indirect
 github.com/go-git/go-git/v5 v5.3.0 // indirect
+github.com/go-openapi/jsonpointer v0.19.5 // indirect
+github.com/go-openapi/jsonreference v0.19.6 // indirect
+github.com/go-openapi/spec v0.20.4 // indirect
+github.com/go-openapi/swag v0.19.15 // indirect
 github.com/imdario/mergo v0.3.12 // indirect
 github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99 // indirect
+github.com/josharian/intern v1.0.0 // indirect
 github.com/kevinburke/ssh_config v1.1.0 // indirect
-github.com/mattn/go-colorable v0.1.8 // indirect
-github.com/mattn/go-isatty v0.0.12 // indirect
+github.com/mailru/easyjson v0.7.6 // indirect
+github.com/mattn/go-colorable v0.1.13 // indirect
+github.com/mattn/go-isatty v0.0.20 // indirect
 github.com/mattn/go-runewidth v0.0.12 // indirect
 github.com/mgutz/ansi v0.0.0-20200706080929-d51e80ef957d // indirect
 github.com/mitchellh/go-homedir v1.1.0 // indirect
@@ -33,11 +46,14 @@ require (
 github.com/sirupsen/logrus v1.8.1 // indirect
 github.com/x-cray/logrus-prefixed-formatter v0.5.2 // indirect
 github.com/xanzy/ssh-agent v0.3.0 // indirect
-golang.org/x/crypto v0.0.0-20210513164829-c07d793c2f9a // indirect
-golang.org/x/net v0.0.0-20210520170846-37e1c6afe023 // indirect
-golang.org/x/sys v0.0.0-20220908164124-27713097b956 // indirect
-golang.org/x/term v0.0.0-20210503060354-a79de5458b56 // indirect
+golang.org/x/crypto v0.22.0 // indirect
+golang.org/x/net v0.24.0 // indirect
+golang.org/x/sys v0.19.0 // indirect
+golang.org/x/term v0.19.0 // indirect
+golang.org/x/text v0.14.0 // indirect
+golang.org/x/tools v0.7.0 // indirect
 golang.org/x/xerrors v0.0.0-20240903120638-7835f813f4da // indirect
 gopkg.in/warnings.v0 v0.1.2 // indirect
+gopkg.in/yaml.v2 v2.4.0 // indirect
 mvdan.cc/xurls/v2 v2.2.0 // indirect
 )