Bug#932946: libhttp-server-simple-perl: Please document "minimal implementation" listening socket FH

[Ian Jackson]

Package: libhttp-server-simple-perl
Version: 0.51-1
Severity: normal
Tags: upstream patch

Hi.  Please find attached a docs patch for this package.  Quoting my
own commit message:

  Document the minimal server listening socket filehandle name

  Knowing this is useful in post_setup_hook, or maybe if
  one wants to override setup_hook without reimplementing run (ie, the
  code in _default_run).

  For example, if one wants HTTP::Server::Simple to bind to any free
  port, one can override port to specify 0, so that the OS chooses a
  free port.  But one then needs to get the port number out somehow and
  the obvious method is calling getsockname on the filehandle.

  So document this.  It seems unlikely that the minimal implementation
  will want or need to change this.

If you agree with my suggestion, I would appreciate it if you would
forward this bug upstream.

Thanks,
Ian.

-- System Information:
Debian Release: 9.9
  APT prefers oldstable-debug
  APT policy: (500, 'oldstable-debug'), (500, 'oldstable')
Architecture: amd64 (x86_64)
Foreign Architectures: i386

Kernel: Linux 4.19.0-0.bpo.5-amd64 (SMP w/4 CPU cores)
Locale: LANG=C.UTF-8, LC_CTYPE=C.UTF-8 (charmap=UTF-8), LANGUAGE=C.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: sysvinit (via /sbin/init)

Versions of packages libhttp-server-simple-perl depends on:
ii  libcgi-pm-perl  4.35-1
ii  perl            5.24.1-3+deb9u5

libhttp-server-simple-perl recommends no packages.

libhttp-server-simple-perl suggests no packages.

-- no debconf information
-------------- next part --------------
>From 0e3370aae5609c1220d5320d7242443192d0b2da Mon Sep 17 00:00:00 2001
From: Ian Jackson <ijackson at chiark.greenend.org.uk>
Date: Thu, 25 Jul 2019 02:02:22 +0100
Subject: [PATCH] Document the minimal server listening socket filehandle name

Knowing this is useful in post_setup_hook, or maybe if
one wants to override setup_hook without reimplementing run (ie, the
code in _default_run).

For example, if one wants HTTP::Server::Simple to bind to any free
port, one can override port to specify 0, so that the OS chooses a
free port.  But one then needs to get the port number out somehow and
the obvious method is calling getsockname on the filehandle.

So document this.  It seems unlikely that the minimal implementation
will want or need to change this.

Signed-off-by: Ian Jackson <ijackson at chiark.greenend.org.uk>
---
 lib/HTTP/Server/Simple.pm | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/lib/HTTP/Server/Simple.pm b/lib/HTTP/Server/Simple.pm
index 70fc38d..4445b6d 100644
--- a/lib/HTTP/Server/Simple.pm
+++ b/lib/HTTP/Server/Simple.pm
@@ -337,6 +337,9 @@ User-overridable method. If you set it to a L<Net::Server> subclass,
 that subclass is used for the C<run> method.  Otherwise, a minimal
 implementation is used as default.
 
+With the minimal implementation, the master listening socket
+filehandle is C<HTTP::Server::Simple::HTTPDaemon>.
+
 =cut
 
 sub net_server {undef}
-- 
2.11.0