# Data transfer powered by the native curl library
#
-# Download or upload over HTTP with `CurlHTTPRequest` and send emails with `CurlMail`.
+# Download or upload data over HTTP with `CurlHTTPRequest` and send emails
+# with `CurlMail`. Scripts can use the easier (but limited) services on `Text`,
+# `http_get` and `http_download`, provided by `curl::extra`.
module curl
import native_curl
-redef class Sys
- # Shared Curl library handle
- #
- # Usually, you do not have to use this attribute, it instancied by `CurlHTTPRequest` and `CurlMail`.
- # But in some cases you may want to finalize it to free some small resources.
- # However, if Curl services are needed once again, this attribute must be manually set.
- var curl: Curl = new Curl is lazy, writable
-end
-
-# Curl library handle, it is initialized and released with this class
-class Curl
+# Curl library handle
+private class Curl
super FinalizableOnce
- private var native = new NativeCurl.easy_init
+ var native = new NativeCurl.easy_init
- # Check for correct initialization
+ # Is this instance correctly initialized?
fun is_ok: Bool do return self.native.is_init
redef fun finalize_once do if is_ok then native.easy_clean
# CURL Request
class CurlRequest
- private var curl: Curl = sys.curl
+ private var curl = new Curl
# Shall this request be verbose?
var verbose: Bool = false is writable
do
return new CurlResponseFailed(error_code, error_msg)
end
+
+ # Close low-level resources associated to this request
+ #
+ # Once closed, this request can't be used again.
+ #
+ # If this service isn't called explicitly, low-level resources
+ # may be freed automatically by the GC.
+ fun close do curl.finalize
end
# HTTP request builder
do
# Reset libcurl parameters as the lib is shared and options
# might affect requests from one another.
- self.curl.native = new NativeCurl.easy_init
if not self.curl.is_ok then return answer_failure(0, "Curl instance is not correctly initialized")
var success_response = new CurlResponseSuccess
var st_code = self.curl.native.easy_getinfo_long(new CURLInfoLong.response_code)
if not st_code == null then success_response.status_code = st_code
- self.curl.native.easy_clean
-
return success_response
end
# Download to file given resource
fun download_to_file(output_file_name: nullable String): CurlResponse
do
+ if not self.curl.is_ok then return answer_failure(0, "Curl instance is not correctly initialized")
+
var success_response = new CurlFileResponseSuccess
var callback_receiver: CurlCallbacks = success_response
# Execute Mail request with settings configured through attribute
fun execute: nullable CurlResponseFailed
do
- self.curl.native = new NativeCurl.easy_init
if not self.curl.is_ok then return answer_failure(0, "Curl instance is not correctly initialized")
var lines = new Array[String]
var err_resp = perform
if err_resp != null then return err_resp
- self.curl.native.easy_clean
-
return null
end
end
class CurlResponseFailed
super CurlResponse
+ # Curl error code
var error_code: Int
+
+ # Curl error message
var error_msg: String
redef fun to_s do return "{error_msg} ({error_code})"
class CurlResponseSuccess
super CurlResponseSuccessIntern
- var body_str = ""
+ # Server HTTP response code
var status_code = 0
- # Receive body from request due to body callback registering
- redef fun body_callback(line) do
- self.body_str = "{self.body_str}{line}"
- end
+ # Response body as a `String`
+ var body_str = ""
+
+ # Accept part of the response body
+ redef fun body_callback(line) do self.body_str += line
end
# Success Response Class of a downloaded File
class CurlFileResponseSuccess
super CurlResponseSuccessIntern
+ # Server HTTP response code
var status_code = 0
+
var speed_download = 0.0
var size_download = 0.0
var total_time = 0.0
+
private var file: nullable FileWriter = null
# Receive bytes stream from request due to stream callback registering
# Get `self` as a single string for HTTP POST
#
# Require: `curl.is_ok`
- fun to_url_encoded(curl: Curl): String
+ private fun to_url_encoded(curl: Curl): String
do
assert curl.is_ok
--- /dev/null
+# This file is part of NIT ( http://www.nitlanguage.org ).
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Shortcut services for scripts: `http_get` and `http_download`
+module extra
+
+import curl
+
+redef class Text
+
+ # Execute a simple HTTP GET request to the URL `self`
+ #
+ # Set `accept_status_code` to the expected response HTTP code, defaults to 200.
+ # If a different status code is received, the return code is printed to stderr.
+ #
+ # Returns the response body on success and `null` on error. Prints the error
+ # message to stderr.
+ #
+ # For more control, set HTTP request headers, keep the response status code
+ # and much more, use `CurlHTTPRequest`.
+ #
+ # ~~~nitish
+ # assert "http://example.com/".http_get != null
+ # ~~~
+ fun http_get(accept_status_code: nullable Int): nullable String
+ do
+ var req = new CurlHTTPRequest(self.to_s)
+ var resp = req.execute
+ req.close
+
+ if resp isa CurlResponseSuccess then
+ if resp.status_code == (accept_status_code or else 200) then
+ return resp.body_str
+ else
+ print_error "HTTP request failed: server returned {resp.status_code}"
+ end
+ else if resp isa CurlResponseFailed then
+ print_error "HTTP request failed: {resp.error_msg}"
+ else abort
+ return null
+ end
+
+ # Download the file at URL `self` to `output_path` with a simple HTTP request
+ #
+ # If not set, `output_path` defaults to `self.basename`.
+ #
+ # Set `accept_status_code` to the expected response HTTP code, defaults to 200.
+ # If a different status code is received, the return code is printed to stderr.
+ #
+ # Returns the path to the downloaded file on success and `null` on errors.
+ # Prints the error message to stderr.
+ #
+ # For more control, set HTTP request headers, keep the response status code
+ # and much more, use `CurlHTTPRequest`.
+ #
+ # ~~~nitish
+ # assert "http://example.com/".http_download("index.html") == "example.com"
+ # ~~~
+ fun http_download(output_path: nullable Text, accept_status_code: nullable Int): nullable String
+ do
+ var path = (output_path or else self.basename).to_s
+
+ var req = new CurlHTTPRequest(self.to_s)
+ var resp = req.download_to_file(path)
+ req.close
+
+ if resp isa CurlFileResponseSuccess then
+ if resp.status_code == (accept_status_code or else 200) then
+ return path
+ else
+ print_error "HTTP request failed: server returned {resp.status_code}"
+ end
+ else if resp isa CurlResponseFailed then
+ print_error "HTTP request failed: {resp.error_msg}"
+ else abort
+ return null
+ end
+end