diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 2cac7a9..b494d3c 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -30,10 +30,8 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - - name: Install docs dependencies - run: make install-docs-dependencies - name: Generate docs - run: make generate-docs + run: make docs - name: Setup Pages id: pages uses: actions/configure-pages@v5 diff --git a/.testcoverage.yml b/.testcoverage.yml deleted file mode 100644 index 015bdd9..0000000 --- a/.testcoverage.yml +++ /dev/null @@ -1,50 +0,0 @@ -# (mandatory) -# Path to coverprofile file (output of `go test -coverprofile` command). -# -# For cases where there are many coverage profiles, such as when running -# unit tests and integration tests separately, you can combine all those -# profiles into one. In this case, the profile should have a comma-separated list -# of profile files, e.g., 'cover_unit.out,cover_integration.out'. -profile: cover.out - -# (optional; but recommended to set) -# When specified reported file paths will not contain local prefix in the output -#local-prefix: "github.com/org/project" - -# Holds coverage thresholds percentages, values should be in range [0-100] -threshold: - # (optional; default 0) - # The minimum coverage that each file should have - #file: 70 - - # (optional; default 0) - # The minimum coverage that each package should have - #package: 80 - - # (optional; default 0) - # The minimum total coverage project should have - total: 85 - -# Holds regexp rules which will override thresholds for matched files or packages -# using their paths. -# -# First rule from this list that matches file or package is going to apply -# new threshold to it. If project has multiple rules that match same path, -# override rules should be listed in order from specific to more general rules. -#override: - # Increase coverage threshold to 100% for `foo` package - # (default is 80, as configured above in this example) -#- threshold: 100 -# path: ^pkg/lib/foo$ - -# Holds regexp rules which will exclude matched files or packages -# from coverage statistics -exclude: - # Exclude files or packages matching their paths - paths: - - \.pb\.go$ # excludes all protobuf generated files - # - ^pkg/bar # exclude package `pkg/bar` - -# NOTES: -# - symbol `/` in all path regexps will be replaced by current OS file path separator -# to properly work on Windows diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c05dfc..1b79e86 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,27 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] + +### PVE API wrapper + +#### Fixed +- PVE original passthrough handler now properly includes the request query params (resolves [#4](https://github.com/iolave/go-proxmox/issues/4)). + + +### PVE API client + +#### Added +- Added the `api` package that contains raw proxmox api implementations for: + - `/api2/json/access` + - `/api2/json/cluster` + +#### Changed +- Renamed `pve.PVE` to `pve.Client`. +- Moved the `GetVersion` method from `pkg/pve` to `pkg/pve/core`. ## [v0.7.1] ### PVE API client diff --git a/Makefile b/Makefile index bb825a7..54a305c 100644 --- a/Makefile +++ b/Makefile @@ -1,13 +1,5 @@ GOBIN ?= $$(go env GOPATH)/bin -.PHONY: install-docs-dependencies -install-docs-dependencies: - ./scripts/install-docs-deps.sh - -.phony: install-dependencies -install-dependencies: install-docs-dependencies - go mod tidy - .PHONY: test test: go test -v ./... @@ -16,16 +8,16 @@ test: coverage: ./scripts/coverage.sh -.PHONY: generate-docs -generate-docs: install-docs-dependencies - bash ./scripts/generate-docs.sh +.PHONY: docs +docs: + ./scripts/generate-docs.sh .PHONY: preview-docs -preview-docs: install-docs-dependencies generate-docs - bash ./scripts/preview-docs.sh +preview-docs: + ./scripts/generate-docs.sh -p .PHONY: build -build: install-dependencies +build: $(eval $@GOOS = linux) $(eval $@GOARCH = amd64) CGO_ENABLED=0 GOOS=$($@GOOS) GOARCH=$($@GOARCH) go build -ldflags="-extldflags=-static" -o "bin/pve-api-wrapper-$($@GOOS)-$($@GOARCH)" ./cmd/pve_api_wrapper/pve_api_wrapper.go diff --git a/README.md b/README.md index 3cf96a9..5d9a566 100644 --- a/README.md +++ b/README.md @@ -3,13 +3,73 @@ > [!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) -go-proxmox is a set of tools I built in order to manage proxmox instances remotely without too much effort. +A fully-featured set of tools for Proxmox Virtual Environment. +This repository provides three layers: -## Tools -- Proxmox go client: To see a list of all implemented api endpoints and more information, click [here]. -- Proxmox cli (not available yet): Proxmox remote management tool. -- Proxmox [api wrapper]: Proxmox api wrapper that adds missing features to proxmox default one. +- Low-level 1:1 API implementation: minimal abstractions, closely matching the upstream Proxmox REST API. To see a list of all implemented api endpoints and more information, click [here]. +- [API Wrapper] (binary): exposes additional features and allows original api calls to be passed through. +- High-level, ergonomic client – a set of well-documented Go interfaces that smooths over quirks of the raw API and integrates extensions provided by the wrapper. [here]: https://go-proxmox.iolave.com/go-client/ -[api wrapper]: https://go-proxmox.iolave.com/api-wrapper/ -[telmate/terraform-provider-proxmox]: https://github.com/Telmate/terraform-provider-proxmox +[API Wrapper]: https://go-proxmox.iolave.com/api-wrapper/ + +## Features +### 1:1 Proxmox API Implementation +- Direct mapping of Proxmox endpoints, parameters, and responses. +- As close to upstream behavior as possible. +- Useful for users who need full control or raw input/output. +- Unclear or inconsistent API behaviors are intentionally preserved (mirrors the original). + +### API Wrapper +Small binary that exposes: + +- Original API. +- Custom API with missing functionality from the native one. + +It is designed to be deployed on a Proxmox node. + +### High-level Client +- Human-friendly Go API. +- Strong typing and validation where the raw API is ambiguous. +- Includes wrapper-only features + +## Project Structure +```text +. +├── pkg/ # Packages that can be imported by other projects +│ │ +│ ├── api/ # Proxmox API 1:1 implementation +│ ├── helpers/ # General purpose helpers +│ └── pve/ # High-level Proxmox API client +│ +├── cmd/ # Command line tools +│ │ +│ ├── pve-api-wrapper/ # Proxmox API wrapper +│ └── gomarkdoc/ # Documentation generator +│ +├── internal/ # API Wrapper internals +├── scripts/ # Shell scripts, mostly for development and Makefile +├── docs/ # MKDocs documentation +├── README.md # This file +├── Makefile # Makefile for building, testing and documentation generation +├── LICENSE # License +├── go.mod # Go module definition +├── go.sum # Go module checksums +└── mkdocs.yml # MKDocs configuration +``` + +## Documentation +- The go client documentation is available [here]. +- The API wrapper documentation is available [here](https://go-proxmox.iolave.com/api-wrapper/). + +## Contributing +Contributions are welcome! + +Please: + +- Open an issue before large changes. +- Keep PRs focused and well‑scoped. +- Include relevant tests. + +[here]: https://go-proxmox.iolave.com/go-client/ +[API Wrapper]: https://go-proxmox.iolave.com/api-wrapper/ diff --git a/cmd/gomarkdoc/main.go b/cmd/gomarkdoc/main.go index 0c3d98a..44a59b6 100644 --- a/cmd/gomarkdoc/main.go +++ b/cmd/gomarkdoc/main.go @@ -13,10 +13,9 @@ import ( func main() { packages := []string{ + "api", "pve", "helpers", - "cloudflare", - "errors", } for i := 0; i < len(packages); i++ { diff --git a/cmd/pve_api_wrapper/pve_api_wrapper.go b/cmd/pve_api_wrapper/pve_api_wrapper.go index 9a320f4..13a3d12 100644 --- a/cmd/pve_api_wrapper/pve_api_wrapper.go +++ b/cmd/pve_api_wrapper/pve_api_wrapper.go @@ -7,7 +7,7 @@ import ( "github.com/alexflint/go-arg" _ "github.com/iolave/go-proxmox/docs/api-wrapper" - "github.com/iolave/go-proxmox/internal/server" + "github.com/iolave/go-proxmox/internal/api_wrapper/server" ) // @title Proxmox API Wrapper diff --git a/docs/api-wrapper/index.md b/docs/api-wrapper/index.md index 4991483..e6ad466 100644 --- a/docs/api-wrapper/index.md +++ b/docs/api-wrapper/index.md @@ -10,10 +10,10 @@ The pve api wrapper is an http server ment to be installed on the proxmox host s ## Installation ### Latest release -The installation script installs the `pve-api-wrapper` binary into `/usr/local/bin`. +The installation script installs the latest `pve-api-wrapper` binary into `/usr/local/bin`. ```bash -curl https://raw.githubusercontent.com/iolave/go-proxmox/refs/tags/latest/scripts/install.sh | bash +curl https://raw.githubusercontent.com/iolave/go-proxmox/refs/tags/latest/scripts/install-paw.sh | bash ``` _Inspect the installation script code [here]._ @@ -51,7 +51,7 @@ pve-api-wrapper [--version] [--pve-host PVE-HOST] [--pve-port PVE-PORT] [--host sudo pve-api-wrapper service install ``` -[here]: https://github.com/iolave/go-proxmox/blob/latest/scripts/install.sh +[here]: https://github.com/iolave/go-proxmox/blob/latest/scripts/install-paw.sh [reference]: https://go-proxmox.iolave.com/api-wrapper/reference/