Communications features of caravan using http 1.1 protocol. ---------------------------------------------------------- HTTP 1.1 is designed for fast and efficient communications with flexibility to extent it as needed. HTTP over tcpip/ip is already the preferred protocol the world over. Caravan is designed with strong support for communications and messaging applications. It can use FTP, HTTP or SMTp in any application but the focus is on HTTP. Caravan provides the objects needed to use http in your applications painlessly. Caravan is fully http/1.1 compliant and implements additional sub protocol http-resume for transfering large bolcks of data from server to server using not so reliable links. Introduction to HTTP: In http, a request is made to another http compliant application using a get,put,post or head method. The response is returned as another http message. A http message contains a list of headers followed by an optional body. Both requests and responses are in the form of http messages. This is an http get request, it has no body: HTTP/1.1 GET /stockquotes.html user-agent:blah blah accept : * This is an HTTP response, it has a body: HTTP/1.1 200 OK content-type: text/html ...body.... ............. If the request uses PUT or POST method, then it will also require a body. The name: value pairs are the headers and there can really be many headers in a typical request or response. For example the 'content-type' header is used to tell the recipient what type of content is in the body. This is what helps the browser to display an image properly instead of a jumble characters. The caravan http engine implements the http protocol with all its intricacies leaving the programmer with the task of creating requests and reading the responses or reading the requests and creating the responses, depending on whether caravan is being used as a client or a server. The simplest way to access an http resource using caravan is to use the file object. File object can also be used to access local files or ftp data. Example : using 'GET' method to access remote document: file remote_document="http://www.server.com/data.txt" This will cause caravan to 'GET' the file "data.txt" from www.server.com, Which involves sending an http request and then reading the response from the server. This file can then used as a local file. In addition an object of name '_reply' will also be created which can be examined to get the response headers from the server. Example : _reply(error) indicates some error has occurred and the request was not successful. _reply(_responsecode) will give you the status code (like 200 for OK) from server. For example '301' or '302' means that the resource has moved to a new location which is given in the _reply(location) and the request has to be retried as: file remote_doment=_reply(location). There are other headers usually, which tells you the 'content-type', 'last-modified' time etc. For more information about http headers refer to http headers. In some cases the 'GET' will not work without additional headers in the request. To make your request more specific you can create an object of name _request before creating the file object and set the header values as needed. example: var _request _request(accept)="image/gif";// tells server to respond with a gif image _request(_port)="88" file x="http://www.pictures.com/picture" Similarly when an http client access your server you will get an object named 'request', which contains the request headers. When you dispatch the resource to the client you can set the response headers by creating the _response object Example : Use of request and _response objects: var _response; _response(content-type)="text/plain" _response(cache-control)="no-cache" _response(_responsecode)="200";// http-ok status "hello world\n" "your browser is ";request(user-agent);"!\n" To sum up 1.When you get a request from client The request headers are in the 'request' object Your response headers are to be set in the '_response' object 2.When you make a request Your request headers to be set in the '_request' object Response headers from the server is in the '_reply' object. You can also make PUT or POST requests in the same way -- only you have to do some more things; before making the file object you have to set the '_httpmethod' property in the _request : _request(_httpmethod)="post" Of course when you put or post you have a message body to put or post. So you have to set it in the '_content' property of the _request File myfile="d:/test/test.doc" _request(content)=myfile(file) Now you can execute the request : file remote_document="http://www.server.com/testput.html" So by creating a '_request' and using a file object you can access almost any http resource. This is the most general way to use http. Also caravan provides a form object which does the above automatically for you avoiding the creation of _request. A form object is created as : form x; you have to set the _url,_server,_port properties of a form and call the put or post method. form x x(_url)="testpost.html" x(_port)="80" x(_server)="www.server.com" x(_content)=myfile(file) x(put) ;// call put // or x(post);// call post Same _reply object will appear after the put or post and has to be used as explained above. Form objects can also morph into seperate threads if the put or post is not called explicitly. The put and post operations will not delay your script, but it is not so reliable if you dont examine the _reply. That is, form objects which have been created but not posted will note get garbage collected, but will come alive as aback ground thread to complete the request. example: put or post will happen after the execution of script in a separate thread. x(_url)="testpost.html" x(_port)="80" x(_server)="www.server.com" x(_content)=myfile(file) over Advantage of the using the form method is that objects can be serialised directly by using the post method; form x=myobject() x(_url)="testpost.html" x(_port)="80" x(_server)="www.server.com" x(post) In this case many things happen - the object myobject is send to the server and the server can get all the properties as if a form has been posted to it from browser. Example : To send record from a caravan table table tbl=cab.files files(recordno)="500" form x=tbl() x(_url)="testpost.html" x(_port)="80" x(_server)="www.server.com" x(post) form is just a wrapper which creates the _request object implicitly. This is all you need to understand for building powerful communications systems using caravan. Though seemingly simple, an advanced protocol like http/1.1 is there for you to use in innovative ways. Here is an example : Create a Proxy server using caravan: ========================================================= Caravan is not a proxy server by design, but you can make one with only five lines of code! The basics: ========== When a browser sends a request via a proxy the url is of the form "http://domain/home.html" but when it sends it to an origin serverthe url is /home.html. The 'get' request to an origin server starts likes this A: http/1.1 get /home.html or if using a proxy it will be B: http/1.1 get http://domain/home.html When a caravan server is used as a proxy by a browser, caravan will redirect the requests to a predefined script 'error404.html' because it cannot locate the url in its 'templates' or 'doc' folders. So here are the five lines of code needed in the 'error404.html' to make http/1.1 proxy: if request(uri)=~"http:*" request(newname)="_request";// rename request object to _request file x=_request(uri) _reply(newname)="_response";// rename _reply to _response dispatch x(file) endif Caravan will not store locally any data received or sent in the above 'proxy' role. Remember that caravan has a search engine and a database built in. Add a few lines of code to create a full fledged proxy application or your own local server to store all the data you browse! =======================================END=========================================