AW: [Openinteract-dev] SOAP as a content generator

[Kutter M. <mar...@er...>]

Hi Cris !

Here are some more details:

>> There are some limitations in the current implementation:
>>
>> 1. Complex datatypes are not supported in SOAP requests. This is due to
>> the
>> simple mapping of request parameters to OpenInteract actions - and a
>> similarity to WWW forms (have you ever seen a complex type in a HTML form
>> ?). However, SOAP responses may be of arbitrary complexity.
	
>I'm not sure I understand this. Do you mean that SOAP::Lite supports them
>but OI doesn't?

Well, I guess that no OI programmer sets up his actions to deal with complex
datatypes, because these cannot be supplied by HTML-Forms - something like
the example below is probably never returned by a HTML form.

{ book => {
    isbn => 1234567,
    author => 'Cris Winters',
    chapters => [
      "Introduction to OI",
      "Programmer's Guide" ]
    }
}

My current SOAP-to-action parameter mapping just takes all parameters from
the SOAP request and sets the action parameters accordingly.

In theory, there would be no problem in handling complex types - at the cost
of loosing the opportunity to make up a WWW-form interface that provides the
same functionality.
Actually, I'm not quite sure if I do the mapping right...

>> 2. Compression, XML encryption and SOAP authentication are currently not
>> supported. This may change for compression and XML encryption, but SOAP
>> authentication is not supported by SOAP::Lite and I don't feel like
>> implementing a new SOAP toolkit.
>
>If authentication is part of the request would it be possible for us to
>pull the auth data out and do it ourselves? For apache1/apache2 we could
>even create an auth handler to deal with this (similar to
>Apache::OI2::Auth)

SOAP authentication (that is, sendingcredentials as part of the SOAP
message) is currently not supported by SOAP::Lite - that's all. HTTP
authentication is no problem.

>> 3. The URL rewrite requires SOAP clients to send appropriate namespace
>> uris.=
>> This is no major drawback - .NET does the same.
>
>Not sure what this means either.

SOAP messages may contain so-called namespace URIs, denoting to which target
namespace the message should map to. 

Basically said, a SOAP request contains 
- the SOAP envelope,
- a SOAP message (usually a method call)
- message parameters 

The SOAP message and the parameters may be additionally qualified by a
namespace URI (e.g. "http://openinteract.org/WebService").

.NET Web Services won't accept messages without namespace URIs, so this
doesn't mean demanding something new from the world...

>> 4. There currently is no WSDL support.
>
>Is this difficult to implement? Maybe we can have optional hooks for
>actions to provide the necessary metadata?

More or less. SOAP::Lite has only limited support for WSDL, and WSDL support
in perl is generally difficult to implement, because of the need to define
strong-typed message elements (number, string etc.) unknown to perl.
A WDSL file could define something like a method called "Date" returning the
date in several fields like 

DayOfWeek => 'Wed',	# string
DayOfMonth => '28',	# number
Month => 'May',		# string
Year => '2004'		# number

Complete WSDL support would mean

- request typechecking (against SOAP types, not perl datatypes)
- request validation (does the request contain the elements defined in WSDL
?)
- maybe parameter mapping (...maybe mapping of complex types to simple ones
with some config directives in the action config ?)
- response templating (providing a kind of template for the response)
- maybe output parameter mapping (same as for request params...)
- response typechecking (make sure we don't params of the wrong type back).
 
This is not *that* hard to do, but it's a bunch of work.

...I'm currently working (with little involvement) on WSDL support, but it
may take a while and maybe never cover the subject completely...

>> The least obvious parts in this implementation are 3.3 (the URL rewrite
>> for
>> request-to-action mapping) and 4.1.1 (the content generation).
>>
>> A look at URL rewriting:
>>
>> URL rewrite seems desirable - this allows to set up a WebService in
>> parallel
>> to a WWW frontend (e.g. http://www.myhost.org/OpenInteract/ for the WWW
>> frontend, http://www.myhost.org/OpenInteractWebService/ for the SOAP
>> frontend).
>> Moreover, it allows to map SOAP requests accepted at exactly _one_ URL to
>> different OpenInteract actions based on the namespace uri of the request.
>
>Hmmmm... this is an interesting idea, being able to differentiate content
>generators based on the top-level namespace rather than the action + task
>mapping. It would not be too difficult to implement either. I'll create a
>JIRA task for investigating this...

Actually, URL rewrite is almost necessary if you don't want your action
tasks to be one flat list: A Web Service usually has *one* URL to connect
to, with lots of method (correspond to OI tasks) to call. OI, in contrast,
has many URLs which map to different actions and tasks.

The (simple) URL rewrite I got up by now just rewrites the URL to the SOAP
namespace URI + method name. The SOAP namespace URI must be the same as the
base URL for an OI action would be. This means, if you got a OI action
saying "Hello world" set up at "http://mymachine.org/hello/world" with
"hello" as action and "world" as task, and a SOAP Webservice set up at
"http://mymachine.org/WebService/" you would have to send a SOAP request for
the method "world" qualified by the namespace URI
"http://mymachine.org/hello".

A more sophisticated URL rewrite mechanism could be based on config file -
but my simple one is all I need by now.

>> A look at content generation:
>>
>> The content generator currently takes the action return parameters and
>> - creates a SOAP::Fault response if an error_msg is set
>> - encodes _all_ return parameters (aside from ACTION) into a SOAP
>> response,
>> automatically encoding SPOPS objects, hash and list references correctly.
>
>
>Excellent! This is exactly what I had in mind.
>
>> Hereby SPOPS objects are transformed into Hash refs containing all fields
>> of the object (nobody but a perl SOAP client could handle perl
>> objects...).
>
>Absolutely, makes perfect sense.
>
>> Theres are some caveats in this kind of content generation:
>> 1. The soap response may include more information than the WWW response -
>> this occurs if you filter your action response with the template.
>
>That's okay. I assume the client only uses what data it needs.
>
>> 2. Lists may be badly encoded if they contain data of more than one SOAP
>> datatype (number, string and ? I forgot about is...). This is a SOAP
>> limitation.
>
>So if you return a list of 'news' SPOPS objects (which just get hashified)
>SOAP gets confused? Or something else...?

No, not just. SOAP only requires list elements to be of the same type, so
mixing numbers with strings may result in unpredictable behaviour. This is
due to the nature of SOAP messages, which encode list as something like 

<list of numbers>
 <element>1</element>
 <element>2</element>
</list>

(well, that's actually not what SOAP messages look like, but it basically is
how list encoding works...).
Lists of SPOPS objects are no problem as long as the SPOPS objects are of
the same class - I don't know how it is with SPOPS objects of different
classes in one list.

>> Interested ?
>
>Heck yes! This would be a really snazzy thing to show people at the
>tutorial I'm doing at YAPC::NA in June as well. (No pressure or
>anything...)

I can post the OI-1.99_03 stuff to the list by now (along with an example
client and some docs). 
I'm not sure, wether I got .NET interopability working by now - I have no
means to test it. And, sure, I guess some serious bugs are lurking around
somewhere, too...

>Thanks for your hard work!

Apreciated. But don't expect too much - I implement the stuff because I need
it, and YAGNI is one of my working principles...

Regards,

Martin Kutter