Debian Codegraph @

inc/Test/Net/SSLeay/Socket.pm

raw
1 package Test::Net::SSLeay::Socket;
2
3 use 5.008001;
4 use strict;
5 use warnings;
6
7 use Carp qw(croak);
8 use English qw( $EVAL_ERROR $OS_ERROR $OUTPUT_AUTOFLUSH -no_match_vars );
9 use Scalar::Util qw(refaddr reftype);
10 use SelectSaver;
11 use Socket qw(
12 AF_INET SOCK_DGRAM SOCK_STREAM
13 inet_aton inet_ntoa pack_sockaddr_in unpack_sockaddr_in
14 );
15
16 our $VERSION = '1.96';
17
18 my %PROTOS = (
19 tcp => SOCK_STREAM,
20 udp => SOCK_DGRAM,
21 );
22
23 sub new {
24 my ( $class, %args ) = @_;
25
26 my $self = bless {
27 addr => delete $args{addr} || '127.0.0.1',
28 port => delete $args{port} || 0,
29 proto => delete $args{proto} || 'tcp',
30 queue => delete $args{queue} || 5,
31 }, $class;
32
33 if ( !exists $PROTOS{ $self->{proto} } ) {
34 croak "Unknown protocol '$self->{proto}'";
35 }
36
37 $self->_init_server();
38
39 return $self;
40 }
41
42 sub _init_server {
43 my ($self) = @_;
44
45 my $addr = eval { inet_aton( $self->{addr} ) }
46 or croak 'Could not pack IP address'
47 . ( $EVAL_ERROR ? ": $EVAL_ERROR" : q{} );
48
49 my $sockaddr = eval { pack_sockaddr_in( $self->{port}, $addr ) }
50 or croak 'Could not create sockaddr_in structure'
51 . ( $EVAL_ERROR ? ": $EVAL_ERROR" : q{} );
52
53 socket $self->{sock}, AF_INET, $PROTOS{ $self->{proto} }, 0
54 or croak "Could not open server socket: $OS_ERROR";
55
56 if ( $self->{proto} eq 'tcp' ) {
57 bind $self->{sock}, $sockaddr
58 or croak "Could not bind server socket: $OS_ERROR";
59
60 listen $self->{sock}, $self->{queue}
61 or croak "Could not listen on server socket: $OS_ERROR";
62 }
63
64 my $sockname = getsockname $self->{sock};
65 ( $self->{sport}, $self->{saddr} ) = unpack_sockaddr_in($sockname);
66 $self->{saddr} = inet_ntoa( $self->{saddr} );
67
68 return 1;
69 }
70
71 sub get_addr {
72 my ($self) = @_;
73
74 return $self->{saddr};
75 }
76
77 sub get_port {
78 my ($self) = @_;
79
80 return $self->{sport};
81 }
82
83 sub accept {
84 my ( $self, $sock ) = @_;
85
86 if ( defined $sock && reftype($sock) ne 'GLOB' ) {
87 croak 'Argument #1 to accept() must be a typeglob reference';
88 }
89
90 accept $sock, $self->{sock}
91 or croak "Could not accept connection: $OS_ERROR";
92
93 my $saver = SelectSaver->new($sock);
94 local $OUTPUT_AUTOFLUSH = 1;
95
96 return $sock;
97 }
98
99 sub connect {
100 my ($self) = @_;
101
102 my $addr = eval { inet_aton( $self->{saddr} ) }
103 or croak 'Could not pack IP address in connect'
104 . ( $EVAL_ERROR ? ": $EVAL_ERROR" : q{} );
105
106 my $sockaddr = eval { pack_sockaddr_in( $self->{sport}, $addr ) }
107 or croak 'Could not create sockaddr_in structure in connect'
108 . ( $EVAL_ERROR ? ": $EVAL_ERROR" : q{} );
109
110 socket my $sock, AF_INET, $PROTOS{ $self->{proto} }, 0
111 or croak "Could not open server socket in connect: $OS_ERROR";
112 connect $sock, $sockaddr
113 or croak "Could not connect to server socket: $OS_ERROR";
114
115 my $saver = SelectSaver->new($sock);
116 local $OUTPUT_AUTOFLUSH = 1;
117
118 return $sock;
119 }
120
121 sub close {
122 my ($self) = @_;
123
124 return close $self->{sock};
125 }
126
127 1;
128
129 __END__
130
131 =head1 NAME
132
133 Test::Net::SSLeay::Socket - Socket class for the Net-SSLeay test suite
134
135 =head1 VERSION
136
137 This document describes version 1.96 of Test::Net::SSLeay::Socket.
138
139 =head1 SYNOPSIS
140
141 use Test::Net::SSLeay::Socket;
142
143 # Create TCP server socket listening on localhost on a random unused port
144 my $server = Test::Net::SSLeay::Socket->new( protocol => 'tcp' );
145
146 # To wait for a connection to the server socket:
147 my $sock = $server->accept();
148
149 # Open a connection to the server socket:
150 my $client_sock = $server->connect();
151
152 # Or do so using Net::SSLeay's high-level API:
153 use Net::SSLeay qw(tcpcat);
154 my ( $response, $err ) =
155 tcpcat( $server->get_addr(), $server->get_port(), 'request' );
156
157 =head1 DESCRIPTION
158
159 Test scripts in the Net-SSLeay test suite commonly need to establish server
160 and client sockets over which TLS communication can be tested. This module
161 simplifies the process of creating server sockets and client sockets that know
162 how to connect to them.
163
164 This module is not intended to be used directly by test scripts; use the
165 helper functions in L<Test::Net::SSLeay|Test::Net::SSLeay/"HELPER FUNCTIONS">
166 instead.
167
168 =head1 CONSTRUCTOR
169
170 =head2 new
171
172 # TCP server socket listening on localhost on a random unused port:
173 my $server = Test::Net::SSLeay::Socket->new();
174
175 # TCP server socket listening on a private IP address on the standard HTTP
176 # port:
177 my $server = Test::Net::SSLeay::Socket->new(
178 addr => '10.0.0.1',
179 port => 80,
180 proto => 'tcp',
181 );
182
183 Creates a new C<Test::Net::SSLeay::Socket> object. A server socket is created
184 that binds to a given (or the default) address and port number.
185
186 Supported options:
187
188 =over 4
189
190 =item *
191
192 C<addr> (optional): the IPv4 address that the server socket should bind to.
193 Defaults to C<'127.0.0.1'>.
194
195 =item *
196
197 C<port> (optional): the port number that the server socket should bind to.
198 Defaults to the number of a random unused port chosen by the operating system.
199
200 =item *
201
202 C<proto> (optional): the transport protocol that the server socket should use;
203 C<'tcp'> for TCP, C<'udp'> for UDP. Defaults to C<'tcp'>.
204
205 =item *
206
207 C<queue> (optional): the maximum number of pending connections to allow for
208 the server socket. Defaults to 5.
209
210 =back
211
212 Dies on failure.
213
214 =head1 METHODS
215
216 =head2 get_addr
217
218 my $address = $server->get_addr();
219
220 Returns the address on which the server socket is listening. Useful when
221 manually creating a connection to the server socket (e.g. via one of
222 Net::SSLeay's high-level API functions) and an address was not specified in
223 the constructor.
224
225 =head2 get_port
226
227 my $port = $server->get_port();
228
229 Returns the port number on which the server socket is listening. Useful when
230 manually creating a client socket to connect to the server socket (e.g. via
231 one of Net::SSLeay's high-level API functions) and a port number was not
232 specified in the constructor.
233
234 =head2 accept
235
236 # Communicate with the client, creating a new file handle:
237 my $sock = $server->accept();
238
239 # Communicate with the client using an existing typeglob as the file
240 # handle:
241 $server->accept(*Net::SSLeay::SSLCAT_S);
242
243 Accepts an incoming connection request to the server socket, and enables
244 autoflush on the resulting file handle.
245
246 If a typeglob is passed as the first argument, it becomes the socket's file
247 handle. This is useful when creating sockets for testing Net::SSLeay's
248 high-level API functions, which perform their operations on the
249 C<Net::SSLeay::SSLCAT_S> typeglob.
250
251 Returns the file handle for the new socket. Dies on failure.
252
253 =head2 connect
254
255 my $sock = $server->connect();
256
257 Creates a new connection to the server socket, and enables autoflush on the
258 resulting file handle.
259
260 Returns the file handle for the new socket. Dies on failure.
261
262 =head2 close
263
264 $server->close();
265
266 Closes the file handle for the server socket.
267
268 Returns true on success, or false on failure (just like Perl's
269 L<close|perlfunc/close> builtin).
270
271 =head1 SEE ALSO
272
273 L<Test::Net::SSLeay|Test::Net::SSLeay>, for an easier way to use this module
274 from Net-SSLeay test scripts.
275
276 =head1 BUGS
277
278 If you encounter a problem with this module that you believe is a bug, please
279 L<create a new issue|https://github.com/radiator-software/p5-net-ssleay/issues/new>
280 in the Net-SSLeay GitHub repository. Please make sure your bug report includes
281 the following information:
282
283 =over
284
285 =item *
286
287 the code you are trying to run (ideally a minimum working example that
288 reproduces the problem), or the full output of the Net-SSLeay test suite if
289 the problem relates to a test failure;
290
291 =item *
292
293 your operating system name and version;
294
295 =item *
296
297 the output of C<perl -V>;
298
299 =item *
300
301 the version of Net-SSLeay you are using;
302
303 =item *
304
305 the version of OpenSSL or LibreSSL you are using.
306
307 =back
308
309 =head1 AUTHORS
310
311 Originally written by Chris Novakovic.
312
313 Maintained by Chris Novakovic and Heikki Vatiainen.
314
315 =head1 COPYRIGHT AND LICENSE
316
317 Copyright 2020- Chris Novakovic <[email protected]>.
318
319 Copyright 2020- Heikki Vatiainen <[email protected]>.
320
321 This module is released under the terms of the Artistic License 2.0. For
322 details, see the C<LICENSE> file distributed with Net-SSLeay's source code.
323
324 =cut