Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 115 lines (95 sloc) 6.113 kB
64a7ee8 @paulj Initial commit of trapeze
authored
1 = Trapeze - AMQP Web Routing
2 Trapeze provides the ability to use your AMQP message queuing infrastructure as
d9468ce @paulj Added a whole bunch more documentation
authored
3 a web router and load balancer. This provides a number of abilities:
64a7ee8 @paulj Initial commit of trapeze
authored
4 * Instant load-balancing
5 * Dynamic routing changes
6
d9468ce @paulj Added a whole bunch more documentation
authored
7 == Installation
8 Trapeze installs as a RabbitMQ plugin. Before setting up Trapeze, you'll need a working
9 RabbitMQ development environment. Setting this up is described at
10 http://www.rabbitmq.com/plugin-development.html#getting-started. Briefly, the process involves:
11 * hg clone http://hg.rabbitmq.com/rabbitmq-public-umbrella
12 * cd rabbitmq-public-umbrella
13 * make co
14 * make
15
16 Once this environment is functional, checkout Trapeze into the umbrella. Assuming that your
17 current working directory is rabbitmq-public-umbrella:
18 * git clone git://github.com/paulj/trapeze.git
19 * cd trapeze
20 * make
21
22 Trapeze can now be run in place by executing:
23 make run
24
25 == Trying it out
26 Assuming that you have a default configuration for RabbitMQ's Mochiweb support (eg, you
27 just checked it out as part of the above steps), Trapeze will be listening on
28 http://localhost:55672. Visiting this URL should result in a 404, since Trapeze currently
29 doesn't have anything to route to!
30
31 To make Trapeze route to an application, you'll need to create a basic application, and run
32 it with a Trapeze-aware handler that understands how to tell Trapeze to route requests to it.
33 Currently, the only handler that can do this is http://github.com/paulj/trapeze-rb, which
34 provides a Ruby Rack handler for making Rack-aware Ruby applications participate in Trapeze
35 routing. An example of using this would be:
36 * git clone git://github.com/paulj/trapeze-rb.git
37 * cd trapeze-rb
38 * rake build
39 * sudo gem install pkg/trapeze-0.1.0.gem
40 * cd samples
41 * trapezerb -R config.ru start
42
43 Following these steps should result in seeing everybody's favourite phrase - "Hello World".
44 At this point, Trapeze would appear to be making something fairly simple (making the webapp
45 browseable) much harder than it needs to be. To show off the actual purpose of Trapeze, you'll
46 need to run more than one application. For your first application, stop the current trapezerb
47 instance, and instead run it as:
48 trapezerb -R config.ru -k "*.localhost.*./.#" -n app1 start
49
50 In a second terminal, change to the trapeze-rb/samples directory again, and execute:
51 trapezerb -R config2.ru -k "*.127.0.0.1.*./.#" -n app2 start
52
53 In your web browser, if you visit http://localhost:55672, then you should see "Hello World". If
54 you visit http://127.0.0.1:55672, you should see "Hello Different World". Trapeze is routing to
55 two different applications, based upon the keys (-k) they provide when they connect. For more
56 details on how to express these keys, see the "Routing Keys" section of this document.
57
58 Note also that each invocation includes a "-n" parameter. This parameter indicates an application
59 name. If two consumers indicate the same application name, then Trapeze will round-robin requests
60 to them. This allows you to bring up multiple instances of your application (potentially on
61 multiple machines), and have the requests balanced between them. To see this in action, try starting
62 both config.ru and config2.ru with no routing key (ie, accept anything), and the same app name:
63 trapezerb -R config.ru -n app1 start
64 (And in another terminal)
65 trapezerb -R config.ru -n app2 start
66
67 Requests should alternate between "Hello World" and "Hello Different World" over a series of
68 refreshes.
69
70 == Routing Keys
71 Trapeze utilises AMQP routing keys in order to find the appropriate application to route a request to.
72 Each requests verb/host/port/path combination is transformed into a routing key that looks like:
73 <verb>.<host parts>.<port>./.<path parts>
74
75 For example, a request to http://localhost:55672 would be transformed into:
76 get.localhost.55672./
77
78 A request to http://127.0.0.1:55672/some/path/file.html would be transformed into:
79 get.127.0.0.1.55672./.some.path.file.html
80
81 Note that the domain and path portions are split by periods. This allows standard AMQP topic-routing to be
82 applied. AMQP topic routing provides a facility to subscribe to topics using routing keys that follow a syntax
83 allowing for sections to be either marked as wildcards or requiring a specific value. The syntax is:
84 * A * indicates that any value is acceptable for this element of the key
85 * A # indicates that any number of period separated values can be accepted
86 * A textual value indicates that an exact match is required
87
88 Examples of matching might be:
89 * To subscribe to anything sent to http://localhost:55672, use "*.localhost.55672./.#". The verb is considered a wildcard, and any number of path parameters are considered acceptable;
90 * To subscribe to example.com and any sub-domain, use "*.#.example.com.*./.#". The verb is considered a wildcard, and any number (including 0) domain parts can precede example.com. Any number of path parameters are acceptable.
91
64a7ee8 @paulj Initial commit of trapeze
authored
92 == Software License
93 Copyright (c) 2009 Paul Jones <paulj@lshift.net>
94 Copyright (c) 2009 LShift Ltd. <query@lshift.net>
95
96 Permission is hereby granted, free of charge, to any person
97 obtaining a copy of this software and associated documentation
98 files (the "Software"), to deal in the Software without
99 restriction, including without limitation the rights to use, copy,
100 modify, merge, publish, distribute, sublicense, and/or sell copies
101 of the Software, and to permit persons to whom the Software is
102 furnished to do so, subject to the following conditions:
103
104 The above copyright notice and this permission notice shall be
105 included in all copies or substantial portions of the Software.
106
107 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
108 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
109 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
110 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
111 HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
112 WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
113 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
d9468ce @paulj Added a whole bunch more documentation
authored
114 DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.