Changes between Version 90 and Version 91 of XmlRpcPlugin


Ignore:
Timestamp:
Apr 19, 2012, 9:28:42 AM (3 years ago)
Author:
rjollos
Comment:

Conent moved to XmlRpcPlugin/Ruby.

Legend:

Unmodified
Added
Removed
Modified
  • XmlRpcPlugin

    v90 v91  
    224224
    225225=== Using from Ruby ===
    226 You can either use the XMLRPC functionality included in the [http://ruby-doc.org/stdlib/libdoc/xmlrpc/rdoc/index.html Ruby Standard Library] or [/attachment/wiki/XmlRpcPlugin/trac4r.tar.gz download the trac4r library] which does all the trivial stuff for you.
    227 
    228 please refer to the '''SSL Support''' section if you need one.
    229 
    230 ==== trac4r Example ====
    231 This example uses trac4r:
    232 {{{
    233 #!ruby
    234 require 'trac4r/trac'
    235 # initialize the connection (username and password can be ommitted if not needed, but most of the time you will need them if anonymous doesn't have XMLRPC permissions)
    236 trac = Trac.new "https://dev.example.com/trac/my_awesome_project", "myusername", "mypassword"
    237 # get a list of all tickets (as an array of numbers)
    238 trac.tickets.list :include_closed => true # this is the default anyway
    239 # get all the tickets
    240 # NOTE: the results here are cached, so you can call it as often as you want without producing traffic more than once.
    241 # use ":cached_results => false" to get the latest version
    242 trac.tickets.get_all :include_closed => true
    243 # get a single ticket
    244 ticket = trac.tickets.get 5
    245 # print the data
    246 puts "Title: #{ticket.summary}"
    247 puts "Description: #{ticket.description}"
    248 puts "Milestone: #{ticket.milestone}"
    249 puts "Status: #{ticket.status}"
    250 puts "Type: #{ticket.type}"
    251 puts "Priority: #{ticket.priority}"
    252 # get a list of all wiki pages
    253 trac.wiki.list
    254 # download one page
    255 trac.wiki.get_html "SomeRandomPageName" # HTML version
    256 trac.wiki.get_raw "AnotherRandomPageName" # trac syntax version (e.g. for editing)
    257 # for previews use
    258 trac.wiki.raw_to_html "content of a page in [wiki:WikiFormatting Trac syntax] as a ''String''"
    259 # to post a page use
    260 trac.wiki.put "NameOfThePage", "content in Trac syntax"
    261 # list the attachments of a wiki page
    262 trac.wiki.attachments "NameOfThePage"
    263 # save an attachment
    264 File.new("my_cool_document","w") do |f|
    265   f.write trac.wiki.get_attachment "NameOfThePage", "my_cool_document.pdf"
    266 end
    267 
    268 # upload an attachment to the page above
    269 page = "NameOfThePage"
    270 fn = "my_nice_doc.pdf"
    271 fh = File.new(fn, "rb")
    272 sdata = fh.read
    273 data = XMLRPC::Base64.new(sdata)
    274 result = trac.wiki.put_attachment(page, name, "uploaded via ruby script", data)
    275 # the correct result should be the name of the file:
    276 puts "ERROR: uploading #{name} didn't work properly!" if result != name
    277 }}}
    278 
    279 Also see the included Documentation in trac4r/doc
    280 
    281 If you need to do a custom query do
    282 {{{
    283 #!ruby
    284 trac.query("system.getAPIVersion")
    285 }}}
    286 The first argument is the method name, all other arguments are directly passed to XMLRPC.
    287 For this example of cause you could do `trac.api_version` instead ;)
    288 
    289 If you have any problems with trac4r you can email me: niklas.cathor (eat) gmail dot com
    290 
    291 ==== xmlrpc Example ====
    292 
    293 An example using XML-RPC directly with Ruby to append to a wiki page:
    294 {{{
    295 #!ruby
    296 require 'xmlrpc/client'
    297 user = "username"
    298 password = "password"
    299 page_name = "SandBoxRPC"
    300 new_content = "\n\nMy new content"
    301 new_comment = "Adding new content from ruby"
    302 
    303 server = XMLRPC::Client.new2("https://#{user}:#{password}@trac.server.com/trac/login/xmlrpc")
    304 content = server.call("wiki.getPage", page_name) + new_content
    305 server.call("wiki.putPage", page_name, content, {"comment" => new_comment})
    306 }}}
    307 
    308 ==== SSL Support + X509 ====
    309 The standard ruby xmlrpc client for some reason does not support SSL at all.
    310 In order to be able to use the XMLRPC over SSL with both
    311  * Client Certificate authentication
    312  * Basic Authentication
    313 One must do as follows.
    314 
    315 in order to proceed, you should have:
    316  * ca certificate in .pem format
    317  * personal certificate + RSA key in .p12 format (and its password, of course)
    318  * patched version of xmlrpc/client.rb
    319  * patched version of trac4r
    320  * username/password (for basic authentication)
    321 
    322 Assuming you have the above, and your ca and user certificates are respectively:
    323 {{{
    324 ~/.openssl/cacert.pem
    325 ~/.openssl/certkey.p12
    326 }}}
    327 ===== The Instructions =====
    328  1. apply the patches:
    329    1. to the [attachment:"xmlrpc-client.SSL.patch" xmlrpc client]
    330 {{{
    331 sudo su -
    332 cd /usr/lib/ruby/1.8/
    333 patch -p0  < /path/to/xmlrpc-client.SSL.patch
    334 }}}
    335    1. to the [attachment:"trac4r-1.2.3.SSL.patch" trac4r gem]
    336 {{{
    337 sudo su -
    338 cd /var/lib/gems/1.8/gems/
    339 patch -p0  < /path/to/trac4r-1.2.3.SSL.patch
    340 }}}
    341  1. create a .yml file called {{{~/.trac/creds.yml}}} of the following structure:
    342 {{{
    343 ---
    344 tracurl: https://yourserver.yourdomain/yourproject
    345 tracuser: yourwebuser
    346 tracpass: yourwebpassword
    347 certkey: /home/youruser/.openssl/certkey.p12
    348 cacert: /home/youruser/.openssl/cacert.pem
    349 keypass: yourkeypassword
    350 }}}
    351    * do not forget to chmod the personal files to 600 or 400
    352  1. use the data in the code
    353 {{{
    354 #!ruby
    355 require 'yaml'
    356 require 'openssl'
    357 require 'xmlrpc/client'
    358 require 'trac4r'
    359 
    360 ## read the data from yaml:
    361 $ymlname= "#{ENV['HOME']}/.trac/creds.yml"
    362 if !File.exists?($ymlname)
    363     raise "Cannot open credentials file!"
    364 end
    365 begin
    366     $vars = YAML::load_file($ymlname)
    367 rescue Exception => e
    368     raise "Cannot load credentials file #{$ymlname}: #{e.message}\nTrace: #{e.stacktrace}"
    369 end
    370 
    371 ## extract the certificate, and the key from the fles.
    372 pkcs = OpenSSL::PKCS12.new(File.open($vars['certkey']),$vars['keypass'])
    373 cert = pkcs.cert
    374 key = pkcs.key
    375 ## connect to the server
    376 trac = Trac.new($vars['tracurl'], $vars['tracuser'], $vars['tracpass'], $vars['cacert'], cert, key)
    377 ## from now you can refer to the connection as open (or query it)
    378 ## use the API as explained above.
    379 }}}
    380 
    381 '''NOTE:''' The working environment of the code (trac4r + ssl) is:
    382  * Debian/GNU system: {{{Linux hostname 2.6.26-2-686 #1 SMP Mon Jun 21 05:58:44 UTC 2010 i686 GNU/Linux}}}
    383  * OpenSSL: {{{OpenSSL 0.9.8g 19 Oct 2007}}}
    384  * Ruby: {{{ruby 1.8.7 (2008-08-11 patchlevel 72) [i486-linux]}}}
    385  * The certificates have been issued by the above OpenSSL setup.
     226
     227See XmlRpcPlugin/Ruby.
    386228
    387229=== API Usage ===