xmlrpc

package module
Version: v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Aug 8, 2022 License: MIT Imports: 16 Imported by: 0

README

XML-RPC Client for Go

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

GitHub Workflow Status codecov Go Report Card

GoDoc GitHub GitHub release (latest SemVer)

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)
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 (it is possible to ignore unknown structs with SkipUnknownFields option).
  • Structs may contain pointers - they will be initialized if required.
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

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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 added in v0.2.0

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 added in v0.4.0

func (c *Codec) SetDecoder(decoder Decoder)

SetDecoder allows setting a new Decoder on the codec

func (*Codec) SetEncoder added in v0.4.0

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 added in v0.1.1

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 added in v0.1.1

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 Option added in v0.2.0

type Option func(client *Client)

Option is a function that configures a Client by mutating it

func Headers added in v0.2.0

func Headers(headers map[string]string) Option

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

func HttpClient added in v0.2.0

func HttpClient(httpClient *http.Client) Option

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

func SkipUnknownFields added in v0.4.0

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 UserAgent added in v0.2.0

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 added in v0.1.1

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 added in v0.1.1

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 added in v0.1.1

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

ResponseFault wraps around failure

type ResponseParam added in v0.1.1

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

ResponseParam encapsulates a nested parameter value

type ResponseStructMember added in v0.1.1

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

ResponseStructMember contains name-value pair of the struct

type ResponseValue added in v0.1.1

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"`
}

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

type StdDecoder added in v0.1.1

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

StdDecoder is the default implementation of the Decoder interface.

func (*StdDecoder) Decode added in v0.1.1

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

func (*StdDecoder) DecodeFault added in v0.1.1

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

func (*StdDecoder) DecodeRaw added in v0.1.1

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

type StdEncoder added in v0.1.1

type StdEncoder struct{}

StdEncoder is the default implementation of Encoder interface.

func (*StdEncoder) Encode added in v0.1.1

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL