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")

    result := &struct {
        BugzillaVersion struct {
            Version string
        }
    }{}

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

If you want to customize any aspect of http.Client used to perform requests or add custom headers, use NewCustomClient instead. By default http.DefaultClient will be used.

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)

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.
• Structs may contain pointers - they will be initialized if required.

Building

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

Documentation

Overview

Package xmlrpc includes everything that is required to perform XML-RPC requests by utilizing familiar rpc.Client interface.

The simplest use-case is creating a client towards an endpoint and making calls:

c, _ := NewClient("https://bugzilla.mozilla.org/xmlrpc.cgi")

resp := &struct {
	BugzillaVersion struct {
		Version string
	}
}{}

err = c.Call("Bugzilla.version", nil, resp)
fmt.Printf("Version: %s\n", resp.BugzillaVersion.Version)

Index

• type Client
  • func NewClient(endpoint string) (*Client, error)
  • func NewCustomClient(endpoint string, httpClient *http.Client, headers map[string]string) (*Client, error)
  • func (c *Client) SetUserAgent(ua string)
  • func (c *Client) UserAgent() string
• type Codec
  • func NewCodec(endpoint *url.URL, httpClient *http.Client, customHeaders map[string]string) *Codec
  • func (c *Codec) Close() error
  • func (c *Codec) ReadResponseBody(v interface{}) error
  • func (c *Codec) ReadResponseHeader(resp *rpc.Response) error
  • func (c *Codec) WriteRequest(req *rpc.Request, args interface{}) error
• type Decoder
• type Encoder
• type Fault
  • func (f *Fault) Error() string
• type Response
  • func NewResponse(body []byte) (*Response, error)
• 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

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) (*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, headers map[string]string) (*Client, error)

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

func (*Client) SetUserAgent

func (c *Client) SetUserAgent(ua string)

SetUserAgent allows customization to User-Agent header. If set to an empty string, User-Agent header will be sent with an empty value.

func (*Client) UserAgent

func (c *Client) UserAgent() string

UserAgent returns currently configured User-Agent header that will be sent to remote server on every RPC call.

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, customHeaders map[string]string) *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) 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 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 ResponseFault

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

type ResponseParam

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

type ResponseStructMember

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

type ResponseValue

type ResponseValue struct {
	Array    []*ResponseValue        `xml:"array>data>value"`
	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"`
}

type StdDecoder

type StdDecoder struct{}

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{}

StdEncoder is the default implementation of Encoder interface.

func (*StdEncoder) Encode

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