[PATCH 0/2] doc and usability updates

[PATCH 0/2] doc and usability updates

[Eric Wong]

Eric Wong (2):
  documentation updates
  s/X-Mwrap-BT-Depth/X-Mwrap-BT/

 README              | 13 ++++-----
 httpd.h             |  2 +-
 script/mwrap-perl   | 64 ++++++++++++++++++++++++++++++++++++++++-----
 script/mwrap-rproxy |  6 ++---
 t/httpd.t           |  6 ++---
 5 files changed, 71 insertions(+), 20 deletions(-)

[PATCH 1/2] documentation updates

[Eric Wong]

Document the HTTP POST API and update the README with POP3
info and some minor rewording.  We'll also consistently use
`DIR' instead of `DIRECTORY' since it's shorter and well
understood (`opendir', `readdir', etc.)
---
 README              | 13 ++++-----
 script/mwrap-perl   | 64 ++++++++++++++++++++++++++++++++++++++++-----
 script/mwrap-rproxy |  6 ++---
 3 files changed, 67 insertions(+), 16 deletions(-)

diff --git a/README b/README
index f8a1d1b..1fa1dfb 100644
--- a/README
+++ b/README
@@ -66,16 +66,17 @@ malloc locations.
 
 * Perl source files over 16.7 million lines long are not supported :P
 
-== Public mail archives (HTTP, Atom feeds, IMAP mailbox, NNTP group):
+== Public mail archives (HTTP, Atom feeds, IMAP mailbox, NNTP group, POP3):
 
 	https://80x24.org/mwrap-perl/
-	imaps://80x24.org/inbox.comp.lang.perl.mwrap.0
+	imaps://;AUTH=ANONYMOUS@80x24.org/inbox.comp.lang.perl.mwrap.0
 	nntps://80x24.org/inbox.comp.lang.perl.mwrap
+	https://80x24.org/mwrap-perl/_/text/help/#pop3
 
-No subscription nor real identities will ever be required to
-obtain support.  Memory usage reductions start with you; only send
-plain-text mail to us and do not top-post.  HTML mail and top-posting
-costs everybody memory and bandwidth.
+No subscription nor real identities will ever be required to obtain support,
+but HTML mail is rejected.  Memory usage reductions start with you;
+only send plain-text mail to us and do not top-post.  HTML mail and
+top-posting costs everybody memory and bandwidth.
 
 		mwrap-perl@80x24.org
 
diff --git a/script/mwrap-perl b/script/mwrap-perl
index 82629b4..48f5471 100644
--- a/script/mwrap-perl
+++ b/script/mwrap-perl
@@ -28,8 +28,8 @@ mwrap-perl - run any command under mwrap
 
 =head1 SYNOPSIS
 
-  # to trace a long-running program and access it via $DIRECTORY/$PID.sock:
-  MWRAP=socket_dir:$DIRECTORY mwrap-perl COMMAND
+  # to trace a long-running program and access it via $DIR/$PID.sock:
+  MWRAP=socket_dir:$DIR mwrap-perl COMMAND
 
   # to trace a short-lived command and dump its output to a log:
   MWRAP=dump_path:$FILENAME mwrap-perl COMMAND
@@ -46,14 +46,16 @@ of native (C/C++) functions for non-Perl programs.
 C<MWRAP> is the only environment variable read.  It contains multiple
 options delimited by C<,> with names and values delimited by C<:>
 
-=item socket_dir:$DIRECTORY
+=over 4
+
+=item socket_dir:$DIR
 
 This launches an embedded HTTP server in each process and binds it
-to C<$DIRECTORY/$PID.sock>.  C<curl --unix-socket $DIRECTORY/$PID.sock>
+to C<$DIR/$PID.sock>.  C<curl --unix-socket $DIR/$PID.sock http://0/$PID/>
 or L<mwrap-rproxy(1p)> may be used to access various endpoints in
 the HTTP server.
 
-=item: bt:$DEPTH
+=item bt:$DEPTH
 
 The backtrace depth for L<backtrace(3)> in addition to the Perl
 file and line number where C<$DEPTH> is a non-negative number.
@@ -64,15 +66,63 @@ increase the amount of memory mwrap (and liburcu) itself uses.
 
 This is only useful in conjunction with C<socket_dir>
 
+This may be changed via POST request (see below).
+
 Default: 0
 
 =item dump_path:$FILENAME
 
-Dumps the output
+Dumps the output at exit to a given filename:
 
 	total_bytes	call_count	location
 
-In the future, dumping to a self-describing CSV will be supported
+In the future, dumping to a self-describing CSV will be supported.
+
+=item dump_fd:$DESCRIPTOR
+
+As with dump_path, but dumps the output to a given file descriptor.
+
+=back
+
+=head1 HTTP POST API
+
+In addition to the various GET endpoints linked via C<http://0/$PID/>,
+there are some POST endpoints which are typically accessed via
+C<curl --unix-socket $DIR/$PID.sock>
+
+=over 4
+
+=item POST http://0/$PID/reset
+
+C<curl --unix-socket $DIR/$PID.sock -XPOST http://0/$PID/reset>
+
+Reset all internal counters.  This is not done atomically and does
+not release any memory.
+
+=item POST http://0/$PID/trim
+
+C<curl --unix-socket $DIR/$PID.sock -XPOST http://0/$PID/trim>
+
+Runs L<malloc_trim(3)> with a 0 pad value to release unused memory
+back to the kernel.  In our malloc implementation, this is done
+lazily to avoid contention and does not happen unless sleeping threads.
+
+=item POST http://0/$PID/ctl
+
+Set various internal knobs.  Currently, C<X-Mwrap-BT-Depth> is the
+only knob supported:
+
+C<curl --unix-socket $DIR/$PID.sock -XPOST -HX-Mwrap-BT-Depth:1 http://0/$PID/ctl>
+
+Using the C<X-Mwrap-BT-Depth> header allows changing the aforementioned
+C<bt:> value to a specified depth level.  As with C<bt:>, only make small
+adjustments as the memory cost can increase exponentially with each step.
+
+It is typically a good idea to reset (C<http://0/$PID/reset>) after changing
+the depth on a running process.
+
+Headers other than C<X-Mwrap-BT-Depth> may be accepted in the future to
+tweak other settings.
 
 =back
 
diff --git a/script/mwrap-rproxy b/script/mwrap-rproxy
index 2498bc3..056e80a 100644
--- a/script/mwrap-rproxy
+++ b/script/mwrap-rproxy
@@ -48,10 +48,10 @@ mwrap-rproxy - reverse proxy for embedded per-process mwrap httpd
 =head1 SYNOPSIS
 
   # start the long-running COMMAND you wish to trace:
-  MWRAP=socket_dir:$DIRECTORY mwrap-perl COMMAND
+  MWRAP=socket_dir:$DIR mwrap-perl COMMAND
 
   # in a different terminal, point mwrap-proxy to the mwrap-perl socket_dir
-  mwrap-rproxy --socket-dir=$DIRECTORY -l 127.0.0.1:8080
+  mwrap-rproxy --socket-dir=$DIR -l 127.0.0.1:8080
 
   # open http://127.0.0.1:8080/ in your favorite web browser:
   w3m http://127.0.0.1:8080/
@@ -71,7 +71,7 @@ traced by mwrap-perl.
 
 =over 4
 
-=item --socket-dir=DIRECTORY
+=item --socket-dir=DIR
 
 If unset, it will attempt to parse C<socket_dir:> from the C<MWRAP>
 environment (see L<mwrap-perl(1p)>).

[PATCH 2/2] s/X-Mwrap-BT-Depth/X-Mwrap-BT/

[Eric Wong]

This is more consistent with the `MWRAP=bt:' use, since adding
`-Depth' seems unnecessary and makes curl commands too long.
---
 httpd.h           | 2 +-
 script/mwrap-perl | 8 ++++----
 t/httpd.t         | 6 +++---
 3 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/httpd.h b/httpd.h
index 36e487d..89e366e 100644
--- a/httpd.h
+++ b/httpd.h
@@ -892,7 +892,7 @@ static enum mw_qev h1_parse_harder(struct mw_h1 *h1, struct mw_h1req *h1r,
 			 * request bodies, so let pico handle parameters in
 			 * HTTP request headers, instead.
 			 */
-			if (NAME_EQ(hdr, "X-Mwrap-BT-Depth")) {
+			if (NAME_EQ(hdr, "X-Mwrap-BT")) {
 				errno = 0;
 				depth = strtol(hdr->value, &end, 10);
 				if (errno || !valid_end(end))
diff --git a/script/mwrap-perl b/script/mwrap-perl
index 48f5471..182b0bd 100644
--- a/script/mwrap-perl
+++ b/script/mwrap-perl
@@ -109,19 +109,19 @@ lazily to avoid contention and does not happen unless sleeping threads.
 
 =item POST http://0/$PID/ctl
 
-Set various internal knobs.  Currently, C<X-Mwrap-BT-Depth> is the
+Set various internal knobs.  Currently, C<X-Mwrap-BT> is the
 only knob supported:
 
-C<curl --unix-socket $DIR/$PID.sock -XPOST -HX-Mwrap-BT-Depth:1 http://0/$PID/ctl>
+C<curl --unix-socket $DIR/$PID.sock -XPOST -HX-Mwrap-BT:1 http://0/$PID/ctl>
 
-Using the C<X-Mwrap-BT-Depth> header allows changing the aforementioned
+Using the C<X-Mwrap-BT> header allows changing the aforementioned
 C<bt:> value to a specified depth level.  As with C<bt:>, only make small
 adjustments as the memory cost can increase exponentially with each step.
 
 It is typically a good idea to reset (C<http://0/$PID/reset>) after changing
 the depth on a running process.
 
-Headers other than C<X-Mwrap-BT-Depth> may be accepted in the future to
+Headers other than C<X-Mwrap-BT> may be accepted in the future to
 tweak other settings.
 
 =back
diff --git a/t/httpd.t b/t/httpd.t
index 8f56f64..bf9100e 100644
--- a/t/httpd.t
+++ b/t/httpd.t
@@ -161,12 +161,12 @@ SKIP: {
 
 	$rc = system(@curl, qw(-d x=y), "http://0/$pid/reset");
 	is($rc, 0, 'curl /reset');
-	$rc = system(@curl, qw(-HX-Mwrap-BT-Depth:10 -XPOST),
+	$rc = system(@curl, qw(-HX-Mwrap-BT:10 -XPOST),
 			"http://0/$pid/ctl");
-	is($rc, 0, 'curl /ctl (X-Mwrap-BT-Depth)');
+	is($rc, 0, 'curl /ctl (X-Mwrap-BT)');
 	like(slurp($cout), qr/\bMWRAP=bt:10\b/, 'changed bt depth');
 
-	$rc = system(@curl, qw(-HX-Mwrap-BT-Depth:10 -d blah http://0/ctl));
+	$rc = system(@curl, qw(-HX-Mwrap-BT:10 -d blah http://0/ctl));
 	is($rc >> 8, 22, '404 w/o PID prefix');
 };