Jekyll2023-10-17T08:21:03+00:00https://rubygems.guide/feed.xmlRubyGems.GuideTutorials for popular Ruby gemsdevise-two-factor2023-10-17T08:21:03+00:002023-10-17T08:21:03+00:00https://rubygems.guide/index
  • How to implement OTP two-factor authentication in Rails 6.1 with devise-two-factor
    • ]]>    Hopper Gee    RubyGems.Guide | rest-man | Exception2023-10-17T08:21:03+00:002023-10-17T08:21:03+00:00https://rubygems.guide/rest-man/exception

    Exception

    Exceptions (see http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)

    • for result codes between 200 and 207, a RestMan::Response will be returned
    • for result codes 301, 302 or 307, the redirection will be followed if the request is a GET or a HEAD
    • for result code 303, the redirection will be followed and the request transformed into a GET
    • for other cases, a RestMan::ExceptionWithResponse holding the Response will be raised; a specific exception class will be thrown for known error codes
    • call .response on the exception to get the server’s response

    Catch errors

    Most exceptions are collected under RestMan::RequestFaield.

    begin
  RestMan.get "http://example.com/test"
rescue => RestMan::RequestFailed => e
  e.response    #=> RestMan::Response
end

    Catch socket errors

    RestMan will propagate up socket errors without modification:

    RestMan.get 'http://example.com/test'
#=> Exception: Errno::ECONNREFUSED: Connection refused - connect(2) for "localhost" port 12345

    Catch EOFError

    RestMan::ServerBrokeConnection is translated from EOFError to give a better error message.

    begin
  RestMan.get 'http://example.com/test'
rescue RestMan::ServerBrokeConnection => error
  error.message         #=> Server broke connection
end

    Catch specific HTTP errors

    It may be more straightforward to use exceptions to handle different HTTP error response cases.

    begin
  response = RestMan.get('http://example.com/resource')
rescue RestMan::Unauthorized, RestMan::Forbidden => error
  puts 'Access denied'
  return error.response
rescue RestMan::ImATeapot =>error
  puts 'The server is a teapot! # RFC 2324'
  return error.response
else
  puts 'It worked!'
  return response
end
    ]]>    Hopper Gee    RubyGems.Guide | rest-man | Proxy2023-10-17T08:21:03+00:002023-10-17T08:21:03+00:00https://rubygems.guide/rest-man/proxy

    Proxy

    Set global proxy

    All calls to RestMan, including Resources, will use the proxy specified by RestMan.proxy.

    HEAD
    /test
    HTTP/1.1
    Accept: */*
    Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
    User-Agent: rest-man/1.1.0 (darwin21 arm64) ruby/3.1.2p20
    Host: example.com
    proxy
    HTTP/1.1
    200
    OK
    Content-Type: text/plain
    Hello world!
    simple
    advance
    resource
    cli 
    RestMan.proxy = "http://proxy.example.com"
RestMan.get "http://example.com/test"

response.code                 #=>200

    RestMan.proxy = "http://proxy.example.com"
response = RestMan::Request.execute(
  method: :get,
  url: "http://example.com/test"
)

response.code                 #=>200

    RestMan.proxy = "http://proxy.example.com"
resource = RestMan::Resource.new("http://example.com/test")
resposne = resource.get

response.code                 #=>200

    RestMan CLI hasn't support proxy customization.

    Set per-request proxy

    Specify a per-request proxy by passing the :proxy option to RestMan::Request. This will override any proxies set by environment variable or by the global RestMan.proxy value.

    HEAD
    /test
    HTTP/1.1
    Accept: */*
    Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
    User-Agent: rest-man/1.1.0 (darwin21 arm64) ruby/3.1.2p20
    Host: example.com
    proxy
    HTTP/1.1
    200
    OK
    Content-Type: text/plain
    Hello world!
    simple
    advance
    resource
    cli 
    RestMan simple mode hasn't support per-request proxy customization.
Please use advance mode.

    response = RestMan::Request.execute(
  method: :get,
  url: "http://example.com/test",
  proxy: "http://proxy.example.com"
)

response.code                 #=>200

    RestMan Resource hasn't support per-request proxy customization.
Please use advance mode.

    RestMan CLI hasn't support proxy customization.

    Disable proxy for a particular request

    HEAD
    /test
    HTTP/1.1
    Accept: */*
    Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
    User-Agent: rest-man/1.1.0 (darwin21 arm64) ruby/3.1.2p20
    Host: example.com
    HTTP/1.1
    200
    OK
    Content-Type: text/plain
    Hello world!
    simple
    advance
    resource
    cli 
    RestMan simple mode hasn't support per-request proxy customization.
Please use advance mode.

    RestMan.proxy = "http://proxy.example.com"
response = RestMan::Request.execute(
  method: :get,
  url: "http://example.com/test",
  proxy: nil
)

response.code                 #=>200

    RestMan Resource hasn't support per-request proxy customization.
Please use advance mode.

    RestMan CLI hasn't support proxy customization.
    ]]>    Hopper Gee    RubyGems.Guide | rest-man | Logging2023-10-17T08:21:03+00:002023-10-17T08:21:03+00:00https://rubygems.guide/rest-man/logging

    Logging

    To enable logging globally you can:

    Set RestMan.log with a Ruby Logger

    RestMan.log = STDOUT

    Or set an environment variable to avoid modifying the code (in this case you can use a file name, “stdout” or “stderr”):

    $ RESTCLIENT_LOG=stdout path/to/my/program

    You can also set individual loggers when instantiating a Resource or making an individual request:

    resource = RestMan::Resource.new 'http://example.com/resource', log: Logger.new(STDOUT)

RestMan::Request.execute(method: :get, url: 'http://example.com/foo', log: Logger.new(STDERR))

    All options produce logs like this:

    RestMan.get "http://some/resource"
# => 200 OK | text/html 250 bytes
RestMan.put "http://some/resource", "payload"
# => 401 Unauthorized | application/xml 340 bytes

    Note that these logs are valid Ruby, so you can paste them into the restman shell or a script to replay your sequence of rest calls.

    ]]>    Hopper Gee    RubyGems.Guide | rest-man | Retry2023-10-17T08:21:03+00:002023-10-17T08:21:03+00:00https://rubygems.guide/rest-man/retry

    Retry

    Manually set max retries

    The default max_retries is 1. You can change it to any number you like.

    HEAD
    /test
    HTTP/1.1
    Accept: */*
    Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
    User-Agent: rest-man/1.1.0 (darwin21 arm64) ruby/3.1.2p20
    Host: example.com
    HTTP/1.1
    200
    OK
    Content-Type: text/plain
    Hello world!
    simple
    advance
    resource
    cli 
    RestMan simple mode hasn't support retry customization.
Please use advance or resource mode.

    response = RestMan::Request.execute(
  method: :get,
  url: "http://example.com/test",
  max_retries: 0
)

response.code                 #=>200
response.headers                #=> Hash
response.headers[:content_type] #=> text/plain
response.body                   #=> Hello world! 

    resource = RestMan::Resource.new(
  "http://example.com/test",
  max_retries: 0
)
resposne = resource.get

response.code                 #=>200
response.headers                #=> Hash
response.headers[:content_type] #=> text/plain
response.body                   #=> Hello world! 

    RestMan CLI hasn't support SSL/TLS customization.
    ]]>    Hopper Gee    RubyGems.Guide | rest-man | Redirection2023-10-17T08:21:03+00:002023-10-17T08:21:03+00:00https://rubygems.guide/rest-man/redirection

    Redirection

    By default, rest-man will follow:

    • HTTP 301, 302, 307 redirection requests for GET and HEAD only
    • HTTP 303 redirection requests

    RestMan::Response exposes a #history method that returns a list of each response received in a redirection chain.

    Get responses in the redirection chain

    All calls to RestMan, including Resources, will use the proxy specified by RestMan.proxy.

    GET
    /test
    HTTP/1.1
    Accept: */*
    Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
    User-Agent: rest-man/1.1.0 (darwin21 arm64) ruby/3.1.2p20
    Host: example.com
    HTTP/1.1
    301
    Moved Permanently
    Content-Type: text/plain
    Location: http://www.example.com/test
    The document has moved to http://www.example.com/test
    GET
    /test
    HTTP/1.1
    Accept: */*
    Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
    User-Agent: rest-man/1.1.0 (darwin21 arm64) ruby/3.1.2p20
    Host: www.example.com
    HTTP/1.1
    200
    OK
    Content-Type: text/plain
    Hello world!
    simple
    advance
    resource
    cli 
    RestMan.get "http://example.com/test"

response.code                 #=> 200
response.request.url          #=> http://www.example.com/test

response.history              #=> Arry of RestMan::Response
response.history[0].code      #=> 301
response.history[0].url       #=> http://example.com/test

    response = RestMan::Request.execute(
  method: :get,
  url: "http://example.com/test"
)

response.code                 #=> 200
response.request.url          #=> http://www.example.com/test

response.history              #=> Arry of RestMan::Response
response.history[0].code      #=> 301
response.history[0].url       #=> http://example.com/test

    resource = RestMan::Resource.new("http://example.com/test")
resposne = resource.get

response.code                 #=> 200
response.request.url          #=> http://www.example.com/test

response.history              #=> Arry of RestMan::Response
response.history[0].code      #=> 301
response.history[0].url       #=> http://example.com/test

    $ restman get http://example.com/test

Hello world!

RestMan CLI hasn't support a way to check the history

    Disable auto redirection

    To disable automatic redirection, set :max_redirects => 0.

    GET
    /test
    HTTP/1.1
    Accept: */*
    Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
    User-Agent: rest-man/1.1.0 (darwin21 arm64) ruby/3.1.2p20
    Host: example.com
    HTTP/1.1
    301
    Moved Permanently
    Content-Type: text/plain
    Location: http://www.example.com/test
    The document has moved to http://www.example.com/test
    simple
    advance
    resource
    cli 
    RestMan simple mode hasn't support disable auto redirection.
Please use advance mode.

    begin
  RestMan::Request.execute(
    method: :get,
    url: "http://example.com/test",
    max_redirects: 0
  )
rescue => error
  error                             #=> 301 Moved Permanently
  error.response.code               #=> 301
  error.response.headers[:location] #=> http://www.example.com/test
  error.response.body               #=> The document has moved to http://www.example.com/test
end 

    RestMan Resource hasn't support disable auto redirection.
Please use advance mode.

    RestMan CLI hasn't support disable auto redirection.

    Manually follow redirection

    To manually follow redirection, you can call Response#follow_redirection. Or you could of course inspect the result and choose custom behavior.

    GET
    /test
    HTTP/1.1
    Accept: */*
    Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
    User-Agent: rest-man/1.1.0 (darwin21 arm64) ruby/3.1.2p20
    Host: example.com
    HTTP/1.1
    301
    Moved Permanently
    Content-Type: text/plain
    Location: http://www.example.com/test
    The document has moved to http://www.example.com/test
    GET
    /test
    HTTP/1.1
    Accept: */*
    Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
    User-Agent: rest-man/1.1.0 (darwin21 arm64) ruby/3.1.2p20
    Host: www.example.com
    HTTP/1.1
    200
    OK
    Content-Type: text/plain
    Hello world!
    simple
    advance
    resource
    cli 
    RestMan simple mode hasn't support disable auto redirection and manual follow redirection.
Please use advance mode.

    begin
  RestMan::Request.execute(
    method: :get,
    url: "http://example.com/test",
    max_redirects: 0
  )
rescue => error
  error.response.code               #=> 301
  error.response.headers[:location] #=> http://www.example.com/test

  response = error.response.follow_redirection
  response.code                     #=> 200
  response.request.url              #=> http://www.example.com/test
end 

    RestMan Resource hasn't support disable auto redirection and manual follow redirection.
Please use advance mode.

    RestMan CLI hasn't support manual follow redirectino.

    Follow redirection for POST request

    Follow redirections for all request types and not only for get and head

    RFC : If the 301, 302 or 307 status code is received in response to a request other than GET or HEAD, the user agent MUST NOT automatically redirect the request unless it can be confirmed by the user, since this might change the conditions under which the request was issued.

    POST
    /resource
    HTTP/1.1
    Accept: */*
    Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
    Host: example.com
    User-Agent: rest-man/1.1.0 (darwin21 arm64) ruby/3.1.2p20
    Content-Type: text/plain
    Content-Length: 14
    Hello, world!
    HTTP/1.1
    301
    Moved Permanently
    Content-Type: text/plain
    Location: http://www.example.com/resource
    The document has moved to http://www.example.com/resource
    POST
    /resource
    HTTP/1.1
    Accept: */*
    Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
    Host: www.example.com
    User-Agent: rest-man/1.1.0 (darwin21 arm64) ruby/3.1.2p20
    Content-Type: text/plain
    Content-Length: 14
    Hello, world!
    HTTP/1.1
    200
    OK
    Content-Type: text/plain
    Text received.
    simple
    advance
    resource
    cli 
    # block style
RestMan.post("http://example.com/resource", "Hello, world!", { content_type: "text/plain" }) do |response, request, result|
  case response.code
  when 301, 302, 307
    response.follow_redirection
  else
    response.return!
  end
end

# exception style by explicit classes
begin
  RestMan.post("http://example.com/resource", "Hello, world!", { content_type: "text/plain" }) 
rescue RestMan::MovedPermanently, RestMan::Found, RestMan::TemporaryRedirect => error
  error.response.follow_redirection
end

# exception style by response code
begin
  RestMan.post("http://example.com/resource", "Hello, world!", { content_type: "text/plain" }) 
rescue RestMan::ExceptionWithResponse => error
  case error.http_code
  when 301, 302, 307
    error.response.follow_redirection
  else
    raise
  end
end

    # block style
RestMan::Request.execute(
  method: :post,
  url: "http://example.com/resource",
  payload: "Hello, world!",
  headers: { content_type: "text/plain" }
) do |response, request, result|
  case response.code
  when 301, 302, 307
    response.follow_redirection
  else
    response.return!
  end
end

# exception style by explicit classes
begin
  RestMan::Request.execute(
    method: :post,
    url: "http://example.com/resource",
    payload: "Hello, world!",
    headers: { content_type: "text/plain" }
  )
rescue RestMan::MovedPermanently, RestMan::Found, RestMan::TemporaryRedirect => error
  error.response.follow_redirection
end

# exception style by response code
begin
  RestMan::Request.execute(
    method: :post,
    url: "http://example.com/resource",
    payload: "Hello, world!",
    headers: { content_type: "text/plain" }
  )
rescue RestMan::ExceptionWithResponse => error
  case error.http_code
  when 301, 302, 307
    error.response.follow_redirection
  else
    raise
  end
end

    resource = RestMan::Resource.new("http://example.com/resource")

# block style
resource.post("Hello, world!", {content_type: "text/plain"}) do |response, request, result|
  case response.code
  when 301, 302, 307
    response.follow_redirection
  else
    response.return!
  end
end

# exception style by explicit classes
begin
  resource.post("Hello, world!", {content_type: "text/plain"})
rescue RestMan::MovedPermanently, RestMan::Found, RestMan::TemporaryRedirect => error
  error.response.follow_redirection
end

# exception style by response code
begin
  resource.post("Hello, world!", {content_type: "text/plain"})
rescue RestMan::ExceptionWithResponse => error
  case error.http_code
  when 301, 302, 307
    error.response.follow_redirection
  else
    raise
  end
end

    RsetMan CLI doesn't offer a way to follow redirection. You have to doing it manually.
    ]]>    Hopper Gee    RubyGems.Guide | rest-man | SSL/TLS2023-10-17T08:21:03+00:002023-10-17T08:21:03+00:00https://rubygems.guide/rest-man/ssl-tls

    SSL/TLS Support

    Various options are supported for configuring rest-man’s TLS settings. By default, rest-man will verify certificates using the system’s CA store on all platforms. This is intended to be similar to how browsers behave. You can also customize it as you like.

    • Customize the certificate authorities by specify :ssl_ca_file, :ssl_ca_path, or :ssl_cert_store.
    • Set client certificate for mutual authentication by specify :ssl_client_cert and :ssl_client_key

    Self-signed certificates can be generated with the openssl command-line tool.

    Customize certificate authorities

    HEAD
    /test
    HTTP/1.1
    Accept: */*
    Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
    User-Agent: rest-man/1.1.0 (darwin21 arm64) ruby/3.1.2p20
    Host: example.com
    HTTP/1.1
    200
    OK
    Content-Type: text/plain
    Hello world!
    simple
    advance
    resource
    cli 
    RestMan simple mode hasn't support SSL/TLS customization.
Please use advance or resource mode.

    # Customize ssl_ca_file
response = RestMan::Request.execute(
  method: :get,
  url: "https://example.com/test",
  ssl_ca_file: "/path/to/ca_certs.pem"
  verify_ssl: OpenSSL::SSL::VERIFY_PEER
)

# Customize ssl_ca_path
response = RestMan::Request.execute(
  method: :get,
  url: "https://example.com/test",
  ssl_ca_path: "/path/to/certs"
  verify_ssl: OpenSSL::SSL::VERIFY_PEER
)

# Customize ssl_cert_store
store = OpenSSL::X509::Store.new
store.set_default_paths
cert = OpenSSL::X509::Certificate.new(File.read('path/to/certificate.pem'))
store.add_cert(cert)
response = RestMan::Request.execute(
  method: :get,
  url: "https://example.com/test",
  ssl_cert_store: store,
  verify_ssl: OpenSSL::SSL::VERIFY_PEER
)

response.code                 #=>200
response.headers                #=> Hash
response.headers[:content_type] #=> text/plain
response.body                   #=> Hello world! 

    # Customize ssl_ca_file
resource = RestMan::Resource.new(
  "https://example.com/test",
  ssl_ca_file: "/path/to/ca_certs.pem"
  verify_ssl: OpenSSL::SSL::VERIFY_PEER
)
resposne = resource.get

# Customize ssl_ca_path
resource = RestMan::Resource.new(
  "https://example.com/test",
  ssl_ca_path: "/path/to/certs"
  verify_ssl: OpenSSL::SSL::VERIFY_PEER
)
resposne = resource.get

# Customize ssl_cert_store
store = OpenSSL::X509::Store.new
store.set_default_paths
cert = OpenSSL::X509::Certificate.new(File.read('path/to/certificate.pem'))
store.add_cert(cert)
resource = RestMan::Resource.new(
  "https://example.com/test",
  ssl_cert_store: store,
  verify_ssl: OpenSSL::SSL::VERIFY_PEER
)
resposne = resource.get

response.code                 #=>200
response.headers                #=> Hash
response.headers[:content_type] #=> text/plain
response.body                   #=> Hello world! 

    RestMan CLI hasn't support SSL/TLS customization.

    Customize client certificates

    HEAD
    /test
    HTTP/1.1
    Accept: */*
    Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
    User-Agent: rest-man/1.1.0 (darwin21 arm64) ruby/3.1.2p20
    Host: example.com
    HTTP/1.1
    200
    OK
    Content-Type: text/plain
    Hello world!
    simple
    advance
    resource
    cli 
    RestMan simple mode hasn't support SSL/TLS customization.
Please use advance or resource mode.

    response = RestMan::Request.execute(
  method: :get,
  url: "https://example.com/test",
  ssl_client_cert: OpenSSL::X509::Certificate.new(File.read("client.crt")),
  ssl_client_key: OpenSSL::PKey::RSA.new(File.read("client.key"))
)

response.code                 #=>200
response.headers                #=> Hash
response.headers[:content_type] #=> text/plain
response.body                   #=> Hello world! 

    resource = RestMan::Resource.new(
  "https://example.com/test",
  ssl_client_cert: OpenSSL::X509::Certificate.new(File.read("client.crt")),
  ssl_client_key: OpenSSL::PKey::RSA.new(File.read("client.key"))
)
resposne = resource.get

response.code                 #=>200
response.headers                #=> Hash
response.headers[:content_type] #=> text/plain
response.body                   #=> Hello world! 

    RestMan CLI hasn't support SSL/TLS customization.
    ]]>    Hopper Gee    RubyGems.Guide | rest-man | HTTP Status2023-10-17T08:21:03+00:002023-10-17T08:21:03+00:00https://rubygems.guide/rest-man/status

    Status Code

    1XX Informational
    100 RestMan::Continue Continue
    101 RestMan::SwitchingProtocols Switching Protocols
    102 RestMan::Processing Processing
    2XX Success
    200 RestMan::OK OK
    201 RestMan::Created Created
    202 RestMan::Accepted Accepted
    203 RestMan::NonAuthoritativeInformation Non-Authoritative Information
    204 RestMan::NoContent No Content
    205 RestMan::ResetContent Reset Content
    206 RestMan::PartialContent Partial Content
    207 RestMan::MultiStatus Multi-Status
    208 RestMan::AlreadyReported Already Reported
    226 RestMan::IMUsed IM Used
    3XX Redirection
    300 RestMan::MultipleChoices Multiple Choices
    301 RestMan::MovedPermanently Moved Permanently
    302 RestMan::Found Found
    303 RestMan::SeeOther See Other
    304 RestMan::NotModified Not Modified
    305 RestMan::UseProxy Use Proxy
    306 RestMan::SwitchProxy Switch Proxy
    307 RestMan::TemporaryRedirect Temporary Redirect
    308 RestMan::PermanentRedirect Permanent Redirect
    4XX Client Error
    400 RestMan::BadRequest Bad Request
    401 RestMan::Unauthorized Unauthorized
    402 RestMan::PaymentRequired Payment Required
    403 RestMan::Forbidden Forbidden
    404 RestMan::NotFound Not Found
    405 RestMan::MethodNotAllowed Method Not Allowed
    406 RestMan::NotAcceptable Not Acceptable
    407 RestMan::ProxyAuthenticationRequired Proxy Authentication Required
    408 RestMan::RequestTimeout Request Timeout
    409 RestMan::Conflict Conflict
    410 RestMan::Gone Gone
    411 RestMan::LengthRequired Length Required
    412 RestMan::PreconditionFailed Precondition Failed
    413 RestMan::PayloadTooLarge Payload Too Large
    414 RestMan::URITooLong URI Too Long
    415 RestMan::UnsupportedMediaType Unsupported Media Type
    416 RestMan::RangeNotSatisfiable Range Not Satisfiable
    417 RestMan::ExpectationFailed Expectation Failed
    418 RestMan::ImATeapot I'm A Teapot
    421 RestMan::TooManyConnectionsFromThisIP Too Many Connections From This IP
    422 RestMan::UnprocessableEntity Unprocessable Entity
    423 RestMan::Locked Locked
    424 RestMan::FailedDependency Failed Dependency
    425 RestMan::UnorderedCollection Unordered Collection
    426 RestMan::UpgradeRequired Upgrade Required
    428 RestMan::PreconditionRequired Precondition Required
    429 RestMan::TooManyRequests Too Many Requests
    431 RestMan::RequestHeaderFieldsTooLarge Request Header Fields Too Large
    449 RestMan::RetryWith Retry With
    450 RestMan::BlockedByWindowsParentalControls Blocked By Windows Parental Controls
    5XX Server Error
    500 RestMan::InternalServerError Internal Server Error
    501 RestMan::NotImplemented Not Implemented
    502 RestMan::BadGateway Bad Gateway
    503 RestMan::ServiceUnavailable Service Unavailable
    504 RestMan::GatewayTimeout Gateway Timeout
    505 RestMan::HTTPVersionNotSupported HTTP Version Not Supported
    506 RestMan::VariantAlsoNegotiates Variant Also Negotiates
    507 RestMan::InsufficientStorage Insufficient Storage
    508 RestMan::LoopDetected Loop Detected
    509 RestMan::BandwidthLimitExceeded Bandwidth Limit Exceeded
    510 RestMan::NotExtended Not Extended
    511 RestMan::NetworkAuthenticationRequired Network Authentication Required
    ]]>    Hopper Gee    RubyGems.Guide | rest-man | Streaming2023-10-17T08:21:03+00:002023-10-17T08:21:03+00:00https://rubygems.guide/rest-man/streaming

    Streaming

    Streaming request payload

    RestMan will try to stream any file-like payload rather than reading it into memory. This happens through RestMan::Payload::Streamed, which is automatically called internally by RestMan::Payload.generate on anything with a read method.

    PUT
    /api/image
    HTTP/1.1
    Accept: */*
    Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
    Host: example.com
    User-Agent: rest-man/1.1.0 (darwin21 arm64) ruby/3.1.2p20
    Content-Type: image/jpeg
    Content-Length: 143685
    ["JPEG binary data goes here"]
    HTTP/1.1
    200
    OK
    Content-Type: text/plain
    Image uploaded successfully
    simple
    advance
    resource
    cli 
    response = RestMan.put(
  'http://example.com/api/image',
  File.open("./files/profile.jpg", 'r'),
  {content_type: :jpg}
)

response.code                   #=> 200
response.headers                #=> Hash
response.headers[:content_type] #=> text/plain
response.body                   #=> Image uploaded successfully

    response = RestMan::Request.execute(
  method: :put,
  url: 'http://example.com/api/image',
  payload: File.open("./files/profile.jpg", 'r'),
  headers: { content_type: :jpg }
)

response.code                   #=> 200
response.headers                #=> Hash
response.headers[:content_type] #=> text/plain
response.body                   #=> Image uploaded successfully

    resource = RestMan::Resource.new("http://example.com/api/image")
response = resource.put(
  File.open("./files/profile.jpg", 'r'),
  {content_type: :jpg}
)

response.code                   #=> 200
response.headers                #=> Hash
response.headers[:content_type] #=> text/plain
response.body                   #=> Image uploaded successfully

    RestMan CLI hasn't support file upload with custom headers

    Streaming responses

    Use raw_response with Tempfile

    If you pass raw_response: true to RestMan::Request.execute, it will save the response body to a temporary file (using Tempfile) and return a RestMan::RawResponse object rather than a RestMan::Response.

    Note that the tempfile created by Tempfile.new will be in Dir.tmpdir (usually /tmp/), which you can override to store temporary files in a different location. This file will be unlinked when it is dereferenced.

    If logging is enabled, this will also print download progress. Customize the interval with :stream_log_percent (defaults to 10 for printing a message every 10% complete).

    For example:

    raw = RestMan::Request.execute(
  method: :get,
  url: 'http://releases.ubuntu.com/16.04.2/ubuntu-16.04.2-desktop-amd64.iso',
  raw_response: true
)
#=> <RestMan::RawResponse
# @code=200,@file=#<Tempfile:/tmp/rest-man.20170522-5346-1pptjm1>,
# @request=<RestMan::Request @method="get",
# @url="http://releases.ubuntu.com/16.04.2/ubuntu-16.04.2-desktop-amd64.iso">>

raw.file.size     #=> 1554186240
raw.file.path     #=> "/tmp/rest-man.20170522-5346-1pptjm1"
raw.file.path     #=> "/tmp/rest-man.20170522-5346-1pptjm1"

require 'digest/sha1'
Digest::SHA1.file(raw.file.path).hexdigest
#=> "4375b73e3a1aa305a36320ffd7484682922262b3"

    Use block_response to receive raw Net::HTTPResponse

    If you want to stream the data from the response to a file as it comes, rather than entirely in memory, you can also pass RestMan::Request.execute a parameter :block_response to which you pass a block/proc. This block receives the raw unmodified Net::HTTPResponse object from Net::HTTP, which you can use to stream directly to a file as each chunk is received.

    Note that this bypasses all the usual HTTP status code handling, so you will want to do you own checking for HTTP 20x response codes, redirects, etc.

    The following is an example:

    File.open('/some/output/file', 'w') {|f|
  block = proc { |response|
    response.read_body do |chunk|
      f.write chunk
    end
  }
  RestMan::Request.execute(
    method: :get,
    url: 'http://example.com/some/really/big/file.img',
    block_response: block
  )
}
    ]]>    Hopper Gee    RubyGems.Guide | rest-man | Timeout2023-10-17T08:21:03+00:002023-10-17T08:21:03+00:00https://rubygems.guide/rest-man/timeout

    Timeout

    Set Read Timeout

    The default read_timeout is from net/http which is based on the Ruby version you’re using.

    HEAD
    /test
    HTTP/1.1
    Accept: */*
    Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
    User-Agent: rest-man/1.1.0 (darwin21 arm64) ruby/3.1.2p20
    Host: example.com
    HTTP/1.1
    200
    OK
    Content-Type: text/plain
    Hello world!
    simple
    advance
    resource
    cli 
    RestMan simple mode hasn't support timeout customization.
Please use advance or resource mode.

    response = RestMan::Request.execute(
  method: :get,
  url: "http://example.com/test",
  read_timeout: 30
)

response.code                 #=>200
response.headers                #=> Hash
response.headers[:content_type] #=> text/plain
response.body                   #=> Hello world! 

    resource = RestMan::Resource.new(
  "http://example.com/test",
  read_timeout: 30
)
resposne = resource.get

response.code                 #=>200
response.headers                #=> Hash
response.headers[:content_type] #=> text/plain
response.body                   #=> Hello world! 

    RestMan CLI hasn't support timeout customization.

    Set Open Timeout

    The default open_timeout is from net/http which is based on the Ruby version you’re using.

    HEAD
    /test
    HTTP/1.1
    Accept: */*
    Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
    User-Agent: rest-man/1.1.0 (darwin21 arm64) ruby/3.1.2p20
    Host: example.com
    HTTP/1.1
    200
    OK
    Content-Type: text/plain
    Hello world!
    simple
    advance
    resource
    cli 
    RestMan simple mode hasn't support timeout customization.
Please use advance or resource mode.

    response = RestMan::Request.execute(
  method: :get,
  url: "http://example.com/test",
  open_timeout: 30
)

response.code                 #=>200
response.headers                #=> Hash
response.headers[:content_type] #=> text/plain
response.body                   #=> Hello world! 

    resource = RestMan::Resource.new(
  "http://example.com/test",
  open_timeout: 30
)
resposne = resource.get

response.code                 #=>200
response.headers                #=> Hash
response.headers[:content_type] #=> text/plain
response.body                   #=> Hello world! 

    RestMan CLI hasn't support timeout customization.

    Set Write Timeout

    The default write_timeout is from net/http which is based on the Ruby version you’re using.

    HEAD
    /test
    HTTP/1.1
    Accept: */*
    Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
    User-Agent: rest-man/1.1.0 (darwin21 arm64) ruby/3.1.2p20
    Host: example.com
    HTTP/1.1
    200
    OK
    Content-Type: text/plain
    Hello world!
    simple
    advance
    resource
    cli 
    RestMan simple mode hasn't support timeout customization.
Please use advance or resource mode.

    response = RestMan::Request.execute(
  method: :get,
  url: "http://example.com/test",
  write_timeout: 30
)

response.code                 #=>200
response.headers                #=> Hash
response.headers[:content_type] #=> text/plain
response.body                   #=> Hello world! 

    resource = RestMan::Resource.new(
  "http://example.com/test",
  write_timeout: 30
)
resposne = resource.get

response.code                 #=>200
response.headers                #=> Hash
response.headers[:content_type] #=> text/plain
response.body                   #=> Hello world! 

    RestMan CLI hasn't support timeout customization.

    Set SSL Timeout

    The default ssl_timeout is from net/http which is based on the Ruby version you’re using.

    HEAD
    /test
    HTTP/1.1
    Accept: */*
    Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
    User-Agent: rest-man/1.1.0 (darwin21 arm64) ruby/3.1.2p20
    Host: example.com
    HTTP/1.1
    200
    OK
    Content-Type: text/plain
    Hello world!
    simple
    advance
    resource
    cli 
    RestMan simple mode hasn't support timeout customization.
Please use advance or resource mode.

    response = RestMan::Request.execute(
  method: :get,
  url: "http://example.com/test",
  ssl_timeout: 30
)

response.code                 #=>200
response.headers                #=> Hash
response.headers[:content_type] #=> text/plain
response.body                   #=> Hello world! 

    resource = RestMan::Resource.new(
  "http://example.com/test",
  ssl_timeout: 30
)
resposne = resource.get

response.code                 #=>200
response.headers                #=> Hash
response.headers[:content_type] #=> text/plain
response.body                   #=> Hello world! 

    RestMan CLI hasn't support timeout customization.

    Set Keep-Alive Timeout

    The default keep_alive_timeout is from net/http which is based on the Ruby version you’re using.

    HEAD
    /test
    HTTP/1.1
    Accept: */*
    Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
    User-Agent: rest-man/1.1.0 (darwin21 arm64) ruby/3.1.2p20
    Host: example.com
    HTTP/1.1
    200
    OK
    Content-Type: text/plain
    Hello world!
    simple
    advance
    resource
    cli 
    RestMan simple mode hasn't support timeout customization.
Please use advance or resource mode.

    response = RestMan::Request.execute(
  method: :get,
  url: "http://example.com/test",
  keep_alive_timeout: 30
)

response.code                 #=>200
response.headers                #=> Hash
response.headers[:content_type] #=> text/plain
response.body                   #=> Hello world! 

    resource = RestMan::Resource.new(
  "http://example.com/test",
  keep_alive_timeout: 30
)
resposne = resource.get

response.code                 #=>200
response.headers                #=> Hash
response.headers[:content_type] #=> text/plain
response.body                   #=> Hello world! 

    RestMan CLI hasn't support timeout customization.
    ]]>    Hopper Gee