Direction

Life got crazy (moved to a new house), and I haven't been able to spend as much time on this as I would like. So, here's a dump of where I'm thinking for this project.

As I get into this more and more, it seems like the SOAP1.2 part of this project is pretty ambitious. Given the NaHi (the main developer of SOAP4R) hasn't touched SOAP 1.2 yet, I'm skeptical that I'll be able to integrate anything nicely into his library that will handle the new spec. That said, for my project, I've been able to generate stub code from the SOAP4R library, which means that we aren't doing anything that is technically new in SOAP1.2. Additionally, I'm really only interested in the MTOM attachment mechanism (now that DIME is officially DOA), not the down and dirty details of SOAP. This all leads me to think that the value added here would be to create a wrapper for the SOAP4R library that runs a transform on the incoming and outgoing messages and:

1. Changes the namespaces to indicate SOAP1.2 messages and trigger the correct parser on the receiving end.
2. Makes any other changes to a SOAP 1.1 message to make it semantically acceptable to a SOAP 1.2 parser.
3. Extracts the Base64Encoded message parts, optimizes them and creates the correct envelope structure (the actual implementation of the MTOM specification).

Again, from the specification, I'm not sure what the functional relationship between MTOM and SOAP1.2 is, other than they were both released at the same time. Given that MTOM and XOP operate outside of the SOAP message spec, and don't alter the non Base64Encoded parts in any appreciable way, making a message completely compliant with the SOAP1.2 spec may not be necessary at all (which would reduce the amount of work on my end by an order of magnitude.)

Stay tuned: next up is creating the wrapper class and trying to clean this up so that it might be useful to someone on another project.

Ruby on Rails + SOAP4R server

And I thought it would be hard! After scouring the web and finding nothing on how to integrate the SOAP4r stub code onto rails (to create a SOAP server on top of the rails framework), I finally figured out a way to do it. The trick was in the server/servant files that are generated by wsdl2ruby; by diving down into the class definitions I was able to pull out the atomic components of the servant and stick them in a rails project. Here's the breakdown:

First, I created an empty rails project using the scaffold generator. I set it up with a base rails class that will act as a router to grab the post data and pass it through to the SOAP router and parser. What we are interested in is the 'create' method in the applicationController that rails generates (which using the REST architecture is where the HTTP POST command is captured.) I'll walk through the raw code first, but keep in mind that I plan to wrap all of this into a helper class for cleanliness.

def create
  @router = ::SOAP::RPC::Router.new('rubynode')
  servant = NetworkNodePortType2.new
  res = ''
  req = request

@router is the SOAP4R router that takes an input post dump and parses it using the type definitions created by WSDL2RUBY. The 'servant' is an instance of the basic class generated by the WSDL2RUBY script. The servant class contains the application logic for generating the return data from the parameters in the request message (this class is dummy generated by the WSDL2RUBY script, and must be filled in; check out the doc/literal example in the soap4r install folder for the specific example.) The 'res' variable will be used to hold the SOAP response message, but for now is nilled out, and the 'req' variable is a copy of the rails generated 'request' data structure that contains the raw POST dump and other HTTP header info needed later on.

  NetworkNodePortType2::Methods.each do definitions
    opt = definitions.last
    if opt[:request_style] == :document
      @router.add_document_operation(servant, *definitions)
    else
      @router.add_rpc_operation(servant, *definitions)
    end
  end

The above section of code is the intialization stub taken from the generated server app class. This simply initializes the operation definitions from the WSDL and binds them to the servant methods through the router. That is, the 'definitions' include the input and output message types and bindings for each operation defined in the WSDL. This code sets up the path to the application logic (in the servant class) when a defined message is recieved.

  conn_data = ::SOAP::StreamHandler::ConnectionData.new
  setup_req(conn_data, req)
  @router.external_ces = nil
  conn_data = @router.route(conn_data)
  input = setup_res(conn_data, req, res)

  respond_to do |format|
    format.xml { render :xml => input }
  end
end

def setup_req(conn_data, req)
  conn_data.receive_string = req.raw_post
  conn_data.receive_contenttype = req.content_type
  conn_data.soapaction = nil
end

def setup_res(conn_data, req, res)
  res = conn_data.send_string
end

Here's the meat of the code. First, the 'conn_data' variable contains the streamhandler connection data type, which is used to house the raw POST dump and the HTTP header info. Next, we map the 'request' information into the 'conn_data' structure and then pass it into the router. We then grab the response from the conn_data structure and pass it to rails XML handler to be returned.

And there you go: a decent first shot at integrating the SOAP4R library/generated stub code into a working Ruby on Rails web service implementation. Incidentally, a wrapper class using these basic tools would be a perfect place to put the MTOM hooks: all that would need to be done is grab the raw SOAP response message and run a transform on the 'base64encoded' parts.

Two Steps Back, Three Steps Forward

Alrighty, well I had a change of plans. After thinking about this for a while and doing some research, the wsdl2ruby tool finally generates some code. I ended up changing the WSDL in a couple of places to get it to generate code successfully:

1. Changed xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" namespace decleration to xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
   
2. Changed corresponding 'soap12:' tags to 'soap:'

So here's the updated WSDL. Aside from the SOAP12 changes, I had to add back in some fault messages that I'd removed in error, ooops. Turns out that was generating a lot of the errors.

Now it is clear that we aren't doing much in the WSDL that isn't supported by SOAP4r - or at least enough to generate the WSDL. So, the real questions is: how much has the functional SOAP layer changed, and how much of a pain is it going to be to alter the existing soap4r code to add these things? At this point, I'm not too worried about making this packageable, or fully implementing the spec: just what I would need to add in order for MTOM to work and allow me to bind to our .NET node running the WSDL.

One outstanding question: will the standalone server allow more than one operation in the portType def?

Kickoff

Welcome all! This blog will document my efforts to create/extend MTOM (Message Transmission and Optimization Mechanism) functionality in Ruby (mainly through the SOAP4R library). MTOM was added as a W3C recommendation with SOAP 1.2 back almost a year ago and was created to allow for inline attachment of payloads in a SOAP message, without having to hack the stack with DIME or SwA. MTOM (and the optimization component XOP) are pretty cool, as the user at either end sees only a unified infoset, with binary represented by the xsd:base64encoded type. There are no hooks, one simply has stick the binary data in a base64encoded element and MTOM/XOP takes over the rest. Currently, MTOM is implemented in .NET 2 and Xfire, thought I haven't explored any other toolkits, so it may be elsewhere too.

This blog will document my progress, and hopefully provide some needed assistance to people who are stuck down the black hole called ruby SOAP support.