wsman

README

This is a WSMAN library for Go.

Fork of github.com/ammmze/wsman

It mostly adheres to the DMTF specifications at http://www.dmtf.org/standards/wsman, except where it does not.

Right now, it can only communicate with WSMAN endpoints over HTTP/HTTPS using Basic auth.

It has no unit tests because I don't feel like writing a WSMAN endpoint in Go, but the SOAP and xml libraries it is based on do.

Documentation

Overview

Package wsman implements a simple WSMAN client interface. It assumes you are talking to WSMAN over http(s) and using basic authentication.

Index

• Constants
• func Resource(uri string) *dom.Element
• type Client
  • func NewClient(host *url.URL, username, password string, opts ...Option) *Client
  • func (c *Client) Close() error
  • func (c *Client) Create(resource string) *Message
  • func (c *Client) Delete(resource string) *Message
  • func (c *Client) Enumerate(resource string) *Message
  • func (c *Client) EnumerateEPR(resource string) *Message
  • func (c *Client) Get(resource string) *Message
  • func (c *Client) Identify(ctx context.Context) (*soap.Message, error)
  • func (c *Client) Invoke(resource, method string) *Message
  • func (c *Client) NewMessage(action string) (msg *Message)
  • func (c *Client) Open(ctx context.Context) error
  • func (c *Client) Post(ctx context.Context, msg *soap.Message) (response *soap.Message, err error)
  • func (c *Client) Put(resource string) *Message
• type Message
  • func (m *Message) AddOption(options ...*dom.Element) *Message
  • func (m *Message) AddParameter(parameters ...*dom.Element) *Message
  • func (m *Message) AddSelector(selector ...*dom.Element) *Message
  • func (m *Message) AddValue(values ...*dom.Element) *Message
  • func (m *Message) EnumItems() ([]*dom.Element, error)
  • func (m *Message) GHC(field string) (string, error)
  • func (m *Message) GetItem() (*dom.Element, error)
  • func (m *Message) GetResource() string
  • func (m *Message) InvokeResponse() (*dom.Element, string, error)
  • func (m *Message) MakeOption(name string) *dom.Element
  • func (m *Message) MakeParameter(name string) *dom.Element
  • func (m *Message) MakeSelector(name string) *dom.Element
  • func (m *Message) MakeValue(name string) *dom.Element
  • func (m *Message) Options(opts ...string) *Message
  • func (m *Message) Parameters(args ...string) *Message
  • func (m *Message) ResourceURI(resource string) *Message
  • func (m *Message) Selectors(args ...string) *Message
  • func (m *Message) Send(ctx context.Context) (*Message, error)
  • func (m *Message) Values(args ...string) *Message
• type Option
  • func WithLogger(logger logr.Logger) Option
  • func WithUseDigest(useDigest bool) Option

Constants

const (
	// Models any simple single item retrieval.
	Get = "http://schemas.xmlsoap.org/ws/2004/09/transfer/Get"

	// Models an update of an entire item.
	Put = "http://schemas.xmlsoap.org/ws/2004/09/transfer/Put"

	// Models creation of a new item.
	Create = "http://schemas.xmlsoap.org/ws/2004/09/transfer/Create"

	// Models the deletion of an item.
	Delete = "http://schemas.xmlsoap.org/ws/2004/09/transfer/Delete"

	// Begins an enumeration or query.
	Enumerate = "http://schemas.xmlsoap.org/ws/2004/09/enumeration/Enumerate"

	// Retrieves the next batch of results from enumeration.
	Pull = "http://schemas.xmlsoap.org/ws/2004/09/enumeration/Pull"

	// Releases an active enumerator.
	Release = "http://schemas.xmlsoap.org/ws/2004/09/enumeration/Release"

	// Models a subscription to an event source.
	Subscribe = "http://schemas.xmlsoap.org/ws/2004/08/eventing/Subscribe"

	// Renews a subscription prior to its expiration.
	Renew = "http://schemas.xmlsoap.org/ws/2004/08/eventing/Renew"

	// Requests the status of a subscription.
	GetStatus = "http://schemas.xmlsoap.org/ws/2004/08/eventing/GetStatus"

	// Removes an active subscription.
	Unsubscribe = "http://schemas.xmlsoap.org/ws/2004/08/eventing/Unsubscribe"

	// Delivers a message to indicate that a subscription has terminated.
	SubscribeEnd = "http://schemas.xmlsoap.org/ws/2004/08/eventing/SubscriptionEnd"

	// Delivers batched events based on a subscription.
	Events = "http://schemas.dmtf.org/wbem/wsman/1/wsman/Events"

	// A pseudo-event that models a heartbeat of an active subscription;
	// delivered when no real events are available, but used to indicate that the
	// event subscription and delivery mechanism is still active.
	Heartbeat = "http://schemas.dmtf.org/wbem/wsman/1/wsman/Heartbeat"

	// A pseudo-event that indicates that the real event was dropped.
	DroppedEvents = "http://schemas.dmtf.org/wbem/wsman/1/wsman/DroppedEvents"

	// Used by event subscribers to acknowledge receipt of events;
	// allows event streams to be strictly sequenced.
	Ack = "http://schemas.dmtf.org/wbem/wsman/1/wsman/Ack"

	// Used for a singleton event that does not define its own action.
	Event = "http://schemas.dmtf.org/wbem/wsman/1/wsman/Event"
)

const (
	NSWSMAN = "http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd"
	NSWSMID = "http://schemas.dmtf.org/wbem/wsman/identity/1/wsmanidentity.xsd"
	NSWSDL  = "http://schemas.xmlsoap.org/wsdl"
	NSWSA   = "http://schemas.xmlsoap.org/ws/2004/08/addressing"
	NSWSA10 = "http://www.w3.org/2005/08/addressing"
	NSWSAM  = "http://www.w3.org/2007/05/addressing/metadata"
	NSWSME  = "http://schemas.xmlsoap.org/ws/2004/08/eventing"
	NSWSMEN = "http://schemas.xmlsoap.org/ws/2004/09/enumeration"
	NSWSMT  = "http://schemas.xmlsoap.org/ws/2004/09/transfer"
	NSWSP   = "http://schemas.xmlsoap.org/ws/2004/09/policy"
)

Functions

func Resource

func Resource(uri string) *dom.Element

Resource turns a resource URI into an appropriate DOM element for inclusion in the SOAP header.

Types

type Client

type Client struct {
	OptimizeEnum bool
	Logger       logr.Logger
	// contains filtered or unexported fields
}

Client is a thin wrapper around http.Client.

func NewClient

func NewClient(host *url.URL, username, password string, opts ...Option) *Client

NewClient creates a new wsman.Client.

target must be a URL, and username and password must be the username and password to authenticate to the controller with. If username or password are empty, we will not try to authenticate. If useDigest is true, we will try to use digest auth instead of basic auth.

func (*Client) Close

func (c *Client) Close() error

func (*Client) Create

func (c *Client) Create(resource string) *Message

Create creates a wsman.Message that will update the passed-in resource. The updated resource should be passed in as the only element in the Body of the messate.

func (*Client) Delete

func (c *Client) Delete(resource string) *Message

Delete creates a wsman.Message that will update the passed-in resource. The updated resource should be passed in as the only element in the Body of the messate.

func (*Client) Enumerate

func (c *Client) Enumerate(resource string) *Message

Enumerate creates a wsman.Message that will enumerate all the objects available at resource. If there are many objects, it will arrange for the appropriate series of wsman Pull calls to be performed, so you can be certain that the response to this message has all the objects you specify.

func (*Client) EnumerateEPR

func (c *Client) EnumerateEPR(resource string) *Message

EnumerateEPR creates a message that will enumerate the endpoints for a given resource.

func (*Client) Get

func (c *Client) Get(resource string) *Message

Get creates a wsman.Message that will get an instance at the passed-in resource.

func (*Client) Identify

func (c *Client) Identify(ctx context.Context) (*soap.Message, error)

Identify performs a basic WSMAN IDENTIFY call. The response will provide the version of WSMAN the endpoint speaks, along with some details about the WSMAN endpoint itself. Note that identify uses soap.Message directly instead of wsman.Message.

func (*Client) Invoke

func (c *Client) Invoke(resource, method string) *Message

Invoke creates a wsman.Message that will invoke method on resource. After creating the Message, you need to add the appropriate selectors with msg.Selectors(), and the appropriate parameters with msg.Parameters().

func (*Client) NewMessage

func (c *Client) NewMessage(action string) (msg *Message)

NewMessage creates a new wsman.Message that can be sent via c. It populates the message with the passed action and some other necessary headers.

func (*Client) Open

func (c *Client) Open(ctx context.Context) error

func (*Client) Post

func (c *Client) Post(ctx context.Context, msg *soap.Message) (response *soap.Message, err error)

Post overrides http.Client's Post method and adds digest auth handling and SOAP pre and post processing.

func (*Client) Put

func (c *Client) Put(resource string) *Message

Put creates a wsman.Message that will update the passed-in resource. The updated resource should be passed in as the only element in the Body of the messate.

type Message

type Message struct {
	*soap.Message
	// contains filtered or unexported fields
}

Message represents WSMAN messages.

func (*Message) AddOption

func (m *Message) AddOption(options ...*dom.Element) *Message

AddOption adds any number of elements (created with MakeOption) to the message header.

func (*Message) AddParameter

func (m *Message) AddParameter(parameters ...*dom.Element) *Message

AddParameter adds any number of elements (created with MakeParameter) to the message.

func (*Message) AddSelector

func (m *Message) AddSelector(selector ...*dom.Element) *Message

AddSelector adds any number of elements (created with MakeSelector) to the message.

func (*Message) AddValue

func (m *Message) AddValue(values ...*dom.Element) *Message

func (*Message) EnumItems

func (m *Message) EnumItems() ([]*dom.Element, error)

func (*Message) GHC

func (m *Message) GHC(field string) (string, error)

GHC gets the contents of a specific Header field.

func (*Message) GetItem

func (m *Message) GetItem() (*dom.Element, error)

func (*Message) GetResource

func (m *Message) GetResource() string

func (*Message) InvokeResponse

func (m *Message) InvokeResponse() (*dom.Element, string, error)

func (*Message) MakeOption

func (m *Message) MakeOption(name string) *dom.Element

MakeOption makes an element that can be added as an option to the message header with AddOption.

func (*Message) MakeParameter

func (m *Message) MakeParameter(name string) *dom.Element

MakeParameter makes an element which can be added to the message with AddParameter.

func (*Message) MakeSelector

func (m *Message) MakeSelector(name string) *dom.Element

MakeSelector makes an element that can be added to the message with AddSelector.

func (*Message) MakeValue

func (m *Message) MakeValue(name string) *dom.Element

MakeValue makes an element that can be used to set a new instance value for a Put call.

func (*Message) Options

func (m *Message) Options(opts ...string) *Message

Options is a fast way of creating options that are basically key/value pairs.

func (*Message) Parameters

func (m *Message) Parameters(args ...string) *Message

Parameters sets the parameters for an invoke call. It takes an even number of strings, which should be key:value pairs. It works alot like Options, except it adds the parameters to the Body in the format that WSMAN expects parameter elements to be in.

func (*Message) ResourceURI

func (m *Message) ResourceURI(resource string) *Message

ResourceURI sets the ResourceURI header of the message.

func (*Message) Selectors

func (m *Message) Selectors(args ...string) *Message

Selectors are used to target the resource that Get, Put, and Invoke should work with. They work like Options does, except they add a SelectorSet element with Selectors instead of Options.

func (*Message) Send

func (m *Message) Send(ctx context.Context) (*Message, error)

Send sends a message to the endpoint of the Client it was constructed with, and returns either the Message that was returned, or an error stating what went wrong.

func (*Message) Values

func (m *Message) Values(args ...string) *Message

type Option

type Option func(*Client)

Option for setting optional Client values.

func WithLogger

func WithLogger(logger logr.Logger) Option

func WithUseDigest

func WithUseDigest(useDigest bool) Option