lib/curl/curl.nit

   1 # This file is part of NIT ( http://www.nitlanguage.org ).
   2 #
   3 # Copyright 2013 Matthieu Lucas <lucasmatthieu@gmail.com>
   4 #
   5 # Licensed under the Apache License, Version 2.0 (the "License");
   6 # you may not use this file except in compliance with the License.
   7 # You may obtain a copy of the License at
   8 #
   9 #     http://www.apache.org/licenses/LICENSE-2.0
  10 #
  11 # Unless required by applicable law or agreed to in writing, software
  12 # distributed under the License is distributed on an "AS IS" BASIS,
  13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 # See the License for the specific language governing permissions and
  15 # limitations under the License.
  16
  17 # Curl services: `CurlHTTPRequest` and `CurlMail`
  18 module curl
  19
  20 import native_curl
  21
  22 redef class Sys
  23         # Shared Curl library handle
  24         #
  25         # Usually, you do not have to use this attribute, it instancied by `CurlHTTPRequest` and `CurlMail`.
  26         # But in some cases you may want to finalize it to free some small resources.
  27         # However, if Curl services are needed once again, this attribute must be manually set.
  28         var curl: Curl = new Curl is lazy, writable
  29 end
  30
  31 # Curl library handle, it is initialized and released with this class
  32 class Curl
  33         super FinalizableOnce
  34
  35         private var native = new NativeCurl.easy_init
  36
  37         # Check for correct initialization
  38         fun is_ok: Bool do return self.native.is_init
  39
  40         redef fun finalize_once do if is_ok then native.easy_clean
  41 end
  42
  43 # CURL Request
  44 class CurlRequest
  45
  46         private var curl: Curl = sys.curl
  47
  48         # Shall this request be verbose?
  49         var verbose: Bool = false is writable
  50
  51         # Launch request method
  52         fun execute: CurlResponse is abstract
  53
  54         # Intern perform method, lowest level of request launching
  55         private fun perform: nullable CurlResponseFailed
  56         do
  57                 if not self.curl.is_ok then return answer_failure(0, "Curl instance is not correctly initialized")
  58
  59                 var err
  60
  61                 err = self.curl.native.easy_setopt(new CURLOption.verbose, self.verbose)
  62                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
  63
  64                 err = self.curl.native.easy_perform
  65                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
  66
  67                 return null
  68         end
  69
  70         # Intern method with return a failed answer with given code and message
  71         private fun answer_failure(error_code: Int, error_msg: String): CurlResponseFailed
  72         do
  73                 return new CurlResponseFailed(error_code, error_msg)
  74         end
  75 end
  76
  77 # CURL HTTP Request
  78 class CurlHTTPRequest
  79         super CurlRequest
  80         super NativeCurlCallbacks
  81
  82         var url: String
  83         var datas: nullable HeaderMap = null is writable
  84         var headers: nullable HeaderMap = null is writable
  85         var delegate: nullable CurlCallbacks = null is writable
  86
  87         # Set the user agent for all following HTTP requests
  88         fun user_agent=(name: String)
  89         do
  90                 curl.native.easy_setopt(new CURLOption.user_agent, name)
  91         end
  92
  93         # Execute HTTP request with settings configured through attribute
  94         redef fun execute
  95         do
  96                 if not self.curl.is_ok then return answer_failure(0, "Curl instance is not correctly initialized")
  97
  98                 var success_response = new CurlResponseSuccess
  99                 var callback_receiver: CurlCallbacks = success_response
 100                 if self.delegate != null then callback_receiver = self.delegate.as(not null)
 101
 102                 var err
 103
 104                 err = self.curl.native.easy_setopt(new CURLOption.follow_location, 1)
 105                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 106
 107                 err = self.curl.native.easy_setopt(new CURLOption.url, url)
 108                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 109
 110                 # Callbacks
 111                 err = self.curl.native.register_callback_header(callback_receiver)
 112                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 113
 114                 err = self.curl.native.register_callback_body(callback_receiver)
 115                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 116
 117                 # HTTP Header
 118                 var headers = self.headers
 119                 if headers != null then
 120                         var headers_joined = headers.join_pairs(": ")
 121                         err = self.curl.native.easy_setopt(new CURLOption.httpheader, headers_joined.to_curlslist)
 122                         if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 123                 end
 124
 125                 # Datas
 126                 var datas = self.datas
 127                 if datas != null then
 128                         var postdatas = datas.to_url_encoded(self.curl)
 129                         err = self.curl.native.easy_setopt(new CURLOption.postfields, postdatas)
 130                         if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 131                 end
 132
 133                 var err_resp = perform
 134                 if err_resp != null then return err_resp
 135
 136                 var st_code = self.curl.native.easy_getinfo_long(new CURLInfoLong.response_code)
 137                 if not st_code == null then success_response.status_code = st_code.response
 138
 139                 return success_response
 140         end
 141
 142         # Download to file given resource
 143         fun download_to_file(output_file_name: nullable String): CurlResponse
 144         do
 145                 var success_response = new CurlFileResponseSuccess
 146
 147                 var callback_receiver: CurlCallbacks = success_response
 148                 if self.delegate != null then callback_receiver = self.delegate.as(not null)
 149
 150                 var err
 151
 152                 err = self.curl.native.easy_setopt(new CURLOption.follow_location, 1)
 153                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 154
 155                 err = self.curl.native.easy_setopt(new CURLOption.url, url)
 156                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 157
 158                 err = self.curl.native.register_callback_header(callback_receiver)
 159                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 160
 161                 err = self.curl.native.register_callback_stream(callback_receiver)
 162                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 163
 164                 var opt_name
 165                 if not output_file_name == null then
 166                         opt_name = output_file_name
 167                 else if not self.url.substring(self.url.length-1, self.url.length) == "/" then
 168                         opt_name = self.url.basename("")
 169                 else
 170                         return answer_failure(0, "Unable to extract file name, please specify one")
 171                 end
 172
 173                 success_response.file = new FileWriter.open(opt_name)
 174                 if not success_response.file.is_writable then
 175                         return answer_failure(0, "Unable to create associated file")
 176                 end
 177
 178                 var err_resp = perform
 179                 if err_resp != null then return err_resp
 180
 181                 var st_code = self.curl.native.easy_getinfo_long(new CURLInfoLong.response_code)
 182                 if not st_code == null then success_response.status_code = st_code.response
 183
 184                 var speed = self.curl.native.easy_getinfo_double(new CURLInfoDouble.speed_download)
 185                 if not speed == null then success_response.speed_download = speed.response
 186
 187                 var size = self.curl.native.easy_getinfo_double(new CURLInfoDouble.size_download)
 188                 if not size == null then success_response.size_download = size.response
 189
 190                 var time = self.curl.native.easy_getinfo_double(new CURLInfoDouble.total_time)
 191                 if not time == null then success_response.total_time = time.response
 192
 193                 success_response.file.close
 194
 195                 return success_response
 196         end
 197 end
 198
 199 # CURL Mail Request
 200 class CurlMail
 201         super CurlRequest
 202         super NativeCurlCallbacks
 203
 204         # Address of the sender
 205         var from: nullable String is writable
 206
 207         # Main recipients
 208         var to: nullable Array[String] is writable
 209
 210         # Subject line
 211         var subject: nullable String is writable
 212
 213         # Text content
 214         var body: nullable String is writable
 215
 216         # CC recipients
 217         var cc: nullable Array[String] is writable
 218
 219         # BCC recipients (hidden from other recipients)
 220         var bcc: nullable Array[String] is writable
 221
 222         # HTTP header
 223         var headers = new HeaderMap is lazy, writable
 224
 225         # Content header
 226         var headers_body = new HeaderMap is lazy, writable
 227
 228         private var supported_outgoing_protocol: Array[String] = ["smtp", "smtps"]
 229
 230         # Helper method to add pair values to mail content while building it (ex: "To:", "address@mail.com")
 231         private fun add_pair_to_content(str: String, att: String, val: nullable String): String
 232         do
 233                 if val != null then return "{str}{att}{val}\n"
 234                 return "{str}{att}\n"
 235         end
 236
 237         # Helper method to add entire list of pairs to mail content
 238         private fun add_pairs_to_content(content: String, pairs: HeaderMap): String
 239         do
 240                 for h_key, h_val in pairs do content = add_pair_to_content(content, h_key, h_val)
 241                 return content
 242         end
 243
 244         # Check for host and protocol availability
 245         private fun is_supported_outgoing_protocol(host: String): CURLCode
 246         do
 247                 var host_reach = host.split_with("://")
 248                 if host_reach.length > 1 and supported_outgoing_protocol.has(host_reach[0]) then return once new CURLCode.ok
 249                 return once new CURLCode.unsupported_protocol
 250         end
 251
 252         # Configure server host and user credentials if needed.
 253         fun set_outgoing_server(host: String, user: nullable String, pwd: nullable String): nullable CurlResponseFailed
 254         do
 255                 # Check Curl initialisation
 256                 if not self.curl.is_ok then return answer_failure(0, "Curl instance is not correctly initialized")
 257
 258                 var err
 259
 260                 # Host & Protocol
 261                 err = is_supported_outgoing_protocol(host)
 262                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 263
 264                 err = self.curl.native.easy_setopt(new CURLOption.url, host)
 265                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 266
 267                 # Credentials
 268                 if not user == null and not pwd == null then
 269                         err = self.curl.native.easy_setopt(new CURLOption.username, user)
 270                         if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 271
 272                         err = self.curl.native.easy_setopt(new CURLOption.password, pwd)
 273                         if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 274                 end
 275
 276                 return null
 277         end
 278
 279         # Execute Mail request with settings configured through attribute
 280         redef fun execute
 281         do
 282                 if not self.curl.is_ok then return answer_failure(0, "Curl instance is not correctly initialized")
 283
 284                 var lines = new Array[String]
 285
 286                 # Headers
 287                 var headers = self.headers
 288                 if not headers.is_empty then
 289                         for k, v in headers do lines.add "{k}{v}"
 290                 end
 291
 292                 # Recipients
 293                 var all_recipients = new Array[String]
 294                 var to = self.to
 295                 if to != null and to.length > 0 then
 296                         lines.add "To:{to.join(",")}"
 297                         all_recipients.append to
 298                 end
 299
 300                 var cc = self.cc
 301                 if cc != null and cc.length > 0 then
 302                         lines.add "Cc:{cc.join(",")}"
 303                         all_recipients.append cc
 304                 end
 305
 306                 var bcc = self.bcc
 307                 if bcc != null and bcc.length > 0 then all_recipients.append bcc
 308
 309                 if all_recipients.is_empty then return answer_failure(0, "There must be at lease one recipient")
 310
 311                 var err = self.curl.native.easy_setopt(new CURLOption.follow_location, 1)
 312                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 313
 314                 err = self.curl.native.easy_setopt(new CURLOption.mail_rcpt, all_recipients.to_curlslist)
 315                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 316
 317                 # From
 318                 var from = self.from
 319                 if not from == null then
 320                         lines.add "From:{from}"
 321
 322                         err = self.curl.native.easy_setopt(new CURLOption.mail_from, from)
 323                         if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 324                 end
 325
 326                 # Subject
 327                 var subject = self.subject
 328                 if subject == null then subject = "" # Default
 329                 lines.add "Subject: {subject}"
 330
 331                 # Headers body
 332                 var headers_body = self.headers_body
 333                 if not headers_body.is_empty then
 334                         for k, v in headers_body do lines.add "{k}{v}"
 335                 end
 336
 337                 # Body
 338                 var body = self.body
 339                 if body == null then body = "" # Default
 340
 341                 lines.add ""
 342                 lines.add body
 343                 lines.add ""
 344
 345                 err = self.curl.native.register_callback_read(self)
 346                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 347
 348                 var content = lines.join("\n")
 349                 err = self.curl.native.register_read_datas_callback(self, content)
 350                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 351
 352                 var err_resp = perform
 353                 if err_resp != null then return err_resp
 354
 355                 return new CurlMailResponseSuccess
 356         end
 357 end
 358
 359 # Callbacks Interface, allow you to manage in your way the different streams
 360 interface CurlCallbacks
 361         super NativeCurlCallbacks
 362 end
 363
 364 # Abstract Curl request response
 365 abstract class CurlResponse
 366 end
 367
 368 # Failed Response Class returned when errors during configuration are raised
 369 class CurlResponseFailed
 370         super CurlResponse
 371
 372         var error_code: Int
 373         var error_msg: String
 374 end
 375
 376 # Success Abstract Response Success Class
 377 abstract class CurlResponseSuccessIntern
 378         super CurlCallbacks
 379         super CurlResponse
 380
 381         var headers = new HashMap[String, String]
 382
 383         # Receive headers from request due to headers callback registering
 384         redef fun header_callback(line)
 385         do
 386                 var splitted = line.split_with(':')
 387                 if splitted.length > 1 then
 388                         var key = splitted.shift
 389                         self.headers[key] = splitted.to_s
 390                 end
 391         end
 392 end
 393
 394 # Success Response Class of a basic response
 395 class CurlResponseSuccess
 396         super CurlResponseSuccessIntern
 397
 398         var body_str = ""
 399         var status_code = 0
 400
 401         # Receive body from request due to body callback registering
 402         redef fun body_callback(line) do
 403                 self.body_str = "{self.body_str}{line}"
 404         end
 405 end
 406
 407 # Success Response Class of mail request
 408 class CurlMailResponseSuccess
 409         super CurlResponseSuccessIntern
 410 end
 411
 412 # Success Response Class of a downloaded File
 413 class CurlFileResponseSuccess
 414         super CurlResponseSuccessIntern
 415
 416         var status_code = 0
 417         var speed_download = 0
 418         var size_download = 0
 419         var total_time = 0
 420         private var file: nullable FileWriter = null
 421
 422         # Receive bytes stream from request due to stream callback registering
 423         redef fun stream_callback(buffer)
 424         do
 425                 file.write buffer
 426         end
 427 end
 428
 429 # Pseudo map associating `String` to `String` for HTTP exchanges
 430 #
 431 # This structure differs from `Map` as each key can have multiple associations
 432 # and the order of insertion is important to some services.
 433 class HeaderMap
 434         private var array = new Array[Couple[String, String]]
 435
 436         # Add a `value` associated to `key`
 437         fun []=(key, value: String)
 438         do
 439                 array.add new Couple[String, String](key, value)
 440         end
 441
 442         # Get a list of the keys associated to `key`
 443         fun [](k: String): Array[String]
 444         do
 445                 var res = new Array[String]
 446                 for c in array do if c.first == k then res.add c.second
 447                 return res
 448         end
 449
 450         # Iterate over all the associations in `self`
 451         fun iterator: MapIterator[String, String] do return new HeaderMapIterator(self)
 452
 453         # Get `self` as a single string for HTTP POST
 454         #
 455         # Require: `curl.is_ok`
 456         fun to_url_encoded(curl: Curl): String
 457         do
 458                 assert curl.is_ok
 459
 460                 var lines = new Array[String]
 461                 for k, v in self do
 462                         if k.length == 0 then continue
 463
 464                         k = curl.native.escape(k)
 465                         v = curl.native.escape(v)
 466                         lines.add "{k}={v}"
 467                 end
 468                 return lines.join("&")
 469         end
 470
 471         # Concatenate couple of 'key value' separated by 'sep' in Array
 472         fun join_pairs(sep: String): Array[String]
 473         do
 474                 var col = new Array[String]
 475                 for k, v in self do col.add("{k}{sep}{v}")
 476                 return col
 477         end
 478
 479         # Number of values in `self`
 480         fun length: Int do return array.length
 481
 482         # Is this map empty?
 483         fun is_empty: Bool do return array.is_empty
 484 end
 485
 486 private class HeaderMapIterator
 487         super MapIterator[String, String]
 488
 489         var map: HeaderMap
 490         var iterator: Iterator[Couple[String, String]] = map.array.iterator is lazy
 491
 492         redef fun is_ok do return self.iterator.is_ok
 493         redef fun next do self.iterator.next
 494         redef fun item do return self.iterator.item.second
 495         redef fun key do return self.iterator.item.first
 496 end