xmlrpc

README

XML-RPC Client for Go

This is an implementation of client-side part of XML-RPC protocol in Go.

Usage

Add dependency to your project:

go get -u alexejk.io/go-xmlrpc

Use it by creating an *xmlrpc.Client and firing RPC method calls with Call().

package main

import(
    "fmt"

    "alexejk.io/go-xmlrpc"
)

func main() {
    client, _ := xmlrpc.NewClient("https://bugzilla.mozilla.org/xmlrpc.cgi")
    defer client.Close()
	
    result := &struct {
        BugzillaVersion struct {
            Version string
        }
    }{}

    _ = client.Call("Bugzilla.version", nil, result)
    fmt.Printf("Version: %s\n", result.BugzillaVersion.Version)
}

Customization is supported by passing a list of Option to the NewClient function. For instance:

• To customize any aspect of http.Client used to perform requests, use HttpClient option, otherwise http.DefaultClient will be used
• To pass custom headers, make use of Headers option.
• To not fail parsing when unmapped fields exist in RPC responses, use SkipUnknownFields(true) option (default is false)
• To change how <dateTime.iso8601> values are encoded and decoded, use TimeFormat option (default is time.RFC3339) - see Time formats

Argument encoding

Arguments to the remote RPC method are passed on as a *struct. This struct is encoded into XML-RPC types based on following rules:

• Order of fields in struct type matters - fields are taken in the order they are defined on the type.
• Numbers are to be specified as int (encoded as <int>) or float64 (encoded as <double>)
• Both pointer and value references are accepted (pointers are followed to actual values)
• map[string]any types are accepted and encoded into <struct>

Shortcut:
If a single <struct> argument is expected for the RPC method call, it is sometimes more convenient to pass a map[string]any as an argument without wrapping into struct{}. This map[string]any will be encoded into a single <struct> argument with <member> elements for each key-value pair. No other key types are supported and neither is it possible to apply this approach with multiple arguments (or other types).

Order preservation:
As per XML-RPC specification, the order of <member> elements in <struct> is not defined. When using maps, order of members in a struct is undeterministic, thus it is not guaranteed that the order of <member> elements will match the order of keys in the map (due to Go not preserving the order of keys). To preserve the order, use a struct type with fields defined in the desired order (order is inherited from the struct type itself, not the instance).

Response decoding

Response is decoded following similar rules to argument encoding.

• Order of fields is important.
• Outer struct should contain exported field for each response parameter (it is possible to ignore unknown structs with SkipUnknownFields option).
• Structs may contain pointers - they will be initialized if required.
• Structs may be parsed as map[string]any, in case struct member names are not known at compile time. Map keys are enforced to string type.

Character Encoding Support

The library automatically detects and handles character encodings in XML-RPC responses beyond UTF-8, including ISO-8859-1, Windows-1252, and other charsets commonly found in legacy XML-RPC services.

Character encoding is automatically detected from the XML declaration (e.g., <?xml version="1.0" encoding="ISO-8859-1"?>), and the response is transparently converted to UTF-8 for Go string handling. This enables seamless interoperability with XML-RPC servers that don't use UTF-8 encoding.

Note: This feature relies on the golang.org/x/net/html/charset package.

Handling of Empty Values

If XML-RPC response contains no value for well-known data-types, it will be decoded into the default "empty" values as per table below:

XML-RPC Value	Default Value
<string/>	""
<int/>, <i4/>	0
<boolean/>	false
<double/>	0.0
<dateTime.iso8601/>	time.Time{}
<base64/>	nil
<array><data/><array>	nil

As per XML-RPC specification, <struct> may not have an empty list of <member> elements, thus no default "empty" value is defined for it. Similarly, <array/> is considered invalid.

Time formats

The XML-RPC specification defines dateTime.iso8601 as ISO8601, but implementations disagree in practice - compact and extended forms, present or absent timezone offsets and fractional seconds are all encountered. By default this library encodes and decodes using time.RFC3339. The TimeFormat option changes that:

c, err := xmlrpc.NewClient("https://example.com/rpc", xmlrpc.TimeFormat(&xmlrpc.LayoutTimeFormatter{
    // Encode using the compact form from the specification's example: 19980717T14:08:55
    FormatLayout: xmlrpc.LayoutISO8601Compact,
    // Accept any of the commonly encountered forms when decoding
    ParseLayouts: xmlrpc.CommonParseLayouts(),
    // The compact layout carries no offset, so pin both directions to UTC
    FormatLocation: time.UTC,
    ParseLocation:  time.UTC,
}))

Fields come in two pairs: Format* controls what goes on the wire, Parse* what is accepted off it. FormatLayout is the single layout used to encode; ParseLayouts are tried in order when decoding and default to FormatLayout when unset. When you do set ParseLayouts it is the complete list - FormatLayout is not added for you, so include it if this client should still read back what it writes. A few layout constants are provided:

Constant	Example
LayoutISO8601Compact	19980717T14:08:55
LayoutISO8601CompactZoned	19980717T14:08:55+0200
LayoutISO8601Basic	19980717T140855
LayoutISO8601BasicZoned	19980717T140855+0200
LayoutISO8601Extended	1998-07-17T14:08:55
LayoutISO8601ExtendedZoned	1998-07-17T14:08:55+02:00

ISO8601 calls the form without separators basic and the form with them extended. The layout shown in the XML-RPC specification's example is neither - a basic date with an extended time - and is called compact here. The specification does not mandate a layout, and leaves timezone assumptions to server documentation, which is why this is configurable at all. A fractional second is accepted on decode even though no layout declares one.

Notes on timezones:

• ParseLocation only applies to decoded values whose layout carries no offset - values that do carry one always keep it. Left unset it follows time.Parse: offset-less values are UTC, and an offset matching the process timezone yields that location along with its DST rules. Set it to decode into one location regardless of where the process runs.
• FormatLocation, when set, converts values to that location before encoding. By default values are encoded in whichever location they carry, which is fine for zoned layouts but a trap for zone-less ones: a non-UTC time.Time would be written as its local wall-clock with no offset, and the receiver has no way to know. Always set FormatLocation when FormatLayout carries no offset.

Servers doing something stranger than a fixed set of layouts can be handled by implementing the TimeFormatter interface directly:

type TimeFormatter interface {
    FormatTime(t time.Time) string
    ParseTime(value string) (time.Time, error)
}

Field renaming

XML-RPC specification does not necessarily specify any rules for struct's member names. Some services allow struct member names to include characters not compatible with standard Go field naming. To support these use-cases, it is possible to remap the field by use of struct tag xmlrpc.

For example, if a response value is a struct that looks like this:

<struct>
    <member>
        <name>stringValue</name>
        <value><string>bar</string></value>
    </member>
    <member>
        <name>2_numeric.Value</name>
        <value><i4>2</i4></value>
    </member>
</struct>

it would be impossible to map the second value to a Go struct with a field 2_numeric.Value as it's not valid in Go. Instead, we can map it to any valid field as follows:

v := &struct {
    StringValue string
    SecondNumericValue string `xmlrpc:"2_numeric.Value"`
}{}

Similarly, request encoding honors xmlrpc tags.

Building

To build this project, simply run make all. If you prefer building in Docker instead - make build-in-docker is your friend.

Documentation

Index

• Constants
• func CommonParseLayouts() []string
• type Client
  • func NewClient(endpoint string, opts ...Option) (*Client, error)
  • func NewCustomClient(endpoint string, httpClient *http.Client) (*Client, error)
• type Codec
  • func NewCodec(endpoint *url.URL, httpClient *http.Client) *Codec
  • func (c *Codec) Close() error
  • func (c *Codec) ReadResponseBody(v interface{}) error
  • func (c *Codec) ReadResponseHeader(resp *rpc.Response) error
  • func (c *Codec) SetDecoder(decoder Decoder)
  • func (c *Codec) SetEncoder(encoder Encoder)
  • func (c *Codec) WriteRequest(req *rpc.Request, args interface{}) error
• type Decoder
• type Encoder
• type Fault
  • func (f *Fault) Error() string
• type LayoutTimeFormatter
  • func (f *LayoutTimeFormatter) FormatTime(t time.Time) string
  • func (f *LayoutTimeFormatter) ParseTime(value string) (time.Time, error)
• type Option
  • func Headers(headers map[string]string) Option
  • func HttpClient(httpClient *http.Client) Option
  • func SkipUnknownFields(skip bool) Option
  • func TimeFormat(formatter TimeFormatter) Option
  • func UserAgent(userAgent string) Option
• type Response
  • func NewResponse(body []byte) (*Response, error)
• type ResponseArrayData
• type ResponseFault
• type ResponseParam
• type ResponseStructMember
• type ResponseValue
• type StdDecoder
  • func (d *StdDecoder) Decode(response *Response, v interface{}) error
  • func (d *StdDecoder) DecodeFault(response *Response) *Fault
  • func (d *StdDecoder) DecodeRaw(body []byte, v interface{}) error
• type StdEncoder
  • func (e *StdEncoder) Encode(w io.Writer, methodName string, args interface{}) error
• type TimeFormatter

Constants

const (
	// LayoutISO8601Compact is the form shown in the XML-RPC specification's example, e.g. "19980717T14:08:55".
	LayoutISO8601Compact = "20060102T15:04:05"
	// LayoutISO8601CompactZoned is the compact form with a numeric timezone offset, e.g. "19980717T14:08:55+0200".
	LayoutISO8601CompactZoned = "20060102T15:04:05Z0700"
	// LayoutISO8601Basic is the ISO8601 basic form, without any separators, e.g. "19980717T140855".
	LayoutISO8601Basic = "20060102T150405"
	// LayoutISO8601BasicZoned is the basic form with a numeric timezone offset, e.g. "19980717T140855+0200".
	LayoutISO8601BasicZoned = "20060102T150405Z0700"
	// LayoutISO8601Extended is the extended form without a timezone offset, e.g. "1998-07-17T14:08:55".
	LayoutISO8601Extended = "2006-01-02T15:04:05"
	// LayoutISO8601ExtendedZoned is the extended form with a timezone offset, e.g. "1998-07-17T14:08:55+02:00".
	// This is equivalent to time.RFC3339.
	LayoutISO8601ExtendedZoned = time.RFC3339
)

Layouts for the XML-RPC <dateTime.iso8601> type, for use with LayoutTimeFormatter.

ISO8601 calls a form with no separators "basic" and a form with separators "extended". The layout shown in the XML-RPC specification's example is neither: it combines a basic date with an extended time, and is called compact here. The specification does not mandate a layout, and leaves timezone assumptions to server documentation.

Functions

func CommonParseLayouts

func CommonParseLayouts() []string

CommonParseLayouts returns the dateTime.iso8601 layouts commonly encountered in the wild, ordered most to least specific. Intended for LayoutTimeFormatter.ParseLayouts when the exact form a server emits is unknown or inconsistent.

Types

type Client

type Client struct {
	*rpc.Client
	// contains filtered or unexported fields
}

Client is responsible for making calls to RPC services with help of underlying rpc.Client.

func NewClient

func NewClient(endpoint string, opts ...Option) (*Client, error)

NewClient creates a Client with http.DefaultClient. If provided endpoint is not valid, an error is returned.

func NewCustomClient

func NewCustomClient(endpoint string, httpClient *http.Client) (*Client, error)

NewCustomClient allows customization of http.Client used to make RPC calls. If provided endpoint is not valid, an error is returned.

Deprecated: prefer using NewClient with HttpClient Option

type Codec

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

Codec implements methods required by rpc.ClientCodec In this implementation Codec is the one performing actual RPC requests with http.Client.

func NewCodec

func NewCodec(endpoint *url.URL, httpClient *http.Client) *Codec

NewCodec creates a new Codec bound to provided endpoint. Provided client will be used to perform RPC requests.

func (*Codec) Close

func (c *Codec) Close() error

func (*Codec) ReadResponseBody

func (c *Codec) ReadResponseBody(v interface{}) error

func (*Codec) ReadResponseHeader

func (c *Codec) ReadResponseHeader(resp *rpc.Response) error

func (*Codec) SetDecoder

func (c *Codec) SetDecoder(decoder Decoder)

SetDecoder allows setting a new Decoder on the codec

func (*Codec) SetEncoder

func (c *Codec) SetEncoder(encoder Encoder)

SetEncoder allows setting a new Encoder on the codec

func (*Codec) WriteRequest

func (c *Codec) WriteRequest(req *rpc.Request, args interface{}) error

type Decoder

type Decoder interface {
	DecodeRaw(body []byte, v interface{}) error
	Decode(response *Response, v interface{}) error
	DecodeFault(response *Response) *Fault
}

Decoder implementations provide mechanisms for parsing of XML-RPC responses to native data-types.

type Encoder

type Encoder interface {
	Encode(w io.Writer, methodName string, args interface{}) error
}

Encoder implementations are responsible for handling encoding of XML-RPC requests to the proper wire format.

type Fault

type Fault struct {
	// Code provides numerical failure code
	Code int
	// String includes more detailed information about the fault, such as error name and cause
	String string
}

Fault is a wrapper for XML-RPC fault object

func (*Fault) Error

func (f *Fault) Error() string

type LayoutTimeFormatter

type LayoutTimeFormatter struct {
	// FormatLayout is used to encode values. Defaults to time.RFC3339.
	// Zone-less layouts should be paired with FormatLocation.
	FormatLayout string

	// FormatLocation, when set, converts values to this location before encoding.
	// This matters for zone-less layouts, where the offset is lost on the wire.
	// Defaults to nil, meaning values are encoded in whichever location they carry.
	FormatLocation *time.Location

	// ParseLayouts are attempted in order when decoding. Defaults to FormatLayout.
	// When set, it is the complete list - FormatLayout is not appended, so include it
	// to keep accepting values this client encodes. See CommonParseLayouts.
	ParseLayouts []string

	// ParseLocation resolves decoded values whose layout carries no timezone offset.
	// Values that do carry an offset always keep it.
	//
	// Defaults to nil, meaning time.Parse semantics: values without an offset are UTC,
	// and an offset matching the process timezone yields that location, keeping its DST
	// rules. Set this to decode into one location regardless of where the process runs.
	ParseLocation *time.Location
}

LayoutTimeFormatter is the default TimeFormatter implementation, driven by time package layout strings. A nil *LayoutTimeFormatter behaves as the zero value.

func (*LayoutTimeFormatter) FormatTime

func (f *LayoutTimeFormatter) FormatTime(t time.Time) string

func (*LayoutTimeFormatter) ParseTime

func (f *LayoutTimeFormatter) ParseTime(value string) (time.Time, error)

type Option

type Option func(client *Client)

Option is a function that configures a Client by mutating it

func Headers

func Headers(headers map[string]string) Option

Headers option allows setting custom headers that will be passed with every request

func HttpClient

func HttpClient(httpClient *http.Client) Option

HttpClient option allows setting custom HTTP Client to be used for every request

func SkipUnknownFields

func SkipUnknownFields(skip bool) Option

SkipUnknownFields option allows setting decoder setting to skip unknown fields. This is only effective if using standard client, which in turn uses StdDecoder.

func TimeFormat

func TimeFormat(formatter TimeFormatter) Option

TimeFormat option allows customizing how time.Time values are encoded to and decoded from the XML-RPC <dateTime.iso8601> type. When unset, values are encoded and decoded using time.RFC3339. See LayoutTimeFormatter for layout-based customization.

This is only effective if using standard client, which in turn uses StdEncoder and StdDecoder.

func UserAgent

func UserAgent(userAgent string) Option

UserAgent option allows setting custom User-Agent header. This is a convenience method when only UA needs to be modified. For other cases use Headers option.

type Response

type Response struct {
	Params []*ResponseParam `xml:"params>param"`
	Fault  *ResponseFault   `xml:"fault,omitempty"`
}

Response is the basic parsed object of the XML-RPC response body. While it's not convenient to use this object directly - it contains all the information needed to unmarshal into other data-types.

func NewResponse

func NewResponse(body []byte) (*Response, error)

NewResponse creates a Response object from XML body. It relies on XML Unmarshaler and if it fails - error is returned.

type ResponseArrayData

type ResponseArrayData struct {
	Values []*ResponseValue `xml:"value"`
}

ResponseArrayData contains a list of array values

type ResponseFault

type ResponseFault struct {
	Value ResponseValue `xml:"value"`
}

ResponseFault wraps around failure

type ResponseParam

type ResponseParam struct {
	Value ResponseValue `xml:"value"`
}

ResponseParam encapsulates a nested parameter value

type ResponseStructMember

type ResponseStructMember struct {
	Name  string        `xml:"name"`
	Value ResponseValue `xml:"value"`
}

ResponseStructMember contains name-value pair of the struct

type ResponseValue

type ResponseValue struct {
	Array    *ResponseArrayData      `xml:"array>data"`
	Struct   []*ResponseStructMember `xml:"struct>member"`
	String   *string                 `xml:"string"`
	Int      *string                 `xml:"int"`
	Int4     *string                 `xml:"i4"`
	Double   *string                 `xml:"double"`
	Boolean  *string                 `xml:"boolean"`
	DateTime *string                 `xml:"dateTime.iso8601"`
	Base64   *string                 `xml:"base64"`

	RawXML string `xml:",innerxml"`
}

ResponseValue encapsulates one of the data types for each parameter. Only one field should be set.

type StdDecoder

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

StdDecoder is the default implementation of the Decoder interface.

func (*StdDecoder) Decode

func (d *StdDecoder) Decode(response *Response, v interface{}) error

func (*StdDecoder) DecodeFault

func (d *StdDecoder) DecodeFault(response *Response) *Fault

func (*StdDecoder) DecodeRaw

func (d *StdDecoder) DecodeRaw(body []byte, v interface{}) error

type StdEncoder

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

StdEncoder is the default implementation of Encoder interface.

func (*StdEncoder) Encode

func (e *StdEncoder) Encode(w io.Writer, methodName string, args interface{}) error

type TimeFormatter

type TimeFormatter interface {
	FormatTime(t time.Time) string
	ParseTime(value string) (time.Time, error)
}

TimeFormatter implementations convert between time.Time and the string contents of the XML-RPC <dateTime.iso8601> type.

Implementations must be safe for concurrent use and must not be mutated once passed to a Client. ParseTime is never called with an empty string - empty XML values are decoded to the zero time.Time by the decoder.