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         # Intern perform method, lowest level of request launching
  52         private fun perform: nullable CurlResponseFailed
  53         do
  54                 if not self.curl.is_ok then return answer_failure(0, "Curl instance is not correctly initialized")
  55
  56                 var err
  57
  58                 err = self.curl.native.easy_setopt(new CURLOption.verbose, self.verbose)
  59                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
  60
  61                 err = self.curl.native.easy_perform
  62                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
  63
  64                 return null
  65         end
  66
  67         # Intern method with return a failed answer with given code and message
  68         private fun answer_failure(error_code: Int, error_msg: String): CurlResponseFailed
  69         do
  70                 return new CurlResponseFailed(error_code, error_msg)
  71         end
  72 end
  73
  74 # CURL HTTP Request
  75 class CurlHTTPRequest
  76         super CurlRequest
  77         super NativeCurlCallbacks
  78
  79         var url: String
  80         var datas: nullable HeaderMap = null is writable
  81         var headers: nullable HeaderMap = null is writable
  82         var delegate: nullable CurlCallbacks = null is writable
  83
  84         # Set the user agent for all following HTTP requests
  85         var user_agent: nullable String = null is writable
  86
  87         # Execute HTTP request with settings configured through attribute
  88         fun execute: CurlResponse
  89         do
  90                 if not self.curl.is_ok then return answer_failure(0, "Curl instance is not correctly initialized")
  91
  92                 var success_response = new CurlResponseSuccess
  93                 var callback_receiver: CurlCallbacks = success_response
  94                 if self.delegate != null then callback_receiver = self.delegate.as(not null)
  95
  96                 var err
  97
  98                 err = self.curl.native.easy_setopt(new CURLOption.follow_location, 1)
  99                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 100
 101                 err = self.curl.native.easy_setopt(new CURLOption.url, url)
 102                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 103
 104                 var user_agent = user_agent
 105                 if user_agent != null then
 106                         err = curl.native.easy_setopt(new CURLOption.user_agent, user_agent)
 107                         if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 108                 end
 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 #
 201 # ~~~
 202 # # Craft mail
 203 # var mail = new CurlMail("sender@example.org",
 204 #                            to=["to@example.org"], cc=["bob@example.org"])
 205 #
 206 # mail.headers_body["Content-Type:"] = """text/html; charset="UTF-8""""
 207 # mail.headers_body["Content-Transfer-Encoding:"] = "quoted-printable"
 208 #
 209 # mail.body = "<h1>Here you can write HTML stuff.</h1>"
 210 # mail.subject = "Hello From My Nit Program"
 211 #
 212 # # Set mail server
 213 # var error = mail.set_outgoing_server("smtps://smtp.example.org:465",
 214 #                                      "user@example.org", "mypassword")
 215 # if error != null then
 216 #     print "Mail Server Error: {error}"
 217 #     exit 0
 218 # end
 219 #
 220 # # Send
 221 # error = mail.execute
 222 # if error != null then
 223 #     print "Transfer Error: {error}"
 224 #     exit 0
 225 # end
 226 # ~~~
 227 class CurlMail
 228         super CurlRequest
 229         super NativeCurlCallbacks
 230
 231         # Address of the sender
 232         var from: nullable String is writable
 233
 234         # Main recipients
 235         var to: nullable Array[String] is writable
 236
 237         # Subject line
 238         var subject: nullable String is writable
 239
 240         # Text content
 241         var body: nullable String is writable
 242
 243         # CC recipients
 244         var cc: nullable Array[String] is writable
 245
 246         # BCC recipients (hidden from other recipients)
 247         var bcc: nullable Array[String] is writable
 248
 249         # HTTP header
 250         var headers = new HeaderMap is lazy, writable
 251
 252         # Content header
 253         var headers_body = new HeaderMap is lazy, writable
 254
 255         private var supported_outgoing_protocol: Array[String] = ["smtp", "smtps"]
 256
 257         # Helper method to add pair values to mail content while building it (ex: "To:", "address@mail.com")
 258         private fun add_pair_to_content(str: String, att: String, val: nullable String): String
 259         do
 260                 if val != null then return "{str}{att}{val}\n"
 261                 return "{str}{att}\n"
 262         end
 263
 264         # Helper method to add entire list of pairs to mail content
 265         private fun add_pairs_to_content(content: String, pairs: HeaderMap): String
 266         do
 267                 for h_key, h_val in pairs do content = add_pair_to_content(content, h_key, h_val)
 268                 return content
 269         end
 270
 271         # Check for host and protocol availability
 272         private fun is_supported_outgoing_protocol(host: String): CURLCode
 273         do
 274                 var host_reach = host.split_with("://")
 275                 if host_reach.length > 1 and supported_outgoing_protocol.has(host_reach[0]) then return once new CURLCode.ok
 276                 return once new CURLCode.unsupported_protocol
 277         end
 278
 279         # Configure server host and user credentials if needed.
 280         fun set_outgoing_server(host: String, user: nullable String, pwd: nullable String): nullable CurlResponseFailed
 281         do
 282                 # Check Curl initialisation
 283                 if not self.curl.is_ok then return answer_failure(0, "Curl instance is not correctly initialized")
 284
 285                 var err
 286
 287                 # Host & Protocol
 288                 err = is_supported_outgoing_protocol(host)
 289                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 290
 291                 err = self.curl.native.easy_setopt(new CURLOption.url, host)
 292                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 293
 294                 # Credentials
 295                 if not user == null and not pwd == null then
 296                         err = self.curl.native.easy_setopt(new CURLOption.username, user)
 297                         if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 298
 299                         err = self.curl.native.easy_setopt(new CURLOption.password, pwd)
 300                         if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 301                 end
 302
 303                 return null
 304         end
 305
 306         # Execute Mail request with settings configured through attribute
 307         fun execute: nullable CurlResponseFailed
 308         do
 309                 if not self.curl.is_ok then return answer_failure(0, "Curl instance is not correctly initialized")
 310
 311                 var lines = new Array[String]
 312
 313                 # Headers
 314                 var headers = self.headers
 315                 if not headers.is_empty then
 316                         for k, v in headers do lines.add "{k}{v}"
 317                 end
 318
 319                 # Recipients
 320                 var all_recipients = new Array[String]
 321                 var to = self.to
 322                 if to != null and to.length > 0 then
 323                         lines.add "To:{to.join(",")}"
 324                         all_recipients.append to
 325                 end
 326
 327                 var cc = self.cc
 328                 if cc != null and cc.length > 0 then
 329                         lines.add "Cc:{cc.join(",")}"
 330                         all_recipients.append cc
 331                 end
 332
 333                 var bcc = self.bcc
 334                 if bcc != null and bcc.length > 0 then all_recipients.append bcc
 335
 336                 if all_recipients.is_empty then return answer_failure(0, "There must be at lease one recipient")
 337
 338                 var err = self.curl.native.easy_setopt(new CURLOption.follow_location, 1)
 339                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 340
 341                 err = self.curl.native.easy_setopt(new CURLOption.mail_rcpt, all_recipients.to_curlslist)
 342                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 343
 344                 # From
 345                 var from = self.from
 346                 if not from == null then
 347                         lines.add "From:{from}"
 348
 349                         err = self.curl.native.easy_setopt(new CURLOption.mail_from, from)
 350                         if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 351                 end
 352
 353                 # Subject
 354                 var subject = self.subject
 355                 if subject == null then subject = "" # Default
 356                 lines.add "Subject: {subject}"
 357
 358                 # Headers body
 359                 var headers_body = self.headers_body
 360                 if not headers_body.is_empty then
 361                         for k, v in headers_body do lines.add "{k}{v}"
 362                 end
 363
 364                 # Body
 365                 var body = self.body
 366                 if body == null then body = "" # Default
 367
 368                 lines.add ""
 369                 lines.add body
 370                 lines.add ""
 371
 372                 err = self.curl.native.register_callback_read(self)
 373                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 374
 375                 var content = lines.join("\n")
 376                 err = self.curl.native.register_read_datas_callback(self, content)
 377                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 378
 379                 var err_resp = perform
 380                 if err_resp != null then return err_resp
 381
 382                 return null
 383         end
 384 end
 385
 386 # Callbacks Interface, allow you to manage in your way the different streams
 387 interface CurlCallbacks
 388         super NativeCurlCallbacks
 389 end
 390
 391 # Abstract Curl request response
 392 abstract class CurlResponse
 393 end
 394
 395 # Failed Response Class returned when errors during configuration are raised
 396 class CurlResponseFailed
 397         super CurlResponse
 398
 399         var error_code: Int
 400         var error_msg: String
 401
 402         redef fun to_s do return "{error_msg} ({error_code})"
 403 end
 404
 405 # Success Abstract Response Success Class
 406 abstract class CurlResponseSuccessIntern
 407         super CurlCallbacks
 408         super CurlResponse
 409
 410         var headers = new HashMap[String, String]
 411
 412         # Receive headers from request due to headers callback registering
 413         redef fun header_callback(line)
 414         do
 415                 var splitted = line.split_with(':')
 416                 if splitted.length > 1 then
 417                         var key = splitted.shift
 418                         self.headers[key] = splitted.to_s
 419                 end
 420         end
 421 end
 422
 423 # Success Response Class of a basic response
 424 class CurlResponseSuccess
 425         super CurlResponseSuccessIntern
 426
 427         var body_str = ""
 428         var status_code = 0
 429
 430         # Receive body from request due to body callback registering
 431         redef fun body_callback(line) do
 432                 self.body_str = "{self.body_str}{line}"
 433         end
 434 end
 435
 436 # Success Response Class of a downloaded File
 437 class CurlFileResponseSuccess
 438         super CurlResponseSuccessIntern
 439
 440         var status_code = 0
 441         var speed_download = 0
 442         var size_download = 0
 443         var total_time = 0
 444         private var file: nullable FileWriter = null
 445
 446         # Receive bytes stream from request due to stream callback registering
 447         redef fun stream_callback(buffer)
 448         do
 449                 file.write buffer
 450         end
 451 end
 452
 453 # Pseudo map associating `String` to `String` for HTTP exchanges
 454 #
 455 # This structure differs from `Map` as each key can have multiple associations
 456 # and the order of insertion is important to some services.
 457 class HeaderMap
 458         private var array = new Array[Couple[String, String]]
 459
 460         # Add a `value` associated to `key`
 461         fun []=(key, value: String)
 462         do
 463                 array.add new Couple[String, String](key, value)
 464         end
 465
 466         # Get a list of the keys associated to `key`
 467         fun [](k: String): Array[String]
 468         do
 469                 var res = new Array[String]
 470                 for c in array do if c.first == k then res.add c.second
 471                 return res
 472         end
 473
 474         # Iterate over all the associations in `self`
 475         fun iterator: MapIterator[String, String] do return new HeaderMapIterator(self)
 476
 477         # Get `self` as a single string for HTTP POST
 478         #
 479         # Require: `curl.is_ok`
 480         fun to_url_encoded(curl: Curl): String
 481         do
 482                 assert curl.is_ok
 483
 484                 var lines = new Array[String]
 485                 for k, v in self do
 486                         if k.length == 0 then continue
 487
 488                         k = curl.native.escape(k)
 489                         v = curl.native.escape(v)
 490                         lines.add "{k}={v}"
 491                 end
 492                 return lines.join("&")
 493         end
 494
 495         # Concatenate couple of 'key value' separated by 'sep' in Array
 496         fun join_pairs(sep: String): Array[String]
 497         do
 498                 var col = new Array[String]
 499                 for k, v in self do col.add("{k}{sep}{v}")
 500                 return col
 501         end
 502
 503         # Number of values in `self`
 504         fun length: Int do return array.length
 505
 506         # Is this map empty?
 507         fun is_empty: Bool do return array.is_empty
 508 end
 509
 510 private class HeaderMapIterator
 511         super MapIterator[String, String]
 512
 513         var map: HeaderMap
 514         var iterator: Iterator[Couple[String, String]] = map.array.iterator is lazy
 515
 516         redef fun is_ok do return self.iterator.is_ok
 517         redef fun next do self.iterator.next
 518         redef fun item do return self.iterator.item.second
 519         redef fun key do return self.iterator.item.first
 520 end