Ruby provides two levels of access to network services. At a low
level, you can access the basic socket support in the underlying
operating system, which allows you to implement clients and servers for
both connection-oriented and connectionless protocols. These are
documented in the next section.
Ruby also has libraries that provide higher-level access to
specific application-level network protocols, such as FTP,
HTTP, and so on. These are documented starting
on page 482.
Finally, the CGI libraries, documented beginning on page 497,
provide server-side developers with a
convenient interface for developing Web applications.
Sockets are the endpoints of a bidirectional communications
channel. Sockets may communicate within a process, between processes
on the same machine, or between processes on different
continents. Sockets may be implemented over a number of different
channel types: Unix domain sockets, TCP, UDP, and so on. The socket
library provides specific classes for handling the common transports
as well as a generic interface for handling the rest. All
functionality in the socket library is accessible through a single
extension library. Access it using
require 'socket'
Sockets have their own vocabulary:
domain
The family of protocols that will be used as the transport
mechanism. These values are constants such as PF_INET, PF_UNIX,
PF_X25, and so on.
type
The type of communications between the two endpoints, typically
SOCK_STREAM for connection-oriented protocols and
SOCK_DGRAM for connectionless protocols.
protocol
Typically zero, this may be used to identify a variant of a protocol
within a domain and type.
hostName
The identifier of a network interface:
a string, which can be a host name, a dotted-quad address, or
an IPV6 address in colon (and possibly dot) notation,
the string ``<broadcast>'', which specifies an
INADDR_BROADCAST address,
a zero-length string, which specifies INADDR_ANY, or
an Integer, interpreted as a binary address in host byte
order.
port
(sometimes called service)
Each server listens for clients calling on one or more ports.
A port may be a Fixnum port number, a string containing a port number, or the
name of a service.
Sockets are children of class IO. Once a socket has been
successfully opened, the conventional I/O methods may be used. However,
greater efficiency is sometimes obtained by using socket-specific
methods. As with other I/O classes, socket I/O blocks by default.
The hierarchy of the socket classes is shown in Figure
26.1 on page 471.
For more information on the use of sockets, see your operating system
documentation. You'll also find a comprehensive treatment in
W. Richard Stevens,
Unix Network Programming, Volumes 1 and
2 .
BasicSocket.do_not_reverse_lookup -> true or false
Returns the value of the global reverse lookup flag. If set to
true, queries on remote addresses will return the
numeric address but not the host name.
Sends aString over aSession. If specified, to is a
struct sockaddr specifying the recipient
address. flags are the sum or one or more of the
MSG_ options (listed on page 478). Returns the
number of characters sent.
Sets a socket option. level is one of the socket-level
options (listed on page 478). optname and
optval are protocol specific---see your system
documentation for details.
Returns the domain, port, name, and IP address of aSession as a
four-element array. The name will be returned as an address if
the do_not_reverse_lookup flag is true.
Receives up to len bytes on the connection. flags is
zero or more of the MSG_ options (listed
on page 478).
Returns a two-element
array. The first element is the received data, the second is an
array containing information about the peer.
t = TCPSocket.new('localhost', 'ftp')
data = t.recvfrom(30)
data
class SOCKSSocket
Parent:
TCPSocket
Version:
1.6
Index:
newopenclose
Class SOCKSSocket supports connections based on the SOCKS protocol.
Creates a new socket on the given
interface (identified by hostName and port). If
hostName is omitted, the server will listen on all
interfaces on the current host (equivalent to an address of
0.0.0.0).
Waits for a connection on aSession, and returns a new TCPSocket
connected to the caller. See the example
on page 474.
class UDPSocket
Parent:
IPSocket
Version:
1.6
Index:
newopenbindconnectrecvfromsend
UDP sockets send and receive datagrams. In order to receive data, a
socket must be bound to a particular port. You have two choices when
sending data: you can connect to a remote UDP socket and thereafter
send datagrams to that port, or you can specify a host and port for
use with every packet you send. This example is a UDP server that
prints the message it receives. It is called by both connectionless and
connection-based clients.
require 'socket'
$port = 4321
sThread = Thread.start do # run server in a thread
server = UDPSocket.open
server.bind(nil, $port)
2.times { p server.recvfrom(64) }
end
# Ad-hoc client
UDPSocket.open.send("ad hoc", 0, 'localhost', $port)
# Connection based client
sock = UDPSocket.open
sock.connect('localhost', $port)
sock.send("connection-based", 0)
sThread.join
Creates a connection to the given hostName and port.
Subsequent
UDPSocket#send requests that don't override the recipient
will use this connection. Multiple connect requests may be
issued on aSession: the most recent will be used by send.
Receives up to len bytes from aSession. flags is zero
or more of the MSG_ options (listed
on page 478).
The result is a two-element
array containing the received data and information on the
sender. See the example on page 475.
The two-parameter form sends aString on an existing
connection. The four-parameter form sends aString to
port on hostName.
class UNIXSocket
Parent:
BasicSocket
Version:
1.6
Index:
newopenaddrpathpeeraddrrecvfrom
Class UNIXSocket supports interprocess communications using the Unix
domain protocol. Although the underlying protocol supports both
datagram and stream connections, the Ruby library provides only a
stream-based connection.
require 'socket'
$path = "/tmp/sample"
sThread = Thread.start do # run server in a thread
sock = UNIXServer.open($path)
s1 = sock.accept
p s1.recvfrom(124)
end
client = UNIXSocket.open($path)
client.send("hello", 0)
client.close
sThread.join
Receives up to len bytes from aSession. flags is
zero or more of the MSG_ options (listed
on page 478).
The first element of the
returned array is the received data, and the second contains
(minimal) information on the sender.
class UNIXServer
Parent:
UNIXSocket
Version:
1.6
Index:
newopenaccept
Class UNIXServer provides a simple Unix domain socket
server. See UNIXSocket for example code.
Class Socket defines constants for use throughout the socket
library. Individual constants are available only on architectures
that support the related facility.
Returns an array of arrays describing the given host and
port (optionally qualified as shown). Each subarray
contains the address family, port number, host name, host IP
address, protocol family, socket type, and protocol.
for line in Socket.getaddrinfo('www.microsoft.com', 'http')
puts line.join(", ")
end
Returns a four-element array containing the canonical host name,
a subarray of host aliases, the address family, and the address
portion of the sockaddr structure.
Looks up the given address, which may be either a string
containing a sockaddr or a three- or four-element array. If
sockaddr is an array, it should contain the string address
family, the port (or nil), and the host name or IP address. If a
fourth element is present and not nil, it will be used as the host name.
Returns a canonical hostname (or address) and port number as an array.
a = Socket.getnameinfo(["AF_INET", '23', 'www.ruby-lang.org'])
Accepts an incoming connection returning an array containing a
new Socket object and a string holding the struct
sockaddr information about the caller.
Receives up to len bytes from aSession. flags is
zero or more of the MSG_ options. The first element of the
result is the data received. The second element contains
protocol-specific information on the sender.
Ruby provides a set of classes to facilitate writing clients for:
File Transfer Protocol (FTP)
HyperText Transfer Protocol (HTTP)
Post Office Protocol (POP)
Simple Mail Transfer Protocol (SMTP)
Telnet
HTTP, POP, and SMTP are layered on top of a helper class,
lib/net/protocol. Although we don't document the Protocol
class here, you should probably study it if you are considering
writing your own network client.
Creates and returns a new FTP object. If the host parameter is
not nil, a connection is made to that
host. Additionally, if the user parameter is not nil, the
given user name, password, and (optionally) account are
used to log in. See the description of FTP#login
on page 484.
Establishes an FTP connection to host, optionally overriding
the default port. If the environment variable
SOCKS_SERVER
is set, sets up the connection through
a SOCKS proxy. Raises an exception (typically
Errno::ECONNREFUSED) if the connection
cannot be established.
Retrieves remotefile in binary mode, storing the result in
localfile. If callback or an associated block is
supplied, calls it, passing in the retrieved data in
blocksize chunks.
Retrieves remotefile in ASCII (text) mode, storing the result in
localfile. If callback or an associated block is
supplied, calls it, passing in the retrieved data one line at a time.
Fetches a directory listing of files matching the given
pattern(s). If a block is associated with the call, invokes it
with each line of the result. Otherwise, returns the result as an
array of strings.
Logs into
the remote host. aSession must have been previously
connected. If user is the string ``anonymous'' and the
password is nil, a password of user@host is
synthesized. If the acct parameter is not nil, an FTP
ACCT command is sent following the successful
login. Raises an exception on error (typically
Net::FTPPermError).
Transfers localfile to the server in binary mode, storing
the result in
remotefile. If callback or an associated block is
supplied, calls it, passing in the transmitted data in
blocksize chunks.
Transfers localfile to the server in ASCII (text) mode,
storing the result in remotefile. If callback or an
associated block is supplied, calls it, passing in the
transmitted data one line at a time.
Sets the status of the resume flag. When resume is
true, partially received files will resume where they
left off, instead of starting from the beginning again. This is
done by sending a REST command (RESTart incomplete
transfer) to the server.
aSession.retrbinary(
cmd, blocksize ) {| data | block }
Puts the connection into binary (image) mode, issues the given
command, and fetches the data returned, passing it to the associated
block in chunks of blocksize characters. Note that
cmd is a server command (such as ``RETR myfile'').
Puts the connection into ASCII (text) mode, issues the given
command, and passes the resulting data, one line at a time, to the
associated block. If no block is given, prints the lines. Note that
cmd is a server command (such as ``RETR myfile'').
Puts the connection into binary (image) mode, issues the given
server-side command (such as ``STOR myfile''), and sends the
contents of the file named fileName to the server. If the optional
block is given, or if the callBack parameter is a Proc,
also passes it the data, in chunks of blocksize characters.
Puts the connection into ASCII (text) mode, issues the given
server-side command (such as ``STOR myfile''), and sends the
contents of the file named fileName to the server, one line at a
time. If the optional
block is given, or if the callBack parameter is a Proc,
also passes it the lines.
require 'net/http'
h = Net::HTTP.new('www.pragmaticprogrammer.com', 80)
resp, data = h.get('/index.html', nil )
puts "Code = #{resp.code}"
puts "Message = #{resp.message}"
resp.each {|key, val| printf "%-14s = %-40.40s\n", key, val }
p data[0..55]
produces:
Code = 200
Message = OK
last-modified = Wed, 29 May 2002 11:08:01 GMT
connection = close
content-type = text/html
etag = "804d98-255c-3cf4b691"
date = Sun, 09 Jun 2002 05:15:10 GMT
server = Rapidsite/Apa/1.3.20 (Unix) FrontPage/4.
content-length = 9564
accept-ranges = bytes
"<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.0 Transitional"
The net/http library provides a simple client to fetch headers
and Web page contents using the HTTP protocol.
The get, post, and head requests raise
exceptions on any error, including some HTTP status responses that
would normally be considered recoverable. There are two ways of
handling these.
Each method has a corresponding version get2,
post2, or head2 that does not raise an
exception. These versions are documented in the source.
Recoverable errors raise a
Net::ProtoRetriableError exception. This exception contains a
data attribute containing the response returned by the
server.
The code below illustrates the handling of an HTTP status 301, a redirect.
It uses Tomoyuki Kosimizu's URI
package, available in the RAA.
h = Net::HTTP.new(ARGV[0] || 'www.ruby-lang.org', 80)
url = ARGV[1] || '/'
begin
resp, data = h.get(url, nil) { |a| }
rescue Net::ProtoRetriableError => detail
head = detail.data
if head.code == "301"
uri = URI.create(head['location'])
host = uri['host']
url = uri['path']
port = uri['port']
h.finish
h = Net::HTTP.new(host, port)
retry
end
end
Retrieves headers and content from the specified path on
the host specified when aSession was created. If specified, the
headers parameter is a Hash containing additional
header names and values to be sent with the request. The method
returns a two-element array. The first element is an
HTTPResponse object (documented in the next section).
The second element is the page's content.
The page's content is also passed to the << method of
the dest parameter, or to the block if specified. This
result is built network block by network block, not line by line.
An exception is raised
if an error is encountered. Multiple get calls may be
made on aSession. Unless Protocol#finish is explicitly
called, the connection will use the HTTP/1.1 keep-alive
protocol, and will not close between requests.
Retrieves headers from the specified path on the host
specified when aSession was created. If specified, the
headers parameter is a hash containing additional
header names and values to be sent with the request. The method
returns a hash of received headers. An exception is raised if
an error is encountered. Multiple head calls may be
made on aSession.
Sends data to path using an HTTP POST
request. headers is a hash containing additional
headers. Assigns the result to data or to the block, as
for Net_HTTP#get. Returns a two-element array containing
an HTTPResponse object and the reply body.
Establishes a connection to the host associated with
aSession. (start is actually a method in
Net::Protocol, but its use is required in HTTP objects.) In
the block form, closes the session at the end of the block.
require 'net/pop'
pop = Net::POP3.new('server.ruby-stuff.com')
pop.start('user', 'secret') do |pop|
msg = pop.mails[0]
# Print the 'From:' header line
puts msg.header.split("\r\n").grep(/^From: /)
# Put message to $stdout (by calling <<)
puts "\nFull message:\n"
msg.all($stdout)
end
produces:
From: dummy msg for Andy
Full message:
From: dummy msg for Andy
looks-better: on dave's box
That's all folks!
The net/pop library provides a simple client to fetch and
delete mail on a Post Office Protocol (POP) server.
The class Net::POP3 is used to access a POP server, returning
a list of Net::POPMail objects, one per message stored on the
server. These POPMail objects are then used to fetch and/or
delete individual messages.
The library also provides an alternative to the POP3 class that
performs APOP authentication.
Closes the pop connection. Some servers require that a
connection is closed before they honor actions such as deleting
mail. Returns false if the connection was never used.
Establishes a connection to the pop server, using the supplied
username and password. Fetches a list of mail held on the server,
which may be accessed using the POP3#mails and
POP3#each methods. In block form, passes aSession to the
block, and closes the connection using finish when the
block terminates.
Fetches the corresponding e-mail from the server. With no argument
or associated block, returns the e-mail as a string. With an
argument but no block, appends the e-mail to dest by
invoking dest<< for each line in the e-mail. With
an associated block, invokes the block once for each line in the e-mail.
require 'net/smtp'
# --- Send using class methods
msg = [ "Subject: Test\n", "\n", "Now is the time\n" ]
Net::SMTP.start do |smtp|
smtp.sendmail( msg, 'dave@localhost', ['dave'] )
end
# --- Send using SMTP object and an adaptor
smtp = Net::SMTP.new
smtp.start('pragprog.com')
smtp.ready('dave@localhost', 'dave') do |a|
a.write "Subject: Test1\r\n"
a.write "\r\n"
a.write "And so is this"
end
The net/smtp library provides a simple client to send
electronic mail using the Simple Mail Transfer Protocol (SMTP).
Equivalent to Net::SMTP.new(server,
port).start(...). For an explanation of the remainder
of the parameters, see the instance method Net_SMTP#start.
Creates a new SMTP object. The domain parameter will be
used in the initial HELO or EHLO transaction with the
SMTP server. In the block form, the smtp object is passed
into the block. When the block terminates, the session is closed.
Equivalent to sendmail(from, to) { ...}.
Sends header and body lines to the sendmail server. The
from parameter is used as the sender's name in the
MAIL FROM: command, and the to is either a string or
an array of strings containing the recipients
for the RCPT TO: command.
The block is passed an adaptor object. Lines are
sent to the server by calling the adaptor's write method. The
terminating '.' and QUIT are sent automatically.
Sends header and body lines to the sendmail server. The
from parameter is used as the sender's name in the
MAIL FROM: command, and to is either a string or an
array of strings containing the
recipients for the RCPT TO: command.
Lines to be sent are fetched by invoking src.each. The
terminating '.' and QUIT are sent automatically.
Starts an SMTP session by connecting to the given domain
(host). If acct and passwd are given,
authentication will be attempted using the given
authentication type (:plain or :cram_md5). If a
block is supplied, it will be invoked with aSession as a
parameter. The connection will be closed when the block terminates.
Trying localhost...
Connected to localhost.
Welcome to SuSE Linux 7.1 (i386) - Kernel 2.4.0-64GB-SMP (8).
zip login: guest
Password:
Last login: Sun Jun 9 00:15:19 from localhost
/etc/zshrc: setopt: no such option: histexpiredupsfirst [31]
> date
Sun Jun 9 00:15:20 CDT 2002
>
Atomic time: Sun Jun 09 00:15:12 CDT 2002
Local time: Sun Jun 09 00:15:20 CDT 2002
The net/telnet library provides a complete implementation of a
telnet client and includes features that make it a convenient
mechanism for interacting with non-telnet services.
Although the class description that follows indicates that
Net::Telnet is a subclass of class Socket, this is a lie.
In reality, the class delegates to Socket. The net effect is the
same: the methods of Socket and its parent, class IO, are
available through Net::Telnet objects.
The methods new, cmd, login, and
waitfor take an optional block. If present, the block is
passed output from the server as it is received by the routine.
This can be used to provide realtime output, rather than waiting for
(for example) a login to complete before displaying the server's
response.
Sends a string to the server and waits (using a timeout) for a
string that matches a pattern to be returned by the server. If
the parameter is not a Hash, it is sent as a string to the server, and
the pattern to match and the timeout are the Prompt and
Timeout options given when aSession was created.
If options is a Hash, then options['String'] is
sent to the server. options['Match'] may be used to
override the class Prompt parameter, and options['Timeout']
the timeout. The method returns the complete server response.
If options is a Hash, a username is taken from
options['Name'] and a password from
options['Password']; otherwise, options is assumed to
be the username, and password the password. The method
waits for the server to send the string matching the pattern
/login[:]*\z/ and sends the username. If a
password is given, it then waits for the server to send
/Password[:]*\z/ and sends the password. The
method returns the full server response.
Waits for the server to respond with a string that matches a
string or pattern. If options is not a Hash, it
is compared against the cumulative server output as that output
is received using options.===. It is likely that you will
want to use a regular expression in this case.
If options is a Hash, then options['Match'],
options['Prompt'], or options['String'] provides the
match. In the latter case, the string will be converted to a
regular expression before being used. options may also
include the keys ``Timeout'' and ``Waittime'' to override the
class options of the same names.
(The output of this script is shown in Figure 26.2 on page 499.)
The CGI class provides support for programs used as a Web server
CGI (Common Gateway Interface) script. It contains several
methods for accessing fields in a CGI form, manipulating ``cookies'' and
the environment, and outputting formatted HTML.
Since environment variables contain a lot of useful information for
a CGI script, CGI makes accessing them very easy---environment
variables are accessible as attributes of CGI objects. For
instance, cgi.auth_type returns the value of
ENV["AUTH_TYPE"]. To create the method name, the environment
variable name is translated to all lowercase, and the
``HTTP_'' prefix is stripped off. Thus,
HTTP_USER_AGENT would be available as the method
user_agent.
Cookies are represented using a separate object of class
CGI::Cookie, containing the following accessors:
You create a cookie object using CGI_Cookie.new, which takes
as arguments the accessors listed above, or CGI_Cookie.parse,
which takes an encoded string and returns a cookie object.
Returns a URL-encoded string made from the given argument, where unsafe
characters (not alphanumeric, ``_'', ``-'', or ``.'') are encoded
using ``%xx'' escapes.
Returns a string made from the given argument with certain
HTML-special characters escaped. The HTML elements given in
elements will be escaped; other HTML elements will not
be affected.
Returns a string made from the given argument with
HTML-special characters (such as
``&'',``"'',``<'',``>'') quoted using
``&'', ``"'', ``<'',
``>'', and so on.
Returns a new CGI object. If HTML output is required, the
desired standards level must be given in aString
(otherwise, no output routines will be created). The level may be
one of:
Returns a string containing the given headers
(in the MOD_RUBY environment, the resulting header is
sent immediately instead). If a hash is given as an
argument, then the key-value pairs will be used to
generate headers.
Generates HTML output using the results of the block as the
content. Headers are generated as with CGI#header.
See the example at the start of this section.
In addition, CGI supports the following HTML output methods. Each
of these methods is named after the corresponding HTML feature (or
close to it). Those tags that require content (such as
blockquote) take an optional block; the block should return a
String that will be used as the content for the feature. These
methods may take arguments as indicated, or as a hash with the given
names as keys.
\ a( url ) a( HREF => )
base( url ) base( HREF => )
blockquote( cite="" ) { aString } blockquote( CITE => ) { aString }
caption( align=nil ) { aString } caption( ALIGN => ) { aString }
checkbox( name=nil, value=nil, checked=nil ) checkbox( NAME, VALUE, CHECKED => )
checkbox_group( name=nil, [items]+ ) checkbox_group( NAME, VALUES => )
Items may be individual String names, or any of:
an array of [ name, checked ],
an array of [ value, name ],
or an array of [ value, name, checked ].
The value for the hash key VALUES should be an array of these items.
Items may be individual String names, or any of:
an array of [ name, selected ],
an array of [ value, name ],
or an array of [ value, name, selected ].
The value for the hash key VALUES should be an array of these items.
Items may be individual String names, or any of:
an array of [ name, selected ],
an array of [ value, name ],
or an array of [ value, name, selected ].
The value for the hash key VALUES should be an array of these items.
reset( value=nil, name=nil ) reset( VALUE, NAME => )
scrolling_list( alias for popup_menu ) scrolling_list( => )
submit( value=nil, name=nil ) submit( VALUE, NAME => )
text_field( name="", value=nil, size=40,
maxlength=nil ) text_field( NAME, VALUE, SIZE, MAXLENGTH => )
textarea( name="", cols=70, rows=10 ) textarea( NAME, COLS, ROWS => )
\
In addition, all HTML tags are supported as methods, including
title, head, body, br, pre, and so on.
The block given to the method must return a String, which will be
used as the content for that tag type. Not all tags require content:
<P>, for example, does not.
The available tags vary according to the supported HTML level---Table
26.1 on page 503 lists the complete set. For these methods, you
can pass in a hash with attributes for the given tag. For instance, you
might pass in 'BORDER'=>'5' to the table method to set the
border width of the table.
HTML tags available as methods
{HTML 3}
a address applet area b base basefont big blockquote body br caption
center cite code dd dfn dir div dl dt em font form h1 h2 h3 h4 h5 h6
head hr html i img input isindex kbd li link listing map menu meta
ol option p param plaintext pre samp script select small strike
strong style sub sup table td textarea th title tr tt u ul var xmp
{HTML 4}
a abbr acronym address area b base bdo big blockquote body br
button caption cite code col colgroup dd del dfn div dl dt em
fieldset form h1 h2 h3 h4 h5 h6 head hr html i img input ins kbd
label legend li link map meta noscript object ol optgroup option p
param pre q samp script select small span strong style sub sup
table tbody td textarea tfoot th thead title tr tt ul var
{HTML 4 Transitional}
a abbr acronym address applet area b base basefont bdo big
blockquote body br button caption center cite code col colgroup dd
del dfn dir div dl dt em fieldset font form h1 h2 h3 h4 h5 h6 head
hr html i iframe img input ins isindex kbd label legend li link map
menu meta noframes noscript object ol optgroup option p param pre q
s samp script select small span strike strong style sub sup table
tbody td textarea tfoot th thead title tr tt u ul var
When dealing with a multipart form, the array returned by CGI#[]
is composed of objects of class Tempfile, with the following
dynamically added methods:
Method
Description
read
Body
local_path
Path to local file containing the content
original_filename
Original filename of the content
content_type
Content type
class CGI::Session
Parent:
Object
Version:
1.6
Index:
new[ ][ ]=deleteupdate
A CGI::Session maintains a persistent state for web users in a
CGI environment. Sessions may be memory-resident or may be stored
on disk. See the discussion on page 146 for details.
Returns a new session object for the CGI query. Options
that may be given in aHash include:
Option
Description
session_key
Name of CGI key for session
identification.
session_id
Value of session id.
new_session
If true, create a new session
id for this session. If false, use an
existing session identified by session_id. If
omitted, use an existing session if available,
otherwise create a new one.
database_manager
Class to use to save sessions; may be
CGI::Session::FileStore or
CGI::Session::MemoryStore
(or user defined if you're
brave). Default is FileStore.
Calls the delete method of the underlying database
manager. For FileStore, deletes the physical file
containing the session.
For MemoryStore, removes the session from memory.
![[visible space]](visible_space.gif){kind=small}
]*\z/