/ 
Net-Gemini-0.02
River stage zero No dependents
/ Net::Gemini

NAME

Net::Gemini - a small gemini client

SYNOPSIS

use Net::Gemini;
my ($gem, $code) = Net::Gemini->get('gemini://example.org/');

use Syntax::Keyword::Match;
match($code : ==) {
  case(0) { die "request failed " . $gem->error }
  case(1) { ... $gem->meta as prompt for input ... }
  case(2) { ... $gem->meta and $gem->content and ... }
  case(3) { ... $gem->meta as redirect ... }
  case(4) { ... $gem->meta as temporary failure ... }
  case(5) { ... $gem->meta as permanent failure ... }
  case(6) { ... $gem->meta as client certificate message ... }
}

DESCRIPTION

This module implements code that may help implement a gemini client.

CAVEATS

The default SSL verification scheme is used. So it's not TOFU (Trust on First Use); that will require customizing IO::Socket::SSL.

METHODS

get URI [ parameters ... ]

Tries to obtain the given gemini URI. Returns an object and a result code. The result code will be 0 if there was a problem with the request (e.g. that the URI failed to parse, or the connection failed) or otherwise a gemini code in the range of 1 to 6 inclusive, which will indicate the next steps any subsequent code probably should take.

For code 2 responses the response body may be split between content and whatever remains unread in the socket, and will be undecoded.

Parameters include:

bufsize => strictly-positive-integer

Size of buffer to use for requests, 4096 by default. Note that a naughty server may return data in far smaller increments than this.

ssl => { params }

Passes the given parameters to the IO::Socket::SSL constructor. These could be used to configure e.g. the SSL_verify_mode or to set a verification callback.

IO::Socket::SSL::set_defaults may also be of use in client code.

getmore callback [ bufsize => n ]

A callback interface is provided to consume the response body, if any. Generally this should only be present for response code 2. The meta line should be consulted for details on the MIME type and encoding of the bytes; $body in the following code may need to be decoded.

my $body = '';
$gem->getmore(
    sub {
        my ( $status, $buffer ) = @_;
        return 0 if !defined $status or $status == 0;
        $body .= $buffer;
        return 1;
    }
);

The bufsize parameter is as for get.

ACCESSORS

code

Code of the request, 0 to 6 inclusive. Pretty important, so is also returned by get.

content

The content, if any. Raw bytes. Only if the code is 2.

error

The error message, if any.

host

Host used for the request.

meta

Gemini meta line. Use varies depending on the code.

port

Port used for the request.

socket

Socket to the server. May not be of much use after getmore is done with.

status

Status of the request, a two digit number. Only set when the code is a gemini response (that is, not an internal 0 code).

uri

URI used for the request. Probably could be used with any relative URL returned from the server.

BUGS

None known. But it is a rather incomplete module; that may be considered a bug?

SEE ALSO

Net::Gemini::URI

gemini://gemini.circumlunar.space/docs/specification.gmi (v0.16.1)

RFC 3986

COPYRIGHT AND LICENSE

Copyright 2022 Jeremy Mates

This program is distributed under the (Revised) BSD License: https://opensource.org/licenses/BSD-3-Clause