sweb

README

sweb-go-sdk

A Go client for the SpaceWeb (sweb.ru) hosting API.

The API speaks JSON-RPC 2.0 over HTTPS. This SDK wraps the transport (envelope, Bearer auth, error handling) and exposes typed operations grouped into services. It is the shared foundation for the sweb CLI and a future Terraform provider.

Install

go get github.com/sanchpet/sweb-go-sdk

Usage

package main

import (
	"context"
	"fmt"

	sweb "github.com/sanchpet/sweb-go-sdk"
)

func main() {
	ctx := context.Background()

	// 1. Exchange credentials for a token (unauthenticated endpoint).
	tmp := sweb.New()
	token, err := tmp.CreateToken(ctx, "login", "password")
	if err != nil {
		panic(err)
	}

	// 2. Use the token for authenticated calls.
	c := sweb.New(sweb.WithToken(token))

	vpsList, err := c.VPS.List(ctx)
	if err != nil {
		panic(err)
	}
	fmt.Println(vpsList)
}

Status

Early. The transport (JSON-RPC envelope, auth, error handling) is covered by tests. Resource result types (VPS list, available config, create) are provisional and will be firmed up against recorded API responses.

License

MIT — see LICENSE.

Documentation

Overview

Package sweb is a Go client for the SpaceWeb (sweb.ru) hosting API.

The API speaks JSON-RPC 2.0 over HTTPS POST. Client is a facade: New wires the per-service clients (vps, ip, dns, …) over one shared transport and exposes them as fields (e.g. Client.VPS), preserving every call site. The transport (envelope, Bearer auth with transparent token refresh, error handling) lives in internal/transport, so it is unimportable by external consumers.

SpaceWeb issues short-lived session tokens and has no refresh-token flow. Use WithCredentials so the client transparently re-exchanges login+password for a fresh token when the session expires.

Index

• Constants
• Variables
• type Client
  • func New(opts ...Option) *Client
  • func (c *Client) CreateToken(ctx context.Context, login, password string) (string, error)
  • func (c *Client) Token() string
• type Option

Constants

const DefaultBaseURL = transport.DefaultBaseURL

DefaultBaseURL is the production SpaceWeb API root.

Variables

var (
	// WithBaseURL overrides the API root (useful for tests / staging).
	WithBaseURL = transport.WithBaseURL
	// WithToken sets the Bearer token used for authenticated endpoints.
	WithToken = transport.WithToken
	// WithHTTPClient injects a custom *http.Client (timeouts, transport, test server).
	WithHTTPClient = transport.WithHTTPClient
	// WithCredentials enables transparent token refresh: when a call fails because
	// the session token expired, the client exchanges login+password for a fresh
	// token (getToken) and retries once. Pair with WithOnTokenRefresh to persist it.
	WithCredentials = transport.WithCredentials
	// WithOnTokenRefresh registers a callback invoked with the new token whenever
	// the client refreshes it — e.g. to cache it in an OS keyring.
	WithOnTokenRefresh = transport.WithOnTokenRefresh
)

The functional options, re-exported from the transport.

Types

type Client

type Client struct {

	// VPS groups VPS operations (endpoint /vps).
	VPS *vps.Service
	// IP groups IP operations (endpoint /vps/ip): local network + public IPs.
	IP *ip.Service
	// Backup groups local backup operations (endpoint /vps/backup).
	Backup *backup.Service
	// RemoteBackup groups cloud backup operations (endpoint /vps/remoteBackup).
	RemoteBackup *remotebackup.Service
	// DNS groups DNS-zone operations (endpoint /domains/dns).
	DNS *dns.Service
	// Domains groups domain/subdomain operations (endpoint /domains).
	Domains *domains.Service
	// Balancer groups load-balancer operations (endpoint /balancer).
	Balancer *balancer.Service
	// DBaaS groups managed-database operations (endpoint /dbaas).
	DBaaS *dbaas.Service
	// SSL groups VPS SSL-certificate operations (endpoint /vps/ssl).
	SSL *ssl.Service
	// Monitoring groups monitoring-tariff operations (endpoint /monitoring).
	Monitoring *monitoring.Service
	// MonitoringChecks groups monitoring-check operations (endpoint /monitoring/checks).
	MonitoringChecks *checks.Service
	// MonitoringContacts groups monitoring-contact operations (endpoint /monitoring/contacts).
	MonitoringContacts *contacts.Service

	// Mail groups shared-hosting email operations (endpoint /vh/mail).
	Mail *mail.Service
	// HostingDB groups shared-hosting database operations (endpoint /vh/hosting).
	HostingDB *hosting.Service
	// Sites groups shared-hosting website operations (endpoint /sites).
	Sites *sites.Service
	// VHSSL groups shared-hosting SSL-certificate operations (endpoint /vh/ssl).
	VHSSL *vhssl.Service
	// VHBackup groups shared-hosting account-backup operations (endpoint /vh/backup).
	VHBackup *vhbackup.Service
	// Cron groups shared-hosting crontab operations (endpoint /vh/cron).
	Cron *cron.Service
	// DDoSGuard groups DDoS-Guard operations (endpoint /vh/ddg).
	DDoSGuard *ddg.Service
	// HostingLoad groups shared-hosting server-load operations (endpoint /vh/load).
	HostingLoad *load.Service
	// SSH groups shared-hosting SSH-toggle operations (endpoint /vh/utils).
	SSH *ssh.Service
	// DiskUsage groups shared-hosting disk-usage operations (endpoint /vh/utils/diskUsage).
	DiskUsage *diskusage.Service
	// Tariff groups tariff / server-info operations (endpoint /tariff).
	Tariff *tariff.Service
	// Pay groups billing operations (endpoint /pay).
	Pay *pay.Service
	// Persons groups domain-registrant-person operations (endpoint /domains/persons).
	Persons *persons.Service
	// Bonus groups domain-bonus operations (endpoint /domains/bonus).
	Bonus *bonus.Service
	// PartnerProgram groups partner-program operations (endpoint /vh/partnerProgram).
	PartnerProgram *partner.Service
	// ReferralProgram groups referral-program operations (endpoint /vh/referralProgram).
	ReferralProgram *referral.Service
	// contains filtered or unexported fields
}

Client talks to the SpaceWeb JSON-RPC API. Construct it with New. It is a facade: each field is a service client sharing one transport.

func New

func New(opts ...Option) *Client

New builds a Client. A token (WithToken) and/or credentials (WithCredentials) are optional but required for authenticated endpoints.

func (*Client) CreateToken

func (c *Client) CreateToken(ctx context.Context, login, password string) (string, error)

CreateToken exchanges a login + password for a personal access token via the unauthenticated endpoint (/notAuthorized/, method getToken). The returned token is then supplied via WithToken for authenticated calls.

func (*Client) Token

func (c *Client) Token() string

Token returns the current Bearer token (which may have been refreshed).

type Option

type Option = transport.Option

Option configures a Client. Options are defined in the transport and re-exported here so callers keep using sweb.WithToken(…) etc.