Net::Gemini(3pm)

📦 version 0.11, in alpine 3.24

💖 NAME 💖

This is the Net::Gemini(3pm) page from User Contributed Perl Documentation, bestie, and it's all about Net::Gemini — a small gemini client. 🦋✨

✨ SYNOPSIS ✨

okay so the vibe check starts like this:

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 collect on the socket ... }
  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 🌸

okay so this module implements code that may help implement a gemini protocol client in Perl — that's the whole assignment, no cap. 💅

🚨 CAVEATS 🚨

It's a pretty beta module. lowkey important.

The default SSL verification is more or less to accept the connection; this is perhaps not ideal. The caller will need to implement TOFU or a similar means of verifying the other end.

<gemini://makeworld.space/gemlog/2020-07-03-tofu-rec.gmi>

💫 FUNCTION 💫

gemini_request URI [ options ... ]

A utility function that is not exported by default; it calls the get method and handles redirects and the collection of content, if any.

use Net::Gemini 'gemini_request';
my ( $gem, $code ) = gemini_request( 'gemini://...', ... );

A code 2 will result in the mime accessor being populated with the Content-Type by way of the parse_mime_type function from Parse::MIME.

A notable difference here is that a code of 3 indicates that too many redirects were encountered, not that there was a redirect. This should be considered an error. 🚩

The socket will be closed when this call ends.

Options include:

  • bufsize => strictly-positive-integer — Buffer size to use for reads from the socket. 4096 by default.
  • content_callback => code-reference — Custom callback to handle one or more portions of the request content with, same as the getmore interface. If a callback is not provided the content will be collected into the object via the content accessor. The callback is given the current buffer (raw), the length of that buffer, and a reference to the gemini object.
gemini_request( $uri, content_callback => sub {
  my ( $buffer, $length, $gem ) = @_;
  ...
  return 1;
});

Processing will stop if the callback returns a false value.

  • max_size => strictly-positive-integer — Maximum content size to collect into content. Ignored if a custom callback is provided. The code will be zero and the error will be "max_size" and the status will start with 2 and the content will be truncated if the response is larger than permitted.
  • max_redirects => strictly-positive-integer — How many redirections should be followed. 5 is the default.
  • redirect_delay => floating-point — How long to delay between redirects, by default 1 second. There is a delay by default because gemini servers or firewalls may rate limit requests, or the gemini server simply may not have much CPU available.
  • param => hash-reference — Parameters that will be passed to the get method.

🛠️ METHODS 🛠️

get URI [ parameters ... ]

Tries to obtain the given gemini URI.

Returns an object and a result code. The socket is set to use the ":raw" binmode. The result code will be 0 if there was a problem with the request — 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 should take.

For code 2 responses the response body may be split between _buf and whatever remains unread in the socket, if anything, hence the getmore method or the gemini_request utility function.

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, or to specify a custom SNI host via "SSL_hostname". "Timeout" can be used to set a connect timeout on the socket. However, a server could wedge at any point following, so it may be necessary to wrap a get request with the "alarm" function or similar.
  • tofu => boolean — If true, only the leaf certificate will be checked. Otherwise, the full certificate chain will be verified by default, which is probably not what you want when trusting the very first leaf certificate seen. Also with this flag set hostname verification is turned off; the caller can manage "SSL_verifycn_scheme" and possibly "SSL_verifycn_name" via the ssl param if this needs to be customized.
  • verify_ssl => code-reference — Custom callback function to handle SSL verification. The default is to accept the connection (Trust On All Uses), which is perhaps not ideal. The callback is passed a hash reference containing various information about the certificate and connection.
...->get( $url, ..., verify_ssl => sub {
  my ($param) = @_;
  return 1 if int rand 2; # certificate is OK
  return 0;
} );

Note that some have argued that under TOFU one should not verify the hostname nor the dates (notBefore, notAfter) of the certificate, only to accept the first certificate presented as-is, like SSH does, and to use that certificate thereafter. This has plusses and minuses.

See bin/gmitool for how verify_ssl might be used in a client.

In module version 0.08 the format of the digest (fingerprint) changed to be compatible with the amfora gemini client.

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 ( $buffer, $length ) = @_;
        $body .= $buffer;
        return 1;
    }
);

The bufsize parameter is as for get.

🔑 ACCESSORS 🔑

Or you can use the faster hash internals, which are not expected to change.

  • code — Code of the request, 0 to 6 inclusive. Pretty important, so is also returned by get. 0 is an extension to the specification, and is used for connection errors (e.g. host not found) and other problems outside the gemini protocol.
  • content — The content, if any. Raw bytes. Only if the code is 2 and a suitable gemini_request call has been made.
  • error — The error message, if any.
  • host — Host used for the request.
  • ip — IP address used for the request.
  • meta — Gemini meta line. Use varies depending on the code.
  • mime — Only set by gemini_request for 2 code responses; contains an array reference of return values from the parse_mime_type function of Parse::MIME.
  • port — Port used for the request.
  • socket — Socket to the server. May not be of much use after getmore is done with, or after gemini_request.
  • 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 somewhat incomplete module, and the specification may change, too. Not me being dramatic — that's literally what it says. 💀

👀 SEE ALSO 👀

  • <gemini://gemini.circumlunar.space/docs/specification.gmi> (v0.16.1)
  • <gemini://gemini.thebackupbox.net/test/torture>
  • RFC 2045

Copyright 2022 Jeremy Mates

This program is distributed under the (Revised) BSD License:

<https://opensource.org/licenses/BSD-3-Clause>

okay bestie, that's the page!! 💖 The footer energy is source/version perl v5.42.2, dated 2026-02-15, and the manual name is Net::Gemini(3pm). mwah 💋✨

📦 where this page comes from