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