Skip to content

Latest commit

 

History

History
162 lines (123 loc) · 7.99 KB

README.md

File metadata and controls

162 lines (123 loc) · 7.99 KB
Raw

pritunl-api-go

Pritunl API Client for Go

A Go client for the Pritunl API, allowing you to interact with Pritunl servers and perform various actions.

Quality Gate Status

Getting Started

Environment Variables

Load your Pritunl API credentials as environment variables:

export PRITUNL_BASE_URL="https://vpn.domain.tld"
export PRITUNL_API_TOKEN="<PRITUNL API TOKEN>"
export PRITUNL_API_SECRET="<PRITUNL API SECRET>"

Installation

Get the Pritunl API Client for Go package/library:

go get github.com/nathanielvarona/pritunl-api-go

Usage

Initialize an API instance and call available feature functions:

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"

	"github.com/nathanielvarona/pritunl-api-go"
)

func main() {
	// Initialize the Pritunl API client
	client, err := pritunl.NewClient()
	// Alternatively, you can initialize the client with manual arguments
	// client, err := pritunl.NewClient(&pritunl.Client{
	// 	BaseUrl:   "<PRITUNL BASE URL>",
	// 	ApiToken:  "<PRITUNL API TOKEN>",
	// 	ApiSecret: "<PRITUNL API SECRET>",
	// })
	if err != nil {
		log.Fatal(err)
	}

	// Create a context for the request
	ctx := context.Background()

	// Retrieve the server status
	status, err := client.StatusGet(ctx)
	if err != nil {
		log.Fatal(err)
	}

	// Print server status details
	fmt.Println("Server Status:")
	for _, stat := range status {
		fmt.Println("Server Version:", stat.ServerVersion)
		fmt.Println("Local Networks:", stat.LocalNetworks)
		fmt.Println("Host Online:", stat.HostsOnline)
		fmt.Println("------")
	}

	// Marshal server status to JSON
	statusBytes, err := json.MarshalIndent(status, "", "  ")
	if err != nil {
		log.Println("Error marshalling status:", err)
	} else {
		fmt.Println("Server Status in JSON:")
		fmt.Println(string(statusBytes))
	}
}

Examples

Check the _examples folder for code examples demonstrating how to use this package/library.

Contributing

We welcome your contributions to pritunl-api-go. This guide outlines the process for contributing effectively.

Fork & Pull Requests

Workflow:

  1. Fork the repository: Visit the pritunl-api-go repository on GitHub and click "Fork". This creates your own copy.
  2. Clone your forked repository: Use git clone to clone your forked copy to your local development environment.
  3. Create a Branch: Use a descriptive branch name following the convention <type>/<descriptive-name>.
    • <type>: Choose from breaking, feature, improvement, automation, or documentation.
    • Refer to the .github/labels.yml and .github/pr-labeler.yml file for valid <type> options and label descriptions. (e.g., improvement/start-stop-a-server)
  4. Make your changes: Implement your code modifications, ensuring they adhere to Go coding conventions gofmt and consider adding unit tests ref* for new features.
  5. Commit your changes: Stage and commit your changes with clear and concise commit messages.
  6. Push your branch and Create a Pull Request: Push your local branch to your forked repository on GitHub and create a pull request with a detailed description of your changes.

Additional Tips:

  • ref* Include examples where relevant to illustrate your changes.
  • Simplify your development workflow! We recommend using a Go workspace when contributing to pritunl-api-go. Go workspaces provide a clean and efficient way to manage dependencies.

Rebasing and Squashing Commits

Before submitting your pull request, we recommend cleaning up your commit history to make it easier to review. This involves rebasing your branch on top of the main branch and combining your commits into a single, clear commit. Additionally, please ensure that your commit author name and email are consistent with your GitHub account, as this will help us keep a clear record of contributions.

We appreciate your contributions to the project!

By following these guidelines, you'll help us maintain a high-quality codebase and make it easier for others to contribute. Thank you for taking the time to contribute to pritunl-api-go!

Features

Core Pritunl API Client

Feature Function Description Status
StatusGet Status of Pritunl Server ✅ Yes
KeyGet Generate or Retrieve a Key for the User ✅ Yes
UserGet Get the Information of Existing User ✅ Yes
UserCreate Create a New User ✅ Yes
UserUpdate Update an Existing User ✅ Yes
UserDelete Delete an User ✅ Yes
OrganizationGet Get the Information of Existing Org ✅ Yes
OrganizationCreate Create a New Org ✅ Yes
OrganizationUpdate Update an Existing Org ✅ Yes
OrganizationDelete Delete an Org ✅ Yes
ServerGet Get the Information of Existing Server ✅ Yes
ServerCreate Create a New Server ✅ Yes
ServerUpdate Update an existing Server ✅ Yes
ServerDelete Delete a Server ✅ Yes
ServerStart Start an existing Server ✅ Yes
ServerStop Start an existing Server ✅ Yes
ServerRestart Restart an existing Server ✅ Yes
ServerRouteGet Get the Routes for a Server ✅ Yes
ServerRouteCreate Create/Add a Server Route ✅ Yes
ServerRouteUpdate Update a Server Route ✅ Yes
ServerRouteDelete Remove/Delete a Server Route ✅ Yes
ServerOrgAttach Attach an Organization for a Server ✅ Yes
ServerOrgDetach Detach an Organization for a Server ✅ Yes
ServerHostAttach Attach a Host for a Server ✅ Yes
ServerHostDetach Detach a Host for a Server ✅ Yes

Future Enhancements (CLI)

  1. CLI Framework: Consider using a popular framework like spf13/cobra, urfave/cli, or alecthomas/kong to simplify the command structure, argument parsing, and flag handling.
  2. Build Distribution Workflow: Implement a CI/CD workflow (e.g., using GitHub Actions) to automate building and distributing the CLI tool across various platforms (Windows, macOS, Linux) and architectures (32-bit, 64-bit). This will streamline setup for users on different systems.

Alternative API Clients