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 # Data transfer powered by the native curl library
  18 #
  19 # Download or upload data over HTTP with `CurlHTTPRequest` and send emails
  20 # with `CurlMail`. Scripts can use the easier (but limited) services on `Text`,
  21 # `http_get` and `http_download`, provided by `curl::extra`.
  22 module curl
  23
  24 import native_curl
  25
  26 # Curl library handle
  27 private class Curl
  28         super FinalizableOnce
  29
  30         var native = new NativeCurl.easy_init
  31
  32         # Is this instance correctly initialized?
  33         fun is_ok: Bool do return self.native.is_init
  34
  35         redef fun finalize_once do if is_ok then native.easy_clean
  36 end
  37
  38 # CURL Request
  39 class CurlRequest
  40
  41         private var curl = new Curl
  42
  43         # Shall this request be verbose?
  44         var verbose: Bool = false is writable
  45
  46         # Intern perform method, lowest level of request launching
  47         private fun perform: nullable CurlResponseFailed
  48         do
  49                 if not self.curl.is_ok then return answer_failure(0, "Curl instance is not correctly initialized")
  50
  51                 var err
  52
  53                 err = self.curl.native.easy_setopt(new CURLOption.verbose, self.verbose)
  54                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
  55
  56                 err = self.curl.native.easy_perform
  57                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
  58
  59                 return null
  60         end
  61
  62         # Intern method with return a failed answer with given code and message
  63         private fun answer_failure(error_code: Int, error_msg: String): CurlResponseFailed
  64         do
  65                 return new CurlResponseFailed(error_code, error_msg)
  66         end
  67
  68         # Close low-level resources associated to this request
  69         #
  70         # Once closed, this request can't be used again.
  71         #
  72         # If this service isn't called explicitly, low-level resources
  73         # may be freed automatically by the GC.
  74         fun close do curl.finalize
  75 end
  76
  77 # HTTP request builder
  78 #
  79 # The request itself is sent by either `execute` or `download_to_file`.
  80 # The attributes of this class must be set before calling either of these two methods.
  81 #
  82 # ## Minimal usage example
  83 #
  84 # ~~~
  85 # var request = new CurlHTTPRequest("http://example.org/")
  86 # var response = request.execute
  87 # if response isa CurlResponseSuccess then
  88 #     print "Response status code: {response.status_code}"
  89 #     print response.body_str
  90 # else if response isa CurlResponseFailed then
  91 #     print_error response.error_msg
  92 # end
  93 # ~~~
  94 class CurlHTTPRequest
  95         super CurlRequest
  96         super NativeCurlCallbacks
  97
  98         # Address of the remote resource to request
  99         var url: String
 100
 101         # Data for the body of a POST request
 102         var data: nullable HeaderMap is writable
 103
 104         # Raw body string
 105         #
 106         # Set this value to send raw data instead of the POST formatted `data`.
 107         #
 108         # If `data` is set, the body will not be sent.
 109         var body: nullable String is writable
 110
 111         # Header content of the request
 112         var headers: nullable HeaderMap is writable
 113
 114         # Delegates to customize the behavior when running `execute`
 115         var delegate: nullable CurlCallbacks is writable
 116
 117         # Set the user agent for all following HTTP requests
 118         var user_agent: nullable String is writable
 119
 120         # Set the Unix domain socket path to use
 121         #
 122         # When not null, enables using a Unix domain socket
 123         # instead of a TCP connection and DNS hostname resolution.
 124         var unix_socket_path: nullable String is writable
 125
 126         # The HTTP method, GET by default
 127         #
 128         # Must be a capitalized string with request name complying with RFC7231
 129         var method: String = "GET" is optional, writable
 130
 131         # Execute HTTP request
 132         #
 133         # By default, the response body is returned in an instance of `CurlResponse`.
 134         # This behavior can be customized by setting a custom `delegate`.
 135         fun execute: CurlResponse
 136         do
 137                 # Reset libcurl parameters as the lib is shared and options
 138                 # might affect requests from one another.
 139                 if not self.curl.is_ok then return answer_failure(0, "Curl instance is not correctly initialized")
 140
 141                 var success_response = new CurlResponseSuccess
 142                 var callback_receiver: CurlCallbacks = success_response
 143                 var err : CURLCode
 144
 145                 # Prepare request
 146                 err = prepare_request(callback_receiver)
 147                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 148
 149                 # Perform request
 150                 var err_resp = perform
 151                 if err_resp != null then return err_resp
 152
 153                 var st_code = self.curl.native.easy_getinfo_long(new CURLInfoLong.response_code)
 154                 if not st_code == null then success_response.status_code = st_code
 155
 156                 return success_response
 157         end
 158
 159         # Internal function that sets cURL options and request' parameters
 160         private fun prepare_request(callback_receiver: CurlCallbacks) : CURLCode
 161         do
 162                 var err
 163
 164                 # cURL options and delegates
 165                 err = set_curl_options
 166                 if not err.is_ok then return err
 167
 168                 # Callbacks
 169                 err = set_curl_callback(callback_receiver)
 170                 if not err.is_ok then return err
 171
 172                 # HTTP Header
 173                 err = set_curl_http_header
 174                 if not err.is_ok then return err
 175
 176                 # Set HTTP method and body
 177                 err = set_method
 178                 if not err.is_ok then return err
 179                 err = set_body
 180
 181                 return err
 182         end
 183
 184         # Set cURL parameters according to assigned HTTP method set in method
 185         # attribute and body if the method allows it according to RFC7231
 186         private fun set_method : CURLCode
 187         do
 188                 var err : CURLCode
 189
 190                 if self.method=="GET" then
 191                         err=self.curl.native.easy_setopt(new CURLOption.get, 1)
 192
 193                 else if self.method=="POST" then
 194                         err=self.curl.native.easy_setopt(new CURLOption.post, 1)
 195
 196                 else if self.method=="HEAD" then
 197                         err=self.curl.native.easy_setopt(new CURLOption.no_body,1)
 198
 199                 else
 200                         err=self.curl.native.easy_setopt(new CURLOption.custom_request,self.method)
 201                 end
 202                 return err
 203         end
 204
 205         # Set request's body
 206         private fun set_body : CURLCode
 207         do
 208                 var err
 209                 var data = self.data
 210                 var body = self.body
 211
 212                 if data != null then
 213                         var postdatas = data.to_url_encoded(self.curl)
 214                         err = self.curl.native.easy_setopt(new CURLOption.postfields, postdatas)
 215                         if not err.is_ok then return err
 216                 else if body != null then
 217                         err = self.curl.native.easy_setopt(new CURLOption.postfields, body)
 218                         if not err.is_ok then return err
 219                 end
 220                 return new CURLCode.ok
 221         end
 222
 223         # Set cURL options
 224         # such as delegate, follow location, URL, user agent and address family
 225         private fun set_curl_options : CURLCode
 226         do
 227                 var err
 228
 229                 err = self.curl.native.easy_setopt(new CURLOption.follow_location, 1)
 230                 if not err.is_ok then return err
 231
 232                 err = self.curl.native.easy_setopt(new CURLOption.url, url)
 233                 if not err.is_ok then return err
 234
 235                 var user_agent = user_agent
 236                 if user_agent != null then
 237                         err = curl.native.easy_setopt(new CURLOption.user_agent, user_agent)
 238                         if not err.is_ok then return err
 239                 end
 240
 241                 var unix_socket_path = unix_socket_path
 242                 if unix_socket_path != null then
 243                         err = self.curl.native.easy_setopt(new CURLOption.unix_socket_path, unix_socket_path)
 244                         if not err.is_ok then return err
 245                 end
 246                 return err
 247         end
 248
 249         # Set cURL callback
 250         private fun set_curl_callback(callback_receiver : CurlCallbacks) : CURLCode
 251         do
 252                 var err
 253
 254                 if self.delegate != null then callback_receiver = self.delegate.as(not null)
 255
 256                 err = self.curl.native.register_callback_header(callback_receiver)
 257                 if not err.is_ok then return err
 258
 259                 err = self.curl.native.register_callback_body(callback_receiver)
 260                 if not err.is_ok then return err
 261
 262                 return err
 263         end
 264
 265         # Set cURL request header according to attribute headers
 266         private fun set_curl_http_header : CURLCode
 267         do
 268                 var headers = self.headers
 269                 if headers != null then
 270                         var headers_joined = headers.join_pairs(": ")
 271                         var err = self.curl.native.easy_setopt(new CURLOption.httpheader, headers_joined.to_curlslist)
 272                         if not err.is_ok then return err
 273                 end
 274                 return new CURLCode.ok
 275         end
 276
 277         # Download to file given resource
 278         fun download_to_file(output_file_name: nullable String): CurlResponse
 279         do
 280                 if not self.curl.is_ok then return answer_failure(0, "Curl instance is not correctly initialized")
 281
 282                 var success_response = new CurlFileResponseSuccess
 283
 284                 var callback_receiver: CurlCallbacks = success_response
 285                 if self.delegate != null then callback_receiver = self.delegate.as(not null)
 286
 287                 var err
 288
 289                 err = self.curl.native.easy_setopt(new CURLOption.follow_location, 1)
 290                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 291
 292                 err = self.curl.native.easy_setopt(new CURLOption.url, url)
 293                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 294
 295                 err = self.curl.native.register_callback_header(callback_receiver)
 296                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 297
 298                 err = self.curl.native.register_callback_stream(callback_receiver)
 299                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 300
 301                 var opt_name
 302                 if not output_file_name == null then
 303                         opt_name = output_file_name
 304                 else if not self.url.substring(self.url.length-1, self.url.length) == "/" then
 305                         opt_name = self.url.basename
 306                 else
 307                         return answer_failure(0, "Unable to extract file name, please specify one")
 308                 end
 309
 310                 success_response.file = new FileWriter.open(opt_name)
 311                 if not success_response.file.is_writable then
 312                         return answer_failure(0, "Unable to create associated file")
 313                 end
 314
 315                 var err_resp = perform
 316                 if err_resp != null then return err_resp
 317
 318                 var st_code = self.curl.native.easy_getinfo_long(new CURLInfoLong.response_code)
 319                 if not st_code == null then success_response.status_code = st_code
 320
 321                 var speed = self.curl.native.easy_getinfo_double(new CURLInfoDouble.speed_download)
 322                 if not speed == null then success_response.speed_download = speed
 323
 324                 var size = self.curl.native.easy_getinfo_double(new CURLInfoDouble.size_download)
 325                 if not size == null then success_response.size_download = size
 326
 327                 var time = self.curl.native.easy_getinfo_double(new CURLInfoDouble.total_time)
 328                 if not time == null then success_response.total_time = time
 329
 330                 success_response.file.close
 331
 332                 return success_response
 333         end
 334 end
 335
 336
 337 # CURL Mail Request
 338 #
 339 # ~~~
 340 # # Craft mail
 341 # var mail = new CurlMail("sender@example.org",
 342 #                            to=["to@example.org"], cc=["bob@example.org"])
 343 #
 344 # mail.headers_body["Content-Type:"] = """text/html; charset="UTF-8""""
 345 # mail.headers_body["Content-Transfer-Encoding:"] = "quoted-printable"
 346 #
 347 # mail.body = "<h1>Here you can write HTML stuff.</h1>"
 348 # mail.subject = "Hello From My Nit Program"
 349 #
 350 # # Set mail server
 351 # var error = mail.set_outgoing_server("smtps://smtp.example.org:465",
 352 #                                      "user@example.org", "mypassword")
 353 # if error != null then
 354 #     print "Mail Server Error: {error}"
 355 #     exit 0
 356 # end
 357 #
 358 # # Send
 359 # error = mail.execute
 360 # if error != null then
 361 #     print "Transfer Error: {error}"
 362 #     exit 0
 363 # end
 364 # ~~~
 365 class CurlMail
 366         super CurlRequest
 367         super NativeCurlCallbacks
 368
 369         # Address of the sender
 370         var from: nullable String is writable
 371
 372         # Main recipients
 373         var to: nullable Array[String] is writable
 374
 375         # Subject line
 376         var subject: nullable String is writable
 377
 378         # Text content
 379         var body: nullable String is writable
 380
 381         # CC recipients
 382         var cc: nullable Array[String] is writable
 383
 384         # BCC recipients (hidden from other recipients)
 385         var bcc: nullable Array[String] is writable
 386
 387         # HTTP header
 388         var headers = new HeaderMap is lazy, writable
 389
 390         # Content header
 391         var headers_body = new HeaderMap is lazy, writable
 392
 393         # Protocols supported to send mail to a server
 394         #
 395         # Default value at `["smtp", "smtps"]`
 396         var supported_outgoing_protocol = ["smtp", "smtps"]
 397
 398         # Helper method to add pair values to mail content while building it (ex: "To:", "address@mail.com")
 399         private fun add_pair_to_content(str: String, att: String, val: nullable String): String
 400         do
 401                 if val != null then return "{str}{att}{val}\n"
 402                 return "{str}{att}\n"
 403         end
 404
 405         # Helper method to add entire list of pairs to mail content
 406         private fun add_pairs_to_content(content: String, pairs: HeaderMap): String
 407         do
 408                 for h_key, h_val in pairs do content = add_pair_to_content(content, h_key, h_val)
 409                 return content
 410         end
 411
 412         # Check for host and protocol availability
 413         private fun is_supported_outgoing_protocol(host: String): CURLCode
 414         do
 415                 var host_reach = host.split_with("://")
 416                 if host_reach.length > 1 and supported_outgoing_protocol.has(host_reach[0]) then return once new CURLCode.ok
 417                 return once new CURLCode.unsupported_protocol
 418         end
 419
 420         # Configure server host and user credentials if needed.
 421         fun set_outgoing_server(host: String, user: nullable String, pwd: nullable String): nullable CurlResponseFailed
 422         do
 423                 # Check Curl initialisation
 424                 if not self.curl.is_ok then return answer_failure(0, "Curl instance is not correctly initialized")
 425
 426                 var err
 427
 428                 # Host & Protocol
 429                 err = is_supported_outgoing_protocol(host)
 430                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 431
 432                 err = self.curl.native.easy_setopt(new CURLOption.url, host)
 433                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 434
 435                 # Credentials
 436                 if not user == null and not pwd == null then
 437                         err = self.curl.native.easy_setopt(new CURLOption.username, user)
 438                         if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 439
 440                         err = self.curl.native.easy_setopt(new CURLOption.password, pwd)
 441                         if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 442                 end
 443
 444                 return null
 445         end
 446
 447         # Execute Mail request with settings configured through attribute
 448         fun execute: nullable CurlResponseFailed
 449         do
 450                 if not self.curl.is_ok then return answer_failure(0, "Curl instance is not correctly initialized")
 451
 452                 var lines = new Array[String]
 453
 454                 # Headers
 455                 var headers = self.headers
 456                 if not headers.is_empty then
 457                         for k, v in headers do lines.add "{k}{v}"
 458                 end
 459
 460                 # Recipients
 461                 var all_recipients = new Array[String]
 462                 var to = self.to
 463                 if to != null and to.length > 0 then
 464                         lines.add "To:{to.join(",")}"
 465                         all_recipients.append to
 466                 end
 467
 468                 var cc = self.cc
 469                 if cc != null and cc.length > 0 then
 470                         lines.add "Cc:{cc.join(",")}"
 471                         all_recipients.append cc
 472                 end
 473
 474                 var bcc = self.bcc
 475                 if bcc != null and bcc.length > 0 then all_recipients.append bcc
 476
 477                 if all_recipients.is_empty then return answer_failure(0, "There must be at lease one recipient")
 478
 479                 var err = self.curl.native.easy_setopt(new CURLOption.follow_location, 1)
 480                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 481
 482                 err = self.curl.native.easy_setopt(new CURLOption.mail_rcpt, all_recipients.to_curlslist)
 483                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 484
 485                 # From
 486                 var from = self.from
 487                 if not from == null then
 488                         lines.add "From:{from}"
 489
 490                         err = self.curl.native.easy_setopt(new CURLOption.mail_from, from)
 491                         if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 492                 end
 493
 494                 # Subject
 495                 var subject = self.subject
 496                 if subject == null then subject = "" # Default
 497                 lines.add "Subject: {subject}"
 498
 499                 # Headers body
 500                 var headers_body = self.headers_body
 501                 if not headers_body.is_empty then
 502                         for k, v in headers_body do lines.add "{k}{v}"
 503                 end
 504
 505                 # Body
 506                 var body = self.body
 507                 if body == null then body = "" # Default
 508
 509                 lines.add ""
 510                 lines.add body
 511                 lines.add ""
 512
 513                 err = self.curl.native.register_callback_read(self)
 514                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 515
 516                 var content = lines.join("\n")
 517                 err = self.curl.native.register_read_datas_callback(self, content)
 518                 if not err.is_ok then return answer_failure(err.to_i, err.to_s)
 519
 520                 var err_resp = perform
 521                 if err_resp != null then return err_resp
 522
 523                 return null
 524         end
 525 end
 526
 527 # Callbacks Interface, allow you to manage in your way the different streams
 528 interface CurlCallbacks
 529         super NativeCurlCallbacks
 530 end
 531
 532 # Abstract Curl request response
 533 abstract class CurlResponse
 534 end
 535
 536 # Failed Response Class returned when errors during configuration are raised
 537 class CurlResponseFailed
 538         super CurlResponse
 539
 540         # Curl error code
 541         var error_code: Int
 542
 543         # Curl error message
 544         var error_msg: String
 545
 546         redef fun to_s do return "{error_msg} ({error_code})"
 547 end
 548
 549 # Success Abstract Response Success Class
 550 abstract class CurlResponseSuccessIntern
 551         super CurlCallbacks
 552         super CurlResponse
 553
 554         var headers = new HashMap[String, String]
 555
 556         # Receive headers from request due to headers callback registering
 557         redef fun header_callback(line)
 558         do
 559                 var splitted = line.split_with(':')
 560                 if splitted.length > 1 then
 561                         var key = splitted.shift
 562                         self.headers[key] = splitted.to_s
 563                 end
 564         end
 565 end
 566
 567 # Success Response Class of a basic response
 568 class CurlResponseSuccess
 569         super CurlResponseSuccessIntern
 570
 571         # Server HTTP response code
 572         var status_code = 0
 573
 574         # Response body as a `String`
 575         var body_str = ""
 576
 577         # Accept part of the response body
 578         redef fun body_callback(line) do self.body_str += line
 579 end
 580
 581 # Success Response Class of a downloaded File
 582 class CurlFileResponseSuccess
 583         super CurlResponseSuccessIntern
 584
 585         # Server HTTP response code
 586         var status_code = 0
 587
 588         var speed_download = 0.0
 589         var size_download = 0.0
 590         var total_time = 0.0
 591
 592         private var file: nullable FileWriter = null
 593
 594         # Receive bytes stream from request due to stream callback registering
 595         redef fun stream_callback(buffer)
 596         do
 597                 file.write buffer
 598         end
 599 end
 600
 601 # Pseudo map associating `String` to `String` for HTTP exchanges
 602 #
 603 # This structure differs from `Map` as each key can have multiple associations
 604 # and the order of insertion is important to some services.
 605 class HeaderMap
 606         private var array = new Array[Couple[String, String]]
 607
 608         # Add a `value` associated to `key`
 609         fun []=(key, value: String)
 610         do
 611                 array.add new Couple[String, String](key, value)
 612         end
 613
 614         # Get a list of the keys associated to `key`
 615         fun [](k: String): Array[String]
 616         do
 617                 var res = new Array[String]
 618                 for c in array do if c.first == k then res.add c.second
 619                 return res
 620         end
 621
 622         # Iterate over all the associations in `self`
 623         fun iterator: MapIterator[String, String] do return new HeaderMapIterator(self)
 624
 625         # Get `self` as a single string for HTTP POST
 626         #
 627         # Require: `curl.is_ok`
 628         private fun to_url_encoded(curl: Curl): String
 629         do
 630                 assert curl.is_ok
 631
 632                 var lines = new Array[String]
 633                 for k, v in self do
 634                         if k.length == 0 then continue
 635
 636                         k = curl.native.escape(k)
 637                         v = curl.native.escape(v)
 638                         lines.add "{k}={v}"
 639                 end
 640                 return lines.join("&")
 641         end
 642
 643         # Concatenate couple of 'key value' separated by 'sep' in Array
 644         fun join_pairs(sep: String): Array[String]
 645         do
 646                 var col = new Array[String]
 647                 for k, v in self do col.add("{k}{sep}{v}")
 648                 return col
 649         end
 650
 651         # Number of values in `self`
 652         fun length: Int do return array.length
 653
 654         # Is this map empty?
 655         fun is_empty: Bool do return array.is_empty
 656 end
 657
 658 private class HeaderMapIterator
 659         super MapIterator[String, String]
 660
 661         var map: HeaderMap
 662         var iterator: Iterator[Couple[String, String]] = map.array.iterator is lazy
 663
 664         redef fun is_ok do return self.iterator.is_ok
 665         redef fun next do self.iterator.next
 666         redef fun item do return self.iterator.item.second
 667         redef fun key do return self.iterator.item.first
 668 end