xmlrpc

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 30, 2026 License: MIT Imports: 14 Imported by: 0

README

GoDoc

Overview

xmlrpc is an implementation of client side part of XMLRPC protocol in Go language.

Status

This project is in minimal maintenance mode with no further development. Bug fixes are accepted, but it might take some time until they are merged.

Installation

To install xmlrpc package run go get github.com/ninech/xmlrpc. To use it in application add "github.com/ninech/xmlrpc" string to import statement.

Usage

client, _ := xmlrpc.NewClient("https://bugzilla.mozilla.org/xmlrpc.cgi", nil)
result := struct{
  Version string `xmlrpc:"version"`
}{}
client.Call("Bugzilla.version", nil, &result)
fmt.Printf("Version: %s\n", result.Version) // Version: 4.2.7+

Second argument of NewClient function is an object that implements http.RoundTripper interface, it can be used to get more control over connection options. By default it is initialized by http.DefaultTransport object.

Arguments encoding

xmlrpc package supports encoding of native Go data types to method arguments.

Data types encoding rules:

  • int, int8, int16, int32, int64 encoded to int;
  • float32, float64 encoded to double;
  • bool encoded to boolean;
  • string encoded to string;
  • time.Time encoded to datetime.iso8601;
  • xmlrpc.Base64 encoded to base64;
  • slice encoded to array;

Structs are encoded to struct by the following rules:

  • all public fields become struct members;
  • field name becomes member name;
  • if field has xmlrpc tag, its value becomes member name.
  • for fields tagged with ",omitempty", empty values are omitted;
  • fields tagged with "-" are omitted.

Server methods can accept multiple arguments, to handle this case there is a special approach to handle slice of empty interfaces ([]interface{}). Each value of such slice is encoded as a separate argument.

Result decoding

Result of remote function is decoded to native Go data type.

Data types decoding rules:

  • int, i4 decoded to int, int8, int16, int32, int64;
  • double decoded to float32, float64;
  • boolean decoded to bool;
  • string decoded to string;
  • array decoded to slice;
  • structs are decoded following the rules described in previous section;
  • datetime.iso8601 decoded as time.Time data type;
  • base64 decoded to string.

Testing

Run unit tests:

go test ./...

Run integration tests (requires Docker):

docker-compose up -d # Start the test server
go test -tags integration ./... # Run all tests including integration tests
docker-compose down # Stop the test server

Contribution

See project status.

Authors

Dmitry Maksimov (dmtmax@gmail.com)

Documentation

Overview

Package xmlrpc provides an XML-RPC client implementation for Go.

The package implements the client side of the XML-RPC protocol, allowing Go programs to make remote procedure calls to XML-RPC servers.

Basic usage: 

client, err := xmlrpc.NewClientWithOptions("https://example.com/xmlrpc",
	xmlrpc.WithHeader("User-Agent", "my-app/1.0"),
	xmlrpc.WithBasicAuth("user", "pass"),
)
if err != nil {
	log.Fatal(err)
}
defer client.Close()

var result string
err = client.Call("Method.Name", arg, &result)
Example 
package main

import (
	"fmt"
	"log"

	"github.com/ninech/xmlrpc"
)

func main() {
	client, err := xmlrpc.NewClientWithOptions("https://example.com/xmlrpc",
		xmlrpc.WithHeader("User-Agent", "my-app/1.0"),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = client.Close() }()

	var result struct {
		Version string `xmlrpc:"version"`
	}
	if err := client.Call("App.version", nil, &result); err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Version: %s\n", result.Version)
}

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// CharsetReader, if non-nil, defines a function to generate a reader
	// that converts a non-UTF-8 charset into UTF-8. It has the same signature
	// as [xml.Decoder.CharsetReader].
	CharsetReader func(string, io.Reader) (io.Reader, error)
)

Functions

func EncodeMethodCall 

func EncodeMethodCall(method string, args ...any) ([]byte, error)

EncodeMethodCall encodes an XML-RPC method call with the given method name and arguments into XML bytes.

Example 
package main

import (
	"fmt"
	"log"

	"github.com/ninech/xmlrpc"
)

func main() {
	data, err := xmlrpc.EncodeMethodCall("Math.add", 1, 2)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(data))
}

Output:

<?xml version="1.0" encoding="UTF-8"?><methodCall><methodName>Math.add</methodName><params><param><value><int>1</int></value></param><param><value><int>2</int></value></param></params></methodCall>

func NewRequest 

func NewRequest(url string, method string, args any) (*http.Request, error)

NewRequest creates an http.Request for an XML-RPC call to the given URL. The method parameter is the XML-RPC method name, and args contains the arguments to pass to the remote method.

func NewRequestContext 

func NewRequestContext(
	ctx context.Context,
	url string,
	method string,
	args any,
) (*http.Request, error)

NewRequestContext creates an http.Request with context for an XML-RPC call to the given URL. The method parameter is the XML-RPC method name, and args contains the arguments to pass to the remote method.

Types

type Base64 

type Base64 string

Base64 is a string type that will be encoded as base64 in XML-RPC requests.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client represents an XML-RPC client.

func NewClient deprecated 

func NewClient(requrl string, transport http.RoundTripper) (*Client, error)

NewClient creates a new XML-RPC client for the given URL. The transport parameter specifies the http.RoundTripper to use for HTTP requests. If transport is nil, http.DefaultTransport is used.

Deprecated: Use NewClientWithOptions instead.

func NewClientWithOptions 

func NewClientWithOptions(requrl string, opts ...Option) (*Client, error)

NewClientWithOptions creates a new XML-RPC client for the given URL with the specified options.

func (*Client) Call 

func (c *Client) Call(serviceMethod string, args any, reply any) error

Call invokes the named method, waits for it to complete, and returns its error status. This is equivalent to CallContext with context.Background.

func (*Client) CallContext 

func (c *Client) CallContext(ctx context.Context, serviceMethod string, args any, reply any) error

CallContext invokes the named method with context support. The context controls cancellation and timeout of the HTTP request.

Example 
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/ninech/xmlrpc"
)

func main() {
	client, err := xmlrpc.NewClientWithOptions("https://example.com/xmlrpc")
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = client.Close() }()

	// Create a context with a 5-second timeout
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	var result struct {
		Status string `xmlrpc:"status"`
	}
	if err := client.CallContext(ctx, "App.status", nil, &result); err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Status: %s\n", result.Status)
}

func (*Client) Close 

func (c *Client) Close() error

Close closes idle connections. The Client can still be used after calling Close.

type FaultError 

type FaultError struct {
	Code   int    `xmlrpc:"faultCode"`
	String string `xmlrpc:"faultString"`
}

FaultError represents an XML-RPC fault response from the server.

func (FaultError) Error 

func (e FaultError) Error() string

Error returns the string representation of the fault.

type Option 

type Option func(*clientOptions)

Option configures a Client.

func WithBasicAuth 

func WithBasicAuth(username, password string) Option

WithBasicAuth sets basic authentication for all requests.

Example 
package main

import (
	"log"

	"github.com/ninech/xmlrpc"
)

func main() {
	client, err := xmlrpc.NewClientWithOptions("https://example.com/xmlrpc",
		xmlrpc.WithBasicAuth("username", "password"),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = client.Close() }()

	var result string
	if err := client.Call("Secure.method", nil, &result); err != nil {
		log.Fatal(err)
	}
}

func WithCookieJar 

func WithCookieJar(jar http.CookieJar) Option

WithCookieJar sets the cookie jar for the client. Pass nil to disable cookie handling.

func WithHTTPClient 

func WithHTTPClient(client *http.Client) Option

WithHTTPClient sets the HTTP client to use for requests. This takes precedence over WithTransport.

func WithHeader 

func WithHeader(key, value string) Option

WithHeader adds a header to all requests. Can be called multiple times to add multiple headers.

func WithTransport 

func WithTransport(transport http.RoundTripper) Option

WithTransport sets the HTTP transport for requests. Ignored if WithHTTPClient is also used.

type Response deprecated 

type Response []byte

Response represents a raw XML-RPC response body.

Deprecated: Response is no longer used internally. Use Client.Call or Client.CallContext instead.

func (Response) Err deprecated 

func (r Response) Err() error

Err checks if the response contains a fault and returns it as a FaultError. If the response is not a fault, Err returns nil.

Deprecated: Use Client.Call or Client.CallContext instead, which return FaultError directly.

func (Response) Unmarshal deprecated 

func (r Response) Unmarshal(v any) error

Unmarshal decodes the XML-RPC response into v.

Deprecated: Use Client.Call or Client.CallContext instead.

type TypeMismatchError 

type TypeMismatchError string

TypeMismatchError is returned when the XML-RPC response type does not match the expected Go type during unmarshaling.

func (TypeMismatchError) Error 

func (e TypeMismatchError) Error() string

Error returns the error message describing the type mismatch.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.