1# Rabbit Hole, a RabbitMQ HTTP API Client for Go 2 3This library is a [RabbitMQ HTTP API](https://raw.githack.com/rabbitmq/rabbitmq-management/rabbitmq_v3_6_0/priv/www/api/index.html) client for the Go language. 4 5## Supported Go Versions 6 7Rabbit Hole supports the last 2 stable Go versions, as well as the version in development (a.k.a. master). 8 9 10## Supported RabbitMQ Versions 11 12 * RabbitMQ `3.7.x` is the primary target series 13 * Most API functions would work against RabbitMQ `3.6.x` nodes or earlier but those releases are officially out of support 14 15All versions require [RabbitMQ Management UI plugin](https://www.rabbitmq.com/management.html) to be installed and enabled. 16 17 18## Project Maturity 19 20Rabbit Hole is a mature library (first released in late 2013) 21designed after a couple of other RabbitMQ HTTP API clients with stable 22APIs. Breaking API changes are not out of the question but not without 23a reasonable version bump. 24 25It is largely (80-90%) feature complete and decently documented. 26 27 28## Change Log 29 30If upgrading from an earlier release, please consult with 31the [change log](https://github.com/michaelklishin/rabbit-hole/blob/master/ChangeLog.md). 32 33 34## Installation 35 36``` 37go get github.com/michaelklishin/rabbit-hole 38``` 39 40 41## Documentation 42 43### API Reference 44 45[API reference](http://godoc.org/github.com/michaelklishin/rabbit-hole) is available on [godoc.org](http://godoc.org). 46 47Continue reading for a list of example snippets. 48 49### Overview 50 51To import the package: 52 53``` go 54import ( 55 "github.com/michaelklishin/rabbit-hole" 56) 57``` 58 59All HTTP API operations are accessible via `rabbithole.Client`, which 60should be instantiated with `rabbithole.NewClient`: 61 62``` go 63// URI, username, password 64rmqc, _ = NewClient("http://127.0.0.1:15672", "guest", "guest") 65``` 66 67TLS (HTTPS) can be enabled by adding an HTTP transport to the parameters 68of `rabbithole.NewTLSClient`: 69 70``` go 71transport := &http.Transport{TLSClientConfig: tlsConfig} 72rmqc, _ := NewTLSClient("https://127.0.0.1:15672", "guest", "guest", transport) 73``` 74 75RabbitMQ HTTP API has to be [configured to use TLS](http://www.rabbitmq.com/management.html#single-listener-https). 76 77 78### Getting Overview 79 80``` go 81res, err := rmqc.Overview() 82``` 83 84### Node and Cluster Status 85 86``` go 87xs, err := rmqc.ListNodes() 88// => []NodeInfo, err 89 90node, err := rmqc.GetNode("rabbit@mercurio") 91// => NodeInfo, err 92``` 93 94 95### Operations on Connections 96 97``` go 98xs, err := rmqc.ListConnections() 99// => []ConnectionInfo, err 100 101conn, err := rmqc.GetConnection("127.0.0.1:50545 -> 127.0.0.1:5672") 102// => ConnectionInfo, err 103 104// Forcefully close connection 105_, err := rmqc.CloseConnection("127.0.0.1:50545 -> 127.0.0.1:5672") 106// => *http.Response, err 107``` 108 109 110### Operations on Channels 111 112``` go 113xs, err := rmqc.ListChannels() 114// => []ChannelInfo, err 115 116ch, err := rmqc.GetChannel("127.0.0.1:50545 -> 127.0.0.1:5672 (1)") 117// => ChannelInfo, err 118``` 119 120 121### Operations on Vhosts 122 123``` go 124xs, err := rmqc.ListVhosts() 125// => []VhostInfo, err 126 127// information about individual vhost 128x, err := rmqc.GetVhost("/") 129// => VhostInfo, err 130 131// creates or updates individual vhost 132resp, err := rmqc.PutVhost("/", VhostSettings{Tracing: false}) 133// => *http.Response, err 134 135// deletes individual vhost 136resp, err := rmqc.DeleteVhost("/") 137// => *http.Response, err 138``` 139 140 141### Managing Users 142 143``` go 144xs, err := rmqc.ListUsers() 145// => []UserInfo, err 146 147// information about individual user 148x, err := rmqc.GetUser("my.user") 149// => UserInfo, err 150 151// creates or updates individual user 152resp, err := rmqc.PutUser("my.user", UserSettings{Password: "s3krE7", Tags: "management,policymaker"}) 153// => *http.Response, err 154 155// creates or updates individual user with no password 156resp, err := rmqc.PutUserWithoutPassword("my.user", UserSettings{Tags: "management,policymaker"}) 157// => *http.Response, err 158 159// deletes individual user 160resp, err := rmqc.DeleteUser("my.user") 161// => *http.Response, err 162``` 163 164``` go 165// creates or updates individual user with a SHA256 password hash 166hash := SaltedPasswordHashSHA256("password-s3krE7") 167resp, err := rmqc.PutUser("my.user", UserSettings{ 168 PasswordHash: hash, 169 HashingAlgorithm: HashingAlgorithmSHA256, 170 Tags: "management,policymaker"}) 171// => *http.Response, err 172``` 173 174 175### Managing Permissions 176 177``` go 178xs, err := rmqc.ListPermissions() 179// => []PermissionInfo, err 180 181// permissions of individual user 182x, err := rmqc.ListPermissionsOf("my.user") 183// => []PermissionInfo, err 184 185// permissions of individual user in vhost 186x, err := rmqc.GetPermissionsIn("/", "my.user") 187// => PermissionInfo, err 188 189// updates permissions of user in vhost 190resp, err := rmqc.UpdatePermissionsIn("/", "my.user", Permissions{Configure: ".*", Write: ".*", Read: ".*"}) 191// => *http.Response, err 192 193// revokes permissions in vhost 194resp, err := rmqc.ClearPermissionsIn("/", "my.user") 195// => *http.Response, err 196``` 197 198 199### Operations on Exchanges 200 201``` go 202xs, err := rmqc.ListExchanges() 203// => []ExchangeInfo, err 204 205// list exchanges in a vhost 206xs, err := rmqc.ListExchangesIn("/") 207// => []ExchangeInfo, err 208 209// information about individual exchange 210x, err := rmqc.GetExchange("/", "amq.fanout") 211// => ExchangeInfo, err 212 213// declares an exchange 214resp, err := rmqc.DeclareExchange("/", "an.exchange", ExchangeSettings{Type: "fanout", Durable: false}) 215// => *http.Response, err 216 217// deletes individual exchange 218resp, err := rmqc.DeleteExchange("/", "an.exchange") 219// => *http.Response, err 220``` 221 222 223### Operations on Queues 224 225``` go 226qs, err := rmqc.ListQueues() 227// => []QueueInfo, err 228 229// list queues in a vhost 230qs, err := rmqc.ListQueuesIn("/") 231// => []QueueInfo, err 232 233// information about individual queue 234q, err := rmqc.GetQueue("/", "a.queue") 235// => QueueInfo, err 236 237// declares a queue 238resp, err := rmqc.DeclareQueue("/", "a.queue", QueueSettings{Durable: false}) 239// => *http.Response, err 240 241// deletes individual queue 242resp, err := rmqc.DeleteQueue("/", "a.queue") 243// => *http.Response, err 244 245// purges all messages in queue 246resp, err := rmqc.PurgeQueue("/", "a.queue") 247// => *http.Response, err 248 249// synchronises all messages in queue with the rest of mirrors in the cluster 250resp, err := rmqc.SyncQueue("/", "a.queue") 251// => *http.Response, err 252 253// cancels queue synchronisation process 254resp, err := rmqc.CancelSyncQueue("/", "a.queue") 255// => *http.Response, err 256``` 257 258 259### Operations on Bindings 260 261``` go 262bs, err := rmqc.ListBindings() 263// => []BindingInfo, err 264 265// list bindings in a vhost 266bs, err := rmqc.ListBindingsIn("/") 267// => []BindingInfo, err 268 269// list bindings of a queue 270bs, err := rmqc.ListQueueBindings("/", "a.queue") 271// => []BindingInfo, err 272 273// list all bindings having the exchange as source 274bs1, err := rmqc.ListExchangeBindingsWithSource("/", "an.exchange") 275// => []BindingInfo, err 276 277// list all bindings having the exchange as destinattion 278bs2, err := rmqc.ListExchangeBindingsWithDestination("/", "an.exchange") 279// => []BindingInfo, err 280 281// declare a binding 282resp, err := rmqc.DeclareBinding("/", BindingInfo{ 283 Source: "an.exchange", 284 Destination: "a.queue", 285 DestinationType: "queue", 286 RoutingKey: "#", 287}) 288// => *http.Response, err 289 290// deletes individual binding 291resp, err := rmqc.DeleteBinding("/", BindingInfo{ 292 Source: "an.exchange", 293 Destination: "a.queue", 294 DestinationType: "queue", 295 RoutingKey: "#", 296 PropertiesKey: "%23", 297}) 298// => *http.Response, err 299``` 300 301### Operations on Shovels 302 303``` go 304qs, err := rmqc.ListShovels() 305// => []ShovelInfo, err 306 307// list shovels in a vhost 308qs, err := rmqc.ListShovelsIn("/") 309// => []ShovelInfo, err 310 311// information about an individual shovel 312q, err := rmqc.GetShovel("/", "a.shovel") 313// => ShovelInfo, err 314 315// declares a shovel 316shovelDetails := rabbithole.ShovelDefinition{SourceURI: "amqp://sourceURI", SourceQueue: "mySourceQueue", DestinationURI: "amqp://destinationURI", DestinationQueue: "myDestQueue", AddForwardHeaders: true, AckMode: "on-confirm", DeleteAfter: "never"} 317resp, err := rmqc.DeclareShovel("/", "a.shovel", shovelDetails) 318// => *http.Response, err 319 320// deletes an individual shovel 321resp, err := rmqc.DeleteShovel("/", "a.shovel") 322// => *http.Response, err 323 324``` 325 326### Operations on cluster name 327``` go 328// Get cluster name 329cn, err := rmqc.GetClusterName() 330// => ClusterName, err 331 332// Rename cluster 333resp, err := rmqc.SetClusterName(ClusterName{Name: "rabbitmq@rabbit-hole"}) 334// => *http.Response, err 335 336``` 337 338### HTTPS Connections 339 340``` go 341var tlsConfig *tls.Config 342 343... 344 345transport := &http.Transport{TLSClientConfig: tlsConfig} 346 347rmqc, err := NewTLSClient("https://127.0.0.1:15672", "guest", "guest", transport) 348``` 349 350### Changing Transport Layer 351 352``` go 353var transport http.RoundTripper 354 355... 356 357rmqc.SetTransport(transport) 358``` 359 360 361## CI Status 362 363[![Build Status](https://travis-ci.org/michaelklishin/rabbit-hole.svg?branch=master)](https://travis-ci.org/michaelklishin/rabbit-hole) 364 365 366## Contributing 367 368See [CONTRIBUTING.md](https://github.com/michaelklishin/rabbit-hole/blob/master/CONTRIBUTING.md) 369 370 371## License & Copyright 372 3732-clause BSD license. 374 375(c) Michael S. Klishin, 2013-2019. 376