You can subscribe to this list here.
| 2004 |
Jan
(123) |
Feb
(24) |
Mar
(11) |
Apr
(7) |
May
(6) |
Jun
(6) |
Jul
(1) |
Aug
(1) |
Sep
(35) |
Oct
(24) |
Nov
(3) |
Dec
(5) |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2005 |
Jan
(2) |
Feb
(6) |
Mar
(13) |
Apr
(17) |
May
(3) |
Jun
(11) |
Jul
(12) |
Aug
(4) |
Sep
(4) |
Oct
(4) |
Nov
|
Dec
(28) |
| 2006 |
Jan
(35) |
Feb
(21) |
Mar
(23) |
Apr
|
May
(16) |
Jun
(2) |
Jul
(8) |
Aug
(27) |
Sep
(2) |
Oct
(12) |
Nov
(22) |
Dec
(6) |
| 2007 |
Jan
(7) |
Feb
(4) |
Mar
|
Apr
(5) |
May
|
Jun
(2) |
Jul
|
Aug
|
Sep
(6) |
Oct
|
Nov
|
Dec
(1) |
| 2008 |
Jan
|
Feb
(11) |
Mar
(2) |
Apr
(14) |
May
|
Jun
|
Jul
(2) |
Aug
(11) |
Sep
(2) |
Oct
(5) |
Nov
|
Dec
|
| 2009 |
Jan
(1) |
Feb
(5) |
Mar
(2) |
Apr
|
May
(3) |
Jun
|
Jul
(5) |
Aug
|
Sep
|
Oct
|
Nov
|
Dec
|
| 2010 |
Jan
(2) |
Feb
(32) |
Mar
|
Apr
|
May
|
Jun
|
Jul
|
Aug
|
Sep
(6) |
Oct
(14) |
Nov
(4) |
Dec
(1) |
| 2011 |
Jan
(8) |
Feb
|
Mar
(41) |
Apr
(42) |
May
|
Jun
(1) |
Jul
(4) |
Aug
(1) |
Sep
|
Oct
|
Nov
(1) |
Dec
|
| 2012 |
Jan
|
Feb
(4) |
Mar
(5) |
Apr
(10) |
May
(2) |
Jun
(2) |
Jul
(15) |
Aug
(8) |
Sep
(101) |
Oct
(35) |
Nov
(17) |
Dec
(6) |
| 2013 |
Jan
(19) |
Feb
(18) |
Mar
(18) |
Apr
(67) |
May
(17) |
Jun
(4) |
Jul
(21) |
Aug
(10) |
Sep
(33) |
Oct
(33) |
Nov
(97) |
Dec
(81) |
| 2014 |
Jan
(39) |
Feb
(30) |
Mar
(10) |
Apr
(34) |
May
(7) |
Jun
(27) |
Jul
(33) |
Aug
(24) |
Sep
(9) |
Oct
(52) |
Nov
(23) |
Dec
(24) |
| 2015 |
Jan
(55) |
Feb
(51) |
Mar
(39) |
Apr
(74) |
May
(63) |
Jun
(33) |
Jul
(19) |
Aug
(21) |
Sep
(28) |
Oct
(11) |
Nov
(25) |
Dec
(26) |
| 2016 |
Jan
(39) |
Feb
(19) |
Mar
(36) |
Apr
(8) |
May
(3) |
Jun
(18) |
Jul
(20) |
Aug
(30) |
Sep
(12) |
Oct
(33) |
Nov
(145) |
Dec
(52) |
| 2017 |
Jan
(22) |
Feb
(43) |
Mar
(44) |
Apr
(71) |
May
(14) |
Jun
(10) |
Jul
(7) |
Aug
(30) |
Sep
(10) |
Oct
(39) |
Nov
(7) |
Dec
|
| 2018 |
Jan
(17) |
Feb
(21) |
Mar
(10) |
Apr
(19) |
May
(8) |
Jun
(9) |
Jul
(12) |
Aug
(3) |
Sep
(17) |
Oct
(9) |
Nov
(14) |
Dec
|
| 2019 |
Jan
(10) |
Feb
(6) |
Mar
(17) |
Apr
(2) |
May
(15) |
Jun
(15) |
Jul
(43) |
Aug
(12) |
Sep
(21) |
Oct
(7) |
Nov
(35) |
Dec
(5) |
| 2020 |
Jan
(110) |
Feb
(19) |
Mar
(12) |
Apr
(7) |
May
(22) |
Jun
(20) |
Jul
(48) |
Aug
(112) |
Sep
(12) |
Oct
(5) |
Nov
(19) |
Dec
(4) |
| 2021 |
Jan
(22) |
Feb
(54) |
Mar
(39) |
Apr
(5) |
May
(5) |
Jun
(36) |
Jul
(23) |
Aug
(31) |
Sep
(29) |
Oct
(2) |
Nov
(63) |
Dec
(50) |
| 2022 |
Jan
(23) |
Feb
(15) |
Mar
(3) |
Apr
(15) |
May
(21) |
Jun
(262) |
Jul
(59) |
Aug
(24) |
Sep
(18) |
Oct
(8) |
Nov
(23) |
Dec
(24) |
| 2023 |
Jan
(13) |
Feb
(3) |
Mar
(24) |
Apr
(3) |
May
(6) |
Jun
(13) |
Jul
(9) |
Aug
(32) |
Sep
(4) |
Oct
(2) |
Nov
(11) |
Dec
|
| 2024 |
Jan
(23) |
Feb
(15) |
Mar
(16) |
Apr
(17) |
May
(2) |
Jun
(5) |
Jul
(34) |
Aug
(48) |
Sep
(24) |
Oct
(12) |
Nov
(43) |
Dec
(34) |
| 2025 |
Jan
(7) |
Feb
(1) |
Mar
(30) |
Apr
(4) |
May
|
Jun
(5) |
Jul
(25) |
Aug
(1) |
Sep
(7) |
Oct
(7) |
Nov
(19) |
Dec
(11) |
| 2026 |
Jan
(10) |
Feb
(2) |
Mar
(5) |
Apr
(42) |
May
(28) |
Jun
(21) |
Jul
(25) |
Aug
(9) |
Sep
(1) |
Oct
(7) |
Nov
(1) |
Dec
|
|
From: Oswald B. <osw...@gm...> - 2026-11-01 13:36:11
|
>2026. okt. 31. 7:42:41 Archit P. Shah <ar...@ca...>: >> It is left to the user to repermission files/directories >> appropriately in the even the Maildir needs to have its permissions >> adjusted. > so why not leave it entirely to the user in the first place? running `chmod -R g+rX` prior to running the agent (or after running mbsync) seems perfectly reasonable. mbsync is a batch program anyway. On Sat, Oct 31, 2026 at 08:08:10AM +0100, Bence Ferdinandy wrote: >I'm assuming your agent would run under a different user. In this case, >why not just use bindfs to present a read-only view of your maildir? > that sound quite nice, indeed. |
|
From: Bence F. <be...@fe...> - 2026-10-31 07:43:55
|
2026. okt. 31. 7:42:41 Archit P. Shah <ar...@ca...>: > I wanted to have a group-readable maildir store so that my agentic user > could read but not modify my email. To allow for existing behavior to > continue (user access only), while allowing group readable/writeable > maildir stores, I'm proposing the addition of a GroupAccess option at > the Maildir Store level. If it is enabled, new messages are created > mode 0660 (subject to OS/umask rules) and new directories 0770. The > option should default to false. The proposed patch does not attempt to > address changes to the new GroupAccess configuration. It is left to > the user to repermission files/directories appropriately in the even > the Maildir needs to have its permissions adjusted. I'm assuming your agent would run under a different user. In this case, why not just use bindfs to present a read-only view of your maildir? https://bindfs.org/ Best, Bence > > Coding and testing was driven by the pi coding agent configured with > GLM-5.3. > > Regards, > > -- Archit > > _______________________________________________ > isync-devel mailing list > isy...@li... > https://lists.sourceforge.net/lists/listinfo/isync-devel > > ---------------------------------------- > Maildir-GroupAccess-option.patch > > diff --git a/src/common.h b/src/common.h > index 38521b6..0c3ffa7 100644 > --- a/src/common.h > +++ b/src/common.h > @@ -300,7 +300,7 @@ void ATTR_NORETURN oom( void ); > > int map_name( const char *arg, int argl, char **result, uint reserve, > const char *in, const char *out ); > > -int mkdir_p( char *path, int len ); > +int mkdir_p( char *path, int len, int mode ); > > #define DEFINE_ARRAY_TYPE(T) \ > typedef struct { \ > diff --git a/src/drv_maildir.c b/src/drv_maildir.c > index fe0e951..4bb2d62 100644 > --- a/src/drv_maildir.c > +++ b/src/drv_maildir.c > @@ -42,6 +42,7 @@ typedef union maildir_store_conf { > #endif /* USE_DB */ > char info_delimiter; > char sub_style; > + char group_access; /* create new messages with mode 0660 > (subject to umask) */ > char failed; > char *info_prefix, *info_stop; /* precalculated from > info_delimiter */ > }; > @@ -588,6 +589,7 @@ maildir_validate( const char *box, int create, > maildir_store_t *ctx ) > int i, bl, ret; > struct stat st; > char buf[_POSIX_PATH_MAX]; > + int mode = ctx->conf->group_access ? 0770 : 0700; > > bl = nfsnprintf( buf, sizeof(buf) - 4, "%s/", box ); > if (stat( buf, &st )) { > @@ -597,7 +599,7 @@ maildir_validate( const char *box, int create, > maildir_store_t *ctx ) > } > if (!create) > return DRV_BOX_BAD; > - if (mkdir_p( buf, bl - 1 )) { > + if (mkdir_p( buf, bl - 1, mode )) { > sys_error( "Maildir error: cannot create mailbox '%s'", buf > ); > ctx->conf->failed = FAIL_FINAL; > maildir_invoke_bad_callback( ctx ); > @@ -614,7 +616,7 @@ maildir_validate( const char *box, int create, > maildir_store_t *ctx ) > /* We always create new/ and tmp/ if they are missing. cur/ > is the presence indicator. */ > if (!i && !create) > return DRV_BOX_BAD; > - if (mkdir( buf, 0700 )) { > + if (mkdir( buf, mode )) { > sys_error( "Maildir error: cannot create directory %s", > buf ); > return DRV_BOX_BAD; > } > @@ -1611,7 +1613,8 @@ maildir_store_msg( store_t *gctx, msg_data_t > *data, int to_trash, > > maildir_make_flags( ctx->conf->info_delimiter, data->flags, fbuf ); > nfsnprintf( buf, sizeof(buf), "%s/tmp/%s%s", box, base, fbuf ); > - if ((fd = open( buf, O_WRONLY | O_CREAT | O_EXCL, 0600 )) < 0) { > + int mode = ctx->conf->group_access ? 0660 : 0600; > + if ((fd = open( buf, O_WRONLY | O_CREAT | O_EXCL, mode )) < 0) { > if (errno != ENOENT || !to_trash) { > sys_error( "Maildir error: cannot create %s", buf ); > free( data->data ); > @@ -1623,7 +1626,7 @@ maildir_store_msg( store_t *gctx, msg_data_t > *data, int to_trash, > cb( ret, 0, aux ); > return; > } > - if ((fd = open( buf, O_WRONLY | O_CREAT | O_EXCL, 0600 )) < 0) > { > + if ((fd = open( buf, O_WRONLY | O_CREAT | O_EXCL, mode )) < 0) > { > sys_error( "Maildir error: cannot create %s", buf ); > free( data->data ); > cb( DRV_BOX_BAD, 0, aux ); > @@ -1909,6 +1912,8 @@ maildir_parse_store( conffile_t *cfg, > store_conf_t **storep ) > cfg->err = 1; > continue; > } > + } else if (!strcasecmp( "GroupAccess", cfg->cmd )) { > + store->group_access = parse_bool( cfg ); > } else if (!strcasecmp( "SubFolders", cfg->cmd )) { > if (!strcasecmp( "Verbatim", cfg->val )) { > store->sub_style = SUB_VERBATIM; > diff --git a/src/mbsync.1.in b/src/mbsync.1.in > index 5169b31..eb05fe0 100644 > --- a/src/mbsync.1.in > +++ b/src/mbsync.1.in > @@ -276,6 +276,14 @@ See \fBRECOMMENDATIONS\fR below. > (Default: \fBno\fR) > . > .TP > +\fBGroupAccess\fR \fByes\fR|\fBno\fR > +Whether message files and mailbox directories newly created by > \fBmbsync\fR > +are created with modes 0600 and 0700, or with modes 0660 and 0770, > +respectively, subject to the process umask. > +.br > +(Default: \fBno\fR) > +. > +.TP > \fBInbox\fR \fIpath\fR > The location of the \fBINBOX\fR. This is \fInot\fR relative to > \fBPath\fR, > but it is allowed to place the \fBINBOX\fR inside the \fBPath\fR. > diff --git a/src/sync_state.c b/src/sync_state.c > index d499f85..7480a45 100644 > --- a/src/sync_state.c > +++ b/src/sync_state.c > @@ -60,7 +60,7 @@ prepare_state( sync_vars_t *svars ) > // Note that this may be shorter than the configuration value, > // as that may contain a filename prefix. > *s = 0; > - if (mkdir_p( svars->dname, s - svars->dname )) { > + if (mkdir_p( svars->dname, s - svars->dname, 0700 )) { > sys_error( "Error: cannot create SyncState directory '%s'", > svars->dname ); > return 0; > } > diff --git a/src/util.c b/src/util.c > index 22e639f..700a541 100644 > --- a/src/util.c > +++ b/src/util.c > @@ -797,20 +797,20 @@ map_name( const char *arg, int l, char **result, > uint reserve, const char *in, c > } > > int > -mkdir_p( char *path, int len ) > +mkdir_p( char *path, int len, int mode ) > { > - if (!mkdir( path, 0700 ) || errno == EEXIST) > + if (!mkdir( path, mode ) || errno == EEXIST) > return 0; > char *p = memrchr( path, '/', (size_t)len ); > if (!p) > return -1; // mkdir() already set errno > *p = 0; > - if (mkdir_p( path, (int)(p - path) )) { > + if (mkdir_p( path, (int)(p - path), mode )) { > *p = '/'; > return -1; > } > *p = '/'; > - return mkdir( path, 0700 ); > + return mkdir( path, mode ); > } > > static int |
|
From: Archit P. S. <ar...@ca...> - 2026-10-31 06:41:44
|
I wanted to have a group-readable maildir store so that my agentic user could read but not modify my email. To allow for existing behavior to continue (user access only), while allowing group readable/writeable maildir stores, I'm proposing the addition of a GroupAccess option at the Maildir Store level. If it is enabled, new messages are created mode 0660 (subject to OS/umask rules) and new directories 0770. The option should default to false. The proposed patch does not attempt to address changes to the new GroupAccess configuration. It is left to the user to repermission files/directories appropriately in the even the Maildir needs to have its permissions adjusted. Coding and testing was driven by the pi coding agent configured with GLM-5.3. Regards, -- Archit |
|
From: Oswald B. <osw...@gm...> - 2026-10-07 11:20:38
|
On Mon, Oct 05, 2026 at 03:04:02PM +0300, Eetu Eloranta via isync-devel wrote: >+++ b/src/mbsync.1.in >@@ -89,6 +89,10 @@ pushed and pulled. >+\fB-p\fR[\fBn\fR], \fB--\fR[\fBno-\fR]\fBprogress\fR >+Set progress visibility. By default the progress is only shown when stdout is >+connected to a TTY, and not to a file or a pipe. here is a somewhat adjusted version: +By default, the progress counters are shown when \fBstdout\fR is connected +to a console (and not to a file or a pipe). +These options override this detection, but note that other means to +suppress the counters are still effective. you should give that behavior a thought; i'm undecided whether it's right. the rest of the patch is ok at first sight. |
|
From: Eetu E. <ee...@mu...> - 2026-10-05 12:04:43
|
This allows forcing progress mode regardless of whether fd 1 is a TTY.
Signed-off-by: Eetu Eloranta <ee...@mu...>
---
src/main.c | 22 +++++++++++++++++++++-
src/mbsync.1.in | 4 ++++
2 files changed, 25 insertions(+), 1 deletion(-)
diff --git a/src/main.c b/src/main.c
index 8581b0c..ed1f428 100644
--- a/src/main.c
+++ b/src/main.c
@@ -49,6 +49,8 @@ PACKAGE " " VERSION " - mailbox synchronizer\n"
" -y, --dry-run do not actually modify anything\n"
" -e, --ext-exit return extended exit code\n"
" -V, --verbose display what is happening\n"
+" -p, --progress always show progress\n"
+" -pn, --no-progress never show progress\n"
" -q, --quiet don't display progress counters\n"
" -v, --version display version\n"
" -h, --help display this help message\n"
@@ -169,6 +171,7 @@ main( int argc, char **argv )
core_vars_t mvars[1];
char *config = NULL, *opt, *ochar;
int oind, cops = 0, op, ms_warn = 0, renew_warn = 0, delete_warn = 0;
+ int progress_mode = -1;
tzset();
init_timers();
@@ -215,6 +218,10 @@ main( int argc, char **argv )
} else if (!strcmp( opt, "quiet" )) {
if (Verbosity > VERYQUIET)
Verbosity--;
+ } else if (!strcmp( opt, "progress" )) {
+ progress_mode = 1;
+ } else if (!strcmp( opt, "no-progress" )) {
+ progress_mode = 0;
} else if (!strcmp( opt, "verbose" )) {
Verbosity = VERBOSE;
} else if (starts_with( opt, -1, "debug", 5 )) {
@@ -442,6 +449,17 @@ main( int argc, char **argv )
if (Verbosity > VERYQUIET)
Verbosity--;
break;
+ case 'p':
+ if (*ochar == 'n' ) {
+ progress_mode = 0;
+ ochar++;
+ } else if (!*ochar) {
+ progress_mode = 1;
+ } else {
+ error( "Unknown -p flag '%c'\n", *ochar );
+ return 1;
+ };
+ break;
case 'V':
Verbosity = VERBOSE;
break;
@@ -543,7 +561,9 @@ main( int argc, char **argv )
for (op = 1; op < argc; op++)
printf( " '%s'", argv[op] );
puts( "" );
- } else if (Verbosity >= TERSE && isatty( 1 )) {
+ } else if (Verbosity >= TERSE &&
+ (progress_mode > 0 ||
+ (progress_mode < 0 && isatty( 1 )))) {
DFlags |= PROGRESS;
}
diff --git a/src/mbsync.1.in b/src/mbsync.1.in
index 5169b31..fd57bff 100644
--- a/src/mbsync.1.in
+++ b/src/mbsync.1.in
@@ -89,6 +89,10 @@ pushed and pulled.
An error may be reported at the same time, so the code may be for example
65 if some changes were successfully pulled, while others failed.
.TP
+\fB-p\fR[\fBn\fR], \fB--\fR[\fBno-\fR]\fBprogress\fR
+Set progress visibility. By default the progress is only shown when stdout is
+connected to a TTY, and not to a file or a pipe.
+.TP
\fB-V\fR, \fB--verbose\fR
Enable \fIverbose\fR mode, which displays what is currently happening.
.TP
--
2.55.0
|
|
From: Oswald B. <osw...@gm...> - 2026-10-05 09:54:38
|
On Mon, Oct 05, 2026 at 10:49:50AM +0300, Eetu Eloranta via isync-devel wrote:
>I have written some notmuch hooks for my personal use, and wound up
>wanting to see the pretty progress output from mbsync through a pipe,
>but it turns out that it wasn't possible without resorting to somehow
>tricking isatty(1).
>
yeah, i was wondering when somebody would ask for that ...
On Mon, Oct 05, 2026 at 10:49:51AM +0300, Eetu Eloranta via isync-devel
wrote:
>+++ b/src/common.h
>@@ -143,6 +143,12 @@ enum {
>+enum {
>+ PROGRESS_AUTO,
>+ PROGRESS_ALWAYS,
>+ PROGRESS_NEVER,
>+};
>+
i probably wouldn't bother with declaring an enum for that, because ...
>@@ -175,6 +181,7 @@ DEFINE_BIT_ENUM(options_enum)
>
> // Global options
>+extern int ProgressMode;
>
.. actual use never leaves main(). so make it local, and just use -1,
0, 1 for auto, no, yes, resp.
>+++ b/src/main.c
>@@ -48,6 +48,7 @@ PACKAGE " " VERSION " - mailbox synchronizer\n"
>+" -p, --progress MODE select progress mode (see manual, default: auto)\n"
>
this seems over-engineered, and doesn't fit the existing patterns very
well. i'd go with "-pn, --no-progress" and "-p, --progress". the auto
mode doesn't need an explicit option.
|
|
From: Eetu E. <ee...@mu...> - 2026-10-05 08:26:53
|
This allow forcing the progress mode regardless of whether fd 1 is tty or not.
Signed-off-by: Eetu Eloranta <ee...@mu...>
---
src/common.h | 7 +++++++
src/main.c | 53 ++++++++++++++++++++++++++++++++++++++++++++++++-
src/mbsync.1.in | 6 ++++++
src/util.c | 1 +
4 files changed, 66 insertions(+), 1 deletion(-)
diff --git a/src/common.h b/src/common.h
index 38521b6..28b7833 100644
--- a/src/common.h
+++ b/src/common.h
@@ -143,6 +143,12 @@ enum {
VERBOSE,
};
+enum {
+ PROGRESS_AUTO,
+ PROGRESS_ALWAYS,
+ PROGRESS_NEVER,
+};
+
#define options_enum(fn) \
fn(DEBUG_MAILDIR) \
fn(DEBUG_NET) \
@@ -175,6 +181,7 @@ DEFINE_BIT_ENUM(options_enum)
// Global options
extern int Verbosity;
+extern int ProgressMode;
extern int DFlags;
extern int JLimit, JCount;
extern int UseFSync;
diff --git a/src/main.c b/src/main.c
index 8581b0c..538c03d 100644
--- a/src/main.c
+++ b/src/main.c
@@ -48,6 +48,7 @@ PACKAGE " " VERSION " - mailbox synchronizer\n"
" -D, --debug debugging modes (see manual)\n"
" -y, --dry-run do not actually modify anything\n"
" -e, --ext-exit return extended exit code\n"
+" -p, --progress MODE select progress mode (see manual, default: auto)\n"
" -V, --verbose display what is happening\n"
" -q, --quiet don't display progress counters\n"
" -v, --version display version\n"
@@ -163,6 +164,18 @@ countStep( void )
exit( 100 );
}
+static int
+parse_progress_mode( const char *mode )
+{
+ if (!strcmp( mode, "auto" ))
+ return PROGRESS_AUTO;
+ if (!strcmp( mode, "always" ))
+ return PROGRESS_ALWAYS;
+ if (!strcmp( mode, "never" ))
+ return PROGRESS_NEVER;
+ return -1;
+}
+
int
main( int argc, char **argv )
{
@@ -244,6 +257,27 @@ main( int argc, char **argv )
DFlags |= DRYRUN;
} else if (!strcmp( opt, "ext-exit" )) {
DFlags |= EXT_EXIT;
+ } else if (!strcmp( opt, "progress" )) {
+ int mode;
+
+ if (oind >= argc) {
+ error( "--progress requires an argument.\n" );
+ return 1;
+ }
+ if ((mode = parse_progress_mode( argv[oind++] )) < 0) {
+ error("Invalid progress mode '%s'\n",
+ argv[oind - 1]);
+ return 1;
+ }
+ ProgressMode = mode;
+ } else if (starts_with( opt, -1, "progress=", 9)) {
+ int mode;
+
+ if ((mode = parse_progress_mode( opt + 9 )) < 0) {
+ error( "Invalid progress mode '%s'\n", opt + 9 );
+ return 1;
+ }
+ ProgressMode = mode;
} else if (!strcmp( opt, "pull" )) {
cops |= XOP_PULL, mvars->ops[F] |= XOP_HAVE_TYPE;
} else if (!strcmp( opt, "push" )) {
@@ -445,6 +479,21 @@ main( int argc, char **argv )
case 'V':
Verbosity = VERBOSE;
break;
+ case 'p': {
+ int mode;
+
+ if (oind >= argc) {
+ error( "-p requires an argument.\n" );
+ return 1;
+ }
+
+ if ((mode = parse_progress_mode( argv[oind++] )) < 0) {
+ error( "Invalid progress mode '%s'\n", argv[oind - 1] );
+ return 1;
+ }
+ ProgressMode = mode;
+ break;
+ }
case 'D':
for (op = 0; *ochar; ochar++) {
switch (*ochar) {
@@ -543,7 +592,9 @@ main( int argc, char **argv )
for (op = 1; op < argc; op++)
printf( " '%s'", argv[op] );
puts( "" );
- } else if (Verbosity >= TERSE && isatty( 1 )) {
+ } else if (Verbosity >= TERSE &&
+ (ProgressMode == PROGRESS_ALWAYS ||
+ (ProgressMode == PROGRESS_AUTO && isatty( 1 )))) {
DFlags |= PROGRESS;
}
diff --git a/src/mbsync.1.in b/src/mbsync.1.in
index 5169b31..375b5e2 100644
--- a/src/mbsync.1.in
+++ b/src/mbsync.1.in
@@ -89,6 +89,12 @@ pushed and pulled.
An error may be reported at the same time, so the code may be for example
65 if some changes were successfully pulled, while others failed.
.TP
+\fB-p\fR, \fB--progress\fR \fImode\fR
+Set progress visibility to \fImode\fR. Allowed modes are \fIauto\fR (default),
+\fIalways\fR and \fInever\fR. In \fIauto\fR mode, the progress is only shown
+when stdout is connected to a TTY, and not to a file or a pipe. This can be
+overridden by setting the progress mode to \fInever\fR or \fIalways\fR.
+.TP
\fB-V\fR, \fB--verbose\fR
Enable \fIverbose\fR mode, which displays what is currently happening.
.TP
diff --git a/src/util.c b/src/util.c
index 22e639f..03c00ad 100644
--- a/src/util.c
+++ b/src/util.c
@@ -15,6 +15,7 @@
#include <sys/time.h>
int Verbosity = TERSE;
+int ProgressMode = PROGRESS_AUTO;
int DFlags;
int JLimit, JCount;
int UseFSync = 1;
--
2.55.0
|
|
From: Eetu E. <ee...@mu...> - 2026-10-05 08:26:53
|
Hey, I have written some notmuch hooks for my personal use, and wound up wanting to see the pretty progress output from mbsync through a pipe, but it turns out that it wasn't possible without resorting to somehow tricking isatty(1). I'm not sure if this is a correct way to implement a new flag, as this is the first bit of C code that I have really written. I took a look at GNU coding standards [1] and at least propose that an option be made available to control the progress output even when stdout isn't connected to a TTY. [1]: https://www.gnu.org/prep/standards/standards.html#User-Interfaces Eetu Eloranta (1): add --progress option src/common.h | 7 +++++++ src/main.c | 53 ++++++++++++++++++++++++++++++++++++++++++++++++- src/mbsync.1.in | 6 ++++++ src/util.c | 1 + 4 files changed, 66 insertions(+), 1 deletion(-) -- 2.55.0 |
|
From: ossi <os...@us...> - 2026-09-01 07:48:21
|
commit 42cfa1adbad64b71c846a12d8e26957769c6ced0
Author: Oswald Buddenhagen <os...@us...>
Date: Thu Aug 27 19:37:47 2026 +0200
limit length of credentials supplied to LOGIN
xvprintf_core() uses its internal fixed-size buffer when quoting
strings, so we should limit what we feed it.
this prevents that a build without SASL support oob()s when fed
credentials meant for XOAUTH2.
REFMAIL: P-M...@tu...
src/drv_imap.c | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/src/drv_imap.c b/src/drv_imap.c
index 9b170ab..61a79d5 100644
--- a/src/drv_imap.c
+++ b/src/drv_imap.c
@@ -2682,6 +2682,11 @@ imap_open_store_authenticate2( imap_store_t *ctx )
if (auth_login) {
if (!ensure_user( srvc ) || !ensure_password( srvc ))
goto bail;
+ // Strictly speaking, the limit is util.c:QPRINTF_BUFF / 2
+ if (strlen( srvc->user ) + strlen( srvc->pass ) > 200) {
+ error( "IMAP error: LOGIN credentials are excessively long. Wrong AuthMech selected?\n" );
+ goto bail;
+ }
#ifdef HAVE_LIBSSL
if (!ctx->conn.ssl && !ctx->conn.conf->tunnel)
#endif
|
|
From: <sou...@tu...> - 2026-08-30 23:58:48
|
Patch applied cleanly against 1.5.1 and fixes it. On a node advertising AUTH=PLAIN, mbsync now reports IMAP error: LOGIN credentials are excessively long. Wrong AuthMech selected? and exits normally. No SIGABRT across several runs. You were right that AUTH=PLAIN was a red herring -- it's the LOGIN path and the credential length, not anything SASL-specific. And the new message is accurate for my case: this build has no XOAUTH2 mechanism available, which is the real misconfiguration underneath. Thanks for the quick turnaround. Aug 27, 2026, 17:48 by isy...@li...: > On Tue, Aug 25, 2026 at 07:11:24PM +0200, sou...@tu... wrote: > >> F: 1 OK CAPABILITY completed. >> Logging in... >> Fatal: buffer too small. Please report a bug. >> >> #6 0x0000aaaaaaab2ee8 in imap_exec (ctx=0xaaaaaaaf5af0, cmdp=0xaaaaaacadbb0, done=<optimized out>, >> fmt=<optimized out>) at drv_imap.c:539 >> #7 0x0000aaaaaaaaf0cc in done_imap_cmd (ctx=0xaaaaaaaf5af0, cmd=0xaaaaaacadc80, >> response=<optimized out>) at drv_imap.c:359 >> > the call chain was obviously tail-merged, making this trace kinda useless. > however, the only place where this is actually possible is the LOGIN path, and thus the AUTH=PLAIN thing must be a red herring. > > please try the attached patch. > > _______________________________________________ > isync-devel mailing list > isy...@li... > https://lists.sourceforge.net/lists/listinfo/isync-devel > |
|
From: Oswald B. <osw...@gm...> - 2026-08-27 17:48:42
|
On Tue, Aug 25, 2026 at 07:11:24PM +0200, sou...@tu... wrote: >F: 1 OK CAPABILITY completed. >Logging in... >Fatal: buffer too small. Please report a bug. > >#6 0x0000aaaaaaab2ee8 in imap_exec (ctx=0xaaaaaaaf5af0, >cmdp=0xaaaaaacadbb0, done=<optimized out>, > fmt=<optimized out>) at drv_imap.c:539 >#7 0x0000aaaaaaaaf0cc in done_imap_cmd (ctx=0xaaaaaaaf5af0, cmd=0xaaaaaacadc80, > response=<optimized out>) at drv_imap.c:359 > the call chain was obviously tail-merged, making this trace kinda useless. however, the only place where this is actually possible is the LOGIN path, and thus the AUTH=PLAIN thing must be a red herring. please try the attached patch. |
|
From: <sou...@tu...> - 2026-08-25 17:11:34
|
catgirl@gentoo ~> gdb --args mbsync -V -D uf GNU gdb (Gentoo 17.2 vanilla) 17.2 Copyright (C) 2025 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type "show copying" and "show warranty" for details. This GDB was configured as "aarch64-unknown-linux-gnu". Type "show configuration" for configuration details. For bug reporting instructions, please see: <https://bugs.gentoo.org/>. Find the GDB manual and other documentation resources online at: <http://www.gnu.org/software/gdb/documentation/>. For help, type "help". Type "apropos word" to search for commands related to "word"... Reading symbols from mbsync... Reading symbols from /usr/lib/debug/usr/bin/mbsync.debug... (gdb) run Starting program: /usr/bin/mbsync -V -D uf [Thread debugging using libthread_db enabled] Using host libthread_db library "/usr/lib64/libthread_db.so.1". isync 1.5.1 called with: '-V' '-D' 'uf' Reading configuration file /home/catgirl/.config/isyncrc merge ops (in Channel 'uf'): common: OP_EXPUNGE,OP_CREATE far: XOP_HAVE_EXPUNGE,XOP_HAVE_CREATE near: => far: OP_EXPUNGE,OP_CREATE,XOP_HAVE_EXPUNGE,XOP_HAVE_CREATE => near: OP_EXPUNGE,OP_CREATE merge ops (in global config section): common: OP_EXPUNGE,OP_CREATE far: XOP_HAVE_EXPUNGE,XOP_HAVE_CREATE near: => far: OP_EXPUNGE,OP_CREATE,XOP_HAVE_EXPUNGE,XOP_HAVE_CREATE => near: OP_EXPUNGE,OP_CREATE channel ops (uf): far: near: Channel uf Opening far side store uf-remote... F: [ 1] Enter connect_store Resolving outlook.office365.com... [Detaching after fork from child process 148130] F: [ 1] Leave connect_store Opening near side store uf-local... N: [ 2] Enter connect_store N: [ 2] Callback enter connect_store, sts=0 pattern '*' (effective '*'): Path, no INBOX N: [ 3] Enter list_store, flags=2 N: [ 3] Callback enter list_store, sts=0 N: [ 3] Callback leave list_store N: [ 3] Leave list_store N: [ 2] Callback leave connect_store N: [ 2] Leave connect_store Connecting to outlook.office365.com (52.96.165.178:993)... Connection is now encrypted F: * OK Microsoft Exchange IMAP4 service ready. (redacted) (tcpproxy/15.21.0339.010 BACKENDAUTHENTICATE) [(redacted)] F: >>> 1 CAPABILITY F: * CAPABILITY IMAP4 IMAP4rev1 AUTH=PLAIN AUTH=XOAUTH2 SASL-IR UIDPLUS MOVE ID UNSELECT CHILDREN IDLE NAMESPACE LITERAL+ F: 1 OK CAPABILITY completed. Logging in... [Detaching after vfork from child process 148131] Fatal: buffer too small. Please report a bug. Program received signal SIGABRT, Aborted. 0x0000fffff7858644 in ?? () from /usr/lib64/libc.so.6 (gdb) bt #0 0x0000fffff7858644 in ?? () from /usr/lib64/libc.so.6 #1 0x0000fffff7807018 in raise () from /usr/lib64/libc.so.6 #2 0x0000fffff77f25d0 in abort () from /usr/lib64/libc.so.6 #3 0x0000aaaaaaaa570c in oob () at util.c:612 #4 0x0000aaaaaaaa5eac in xvprintf_core (fmt=<optimized out>, ap=..., cb=cb@entry=0xaaaaaaaa63a0 <xasprintf_cb>, cb_aux=cb_aux@entry=0xffffffffef40) at util.c:232 #5 0x0000aaaaaaaa61a8 in xvasprintf (fmt=<optimized out>, ap=<error reading variable: Cannot access memory at address 0x2429c>) at util.c:347 #6 0x0000aaaaaaab2ee8 in imap_exec (ctx=0xaaaaaaaf5af0, cmdp=0xaaaaaacadbb0, done=<optimized out>, fmt=<optimized out>) at drv_imap.c:539 #7 0x0000aaaaaaaaf0cc in done_imap_cmd (ctx=0xaaaaaaaf5af0, cmd=0xaaaaaacadc80, response=<optimized out>) at drv_imap.c:359 #8 0x0000aaaaaaab46e8 in imap_socket_read (aux=0xaaaaaaaf5af0) at drv_imap.c:1931 #9 0x0000aaaaaaaa72b8 in event_wait () at util.c:1129 #10 main_loop () at util.c:1203 #11 0x0000aaaaaaac46a4 in sync_chans (cvars=cvars@entry=0xfffffffff318, argv=<optimized out>) at main_sync.c:368 #12 0x0000aaaaaaaa4378 in main (argc=4, argv=0xfffffffff5b8) at main.c:582 The abort is in xvprintf_core (util.c:232) reaching oob() at util.c:612, called via xvasprintf from imap_exec (drv_imap.c:539). So it's a limit in the printf implementation rather than a buffer in the auth path, which may be why it wasn't where you looked. Note this is the xasprintf_cb path, so it's presumably not specific to credentials -- any sufficiently long formatted string should hit it. Aug 19, 2026, 06:34 by isy...@li...: > On Wed, Aug 19, 2026 at 01:04:28AM +0200, sourcefrg3--- via isync-devel wrote: > >> mbsync 1.5.1 aborts with SIGABRT while logging in to outlook.office365.com. >> > whoops. > >> Happy to provide a backtrace >> > yeah, that would help. i'm obviously just being blind, but i failed to locate the relevant fixed-size buffer. :-} > > > > _______________________________________________ > isync-devel mailing list > isy...@li... > https://lists.sourceforge.net/lists/listinfo/isync-devel > |
|
From: Oswald B. <osw...@gm...> - 2026-08-19 06:34:38
|
On Wed, Aug 19, 2026 at 01:04:28AM +0200, sourcefrg3--- via isync-devel wrote: >mbsync 1.5.1 aborts with SIGABRT while logging in to >outlook.office365.com. > whoops. > Happy to provide a backtrace > yeah, that would help. i'm obviously just being blind, but i failed to locate the relevant fixed-size buffer. :-} |
|
From: <sou...@tu...> - 2026-08-18 23:22:57
|
Hi, mbsync 1.5.1 aborts with SIGABRT while logging in to outlook.office365.com. This build has no XOAUTH2 support, so when the server offers AUTH=PLAIN, mbsync falls back to it and tries to send a 2542-byte OAuth access token (supplied via PassCmd) as a plaintext password. Base64-encoded that's roughly 3.4 KB in the AUTHENTICATE PLAIN command, and it aborts while building it. Microsoft's frontend nodes don't all advertise the same capabilities, so the outcome varies per connection. Two consecutive runs of the same command, seconds apart: AUTH=PLAIN AUTH=XOAUTH2 -> SIGABRT AUTH=XOAUTH2 LOGINDISABLED -> clean "no acceptable authentication mechanism" Version: isync 1.5.1 (Gentoo, aarch64) Version: isync 1.5.1 (Gentoo, aarch64) Output of `mbsync -a`: C: 1/2 B: 6/6 F: +0/0 *0/0 #0/0 -0/0 N: +0/0 *0/0 #0/0 -0/0Fatal: buffer too small. Please report a bug. Output of `mbsync -V -D uf`: catgirl@gentoo ~> mbsync -V -D uf isync 1.5.1 called with: '-V' '-D' 'uf' Reading configuration file /home/catgirl/.config/isyncrc merge ops (in Channel 'uf'): common: OP_EXPUNGE,OP_CREATE far: XOP_HAVE_EXPUNGE,XOP_HAVE_CREATE near: => far: OP_EXPUNGE,OP_CREATE,XOP_HAVE_EXPUNGE,XOP_HAVE_CREATE => near: OP_EXPUNGE,OP_CREATE merge ops (in global config section): common: OP_EXPUNGE,OP_CREATE far: XOP_HAVE_EXPUNGE,XOP_HAVE_CREATE near: => far: OP_EXPUNGE,OP_CREATE,XOP_HAVE_EXPUNGE,XOP_HAVE_CREATE => near: OP_EXPUNGE,OP_CREATE channel ops (uf): far: near: Channel uf Opening far side store uf-remote... F: [ 1] Enter connect_store Resolving outlook.office365.com... F: [ 1] Leave connect_store Opening near side store uf-local... N: [ 2] Enter connect_store N: [ 2] Callback enter connect_store, sts=0 pattern '*' (effective '*'): Path, no INBOX N: [ 3] Enter list_store, flags=2 N: [ 3] Callback enter list_store, sts=0 N: [ 3] Callback leave list_store N: [ 3] Leave list_store N: [ 2] Callback leave connect_store N: [ 2] Leave connect_store Connecting to outlook.office365.com ([2603:1036:303:7::2]:993)... Connection is now encrypted F: * OK The Microsoft Exchange IMAP4 service is ready. (BACKENDAUTHENTICATE) [(redacted)] F: >>> 1 CAPABILITY F: * CAPABILITY IMAP4 IMAP4rev1 AUTH=PLAIN AUTH=XOAUTH2 SASL-IR UIDPLUS MOVE ID UNSELECT CHILDREN IDLE NAMESPACE LITERAL+ F: 1 OK CAPABILITY completed. Logging in... Fatal: buffer too small. Please report a bug. fish: Job 1, 'mbsync -V -D uf' terminated by signal SIGABRT (Abort) catgirl@gentoo ~ [SIGABRT]> mbsync -V -D uf isync 1.5.1 called with: '-V' '-D' 'uf' Reading configuration file /home/catgirl/.config/isyncrc merge ops (in Channel 'uf'): common: OP_EXPUNGE,OP_CREATE far: XOP_HAVE_EXPUNGE,XOP_HAVE_CREATE near: => far: OP_EXPUNGE,OP_CREATE,XOP_HAVE_EXPUNGE,XOP_HAVE_CREATE => near: OP_EXPUNGE,OP_CREATE merge ops (in global config section): common: OP_EXPUNGE,OP_CREATE far: XOP_HAVE_EXPUNGE,XOP_HAVE_CREATE near: => far: OP_EXPUNGE,OP_CREATE,XOP_HAVE_EXPUNGE,XOP_HAVE_CREATE => near: OP_EXPUNGE,OP_CREATE channel ops (uf): far: near: Channel uf Opening far side store uf-remote... F: [ 1] Enter connect_store Resolving outlook.office365.com... F: [ 1] Leave connect_store Opening near side store uf-local... N: [ 2] Enter connect_store N: [ 2] Callback enter connect_store, sts=0 pattern '*' (effective '*'): Path, no INBOX N: [ 3] Enter list_store, flags=2 N: [ 3] Callback enter list_store, sts=0 N: [ 3] Callback leave list_store N: [ 3] Leave list_store N: [ 2] Callback leave connect_store N: [ 2] Leave connect_store Connecting to outlook.office365.com ([2603:1036:303:380a::2]:993)... Connection is now encrypted F: * OK Microsoft Exchange IMAP4 service ready. (redacted) (tcpproxy/15.21.0315.000 BACKENDAUTHENTICATE) [(redacted)] F: >>> 1 CAPABILITY F: * CAPABILITY IMAP4 IMAP4rev1 AUTH=XOAUTH2 LOGINDISABLED SASL-IR UIDPLUS MOVE ID UNSELECT CHILDREN IDLE NAMESPACE LITERAL+ F: 1 OK CAPABILITY completed. Logging in... IMAP error: server supports no acceptable authentication mechanism F: [ 1] Callback enter connect_store, sts=3 F: Enter free_store F: Leave free_store N: Enter free_store N: Leave free_store F: [ 1] Callback leave connect_store The access token is 2542 bytes; the base64-encoded SASL initial response is roughly 3.4 KB. Microsoft Entra access tokens are much larger than Gmail's and grow with group and role claims, so institutional tenants produce the biggest ones. That may be why this hasn't come up before. Reproduces whenever the server advertises AUTH=PLAIN, which is roughly half of connections. My config is arguably wrong (no working XOAUTH2 mechanism available), but aborting rather than failing gracefully on an oversized credential seems worth fixing. Happy to provide a backtrace or test a patch. Thanks, Vera |
|
From: ossi <os...@us...> - 2026-08-11 09:22:39
|
commit aebbf2ab607b93722a2234f827c7602804c7c72e
Author: Oswald Buddenhagen <os...@us...>
Date: Wed May 20 12:57:46 2026 +0200
mention that --dry-run isn't quite read-only
src/mbsync.1.in | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/src/mbsync.1.in b/src/mbsync.1.in
index 1a15b10..5169b31 100644
--- a/src/mbsync.1.in
+++ b/src/mbsync.1.in
@@ -77,8 +77,9 @@ Display version information.
.TP
\fB-y\fR, \fB--dry-run\fR
Enter simulation mode: the Channel status is queried and all required
-operations are determined, but no modifications are actually made
-to either the mailboxes or the state files.
+operations are determined, but no synchronization is actually performed.
+Note that this does not imply completely read-only operation, as
+mailbox book-keeping is still performed.
.TP
\fB-e\fR, \fB--ext-exit\fR
Return an extended exit code: Add 32 or 64 to the code if any
|
|
From: ossi <os...@us...> - 2026-08-11 09:22:38
|
commit bdd9ff8d931236e1926a58cb44bd2644e4538217
Author: Finn Rayk Gaertner <fin...@pr...>
AuthorDate: Mon Aug 10 21:33:10 2026 +0200
Commit: Oswald Buddenhagen <os...@us...>
CommitDate: Tue Aug 11 11:16:20 2026 +0200
fix build with openssl 4
ASN1_STRING and its derivatives are opaque now. but proper accessors
have been available "forever" (the get0 variants since 1.1), so this is
an easy fix.
src/socket.c | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/src/socket.c b/src/socket.c
index 1ef0e95..69cf9cb 100644
--- a/src/socket.c
+++ b/src/socket.c
@@ -24,6 +24,7 @@
|| (defined(LIBRESSL_VERSION_NUMBER) && LIBRESSL_VERSION_NUMBER < 0x2070100fL)
# define X509_OBJECT_get0_X509(o) ((o)->data.x509)
# define X509_STORE_get0_objects(o) ((o)->objs)
+# define ASN1_STRING_get0_data(s) ((const unsigned char *)ASN1_STRING_data(s))
# endif
#endif
@@ -141,8 +142,8 @@ verify_hostname( X509 *cert, const char *hostname )
for (i = 0; i < num_subj_alt_names; i++) {
GENERAL_NAME *subj_alt_name = sk_GENERAL_NAME_value( subj_alt_names, i );
if (subj_alt_name->type == GEN_DNS &&
- strlen( (const char *)subj_alt_name->d.ia5->data ) == (size_t)subj_alt_name->d.ia5->length &&
- host_matches( hostname, (const char *)(subj_alt_name->d.ia5->data) ))
+ strlen( (const char *)ASN1_STRING_get0_data( subj_alt_name->d.ia5 ) ) == (size_t)ASN1_STRING_length( subj_alt_name->d.ia5 ) &&
+ host_matches( hostname, (const char *)ASN1_STRING_get0_data( subj_alt_name->d.ia5 ) ))
{
found = 1;
break;
|
|
From: Oswald B. <osw...@gm...> - 2026-08-04 19:51:35
|
On Sat, Aug 01, 2026 at 03:59:21PM +1000, Seth McDonald wrote:
>On Sun, 26 Jul 2026 at 18:16:07 +0200, Oswald Buddenhagen wrote:
>> but i wonder whether it actually makes sense to filter mechanisms
>> client-side beyond what the config says. is there a plausible situation
>> where the server would offer a mechanism that the client cannot actually use
>> because of local constraints?
>
>We can actually test this by spinning up netcat to act as an IMAP server
>for isync (as of master-next) to connect to. [...]
>
stop right there. that does *not* qualify as "plausible situation".
i'm interested in real-world scenarios that would be expected to
actually work, rather than bailing out due to a reasonable follow-up
error.
>Suppose the intersection of the user configured mechs and the server
>mechs is { LOGIN, PLAIN, SCRAM-SHA-256 }. In this case, isync will
>attempt to use SCRAM-SHA-256. But suppose it fails to initiate the
>authentication session due to a library error.
>
>Speaking as a user, if I saw that the program failed to authenticate
>with SCRAM-SHA-256, I would expect it to retry with one of the other
>availble mechs (LOGIN and PLAIN). The ideal behaviour would be to retry
>with each mech in order of descending security.
>
just no.
the most likely failure is a bad password. we wouldn't want to trigger
rate-limiting by hammering the server with repeated attempts.
if it's a different failure, then the user should want to investigate
it, rather than having isync silently paper over it. it's not like this
is going to happen particularly often to one user ...
>I think I've found a serious bug in the authentication logic.
>
>isync should only ever send plaintext credentials over an insecure
>channel when the user explicitly allows it. It does this for LOGIN by
>only commencing authentication over an insecure connection if the config
>explicitly includes LOGIN in AuthMechs.
>
>PLAIN also sends plaintext credentials for authentication. But isync
>does not perform the same secure channel check for PLAIN that it does
>for LOGIN. This means it will use PLAIN over an insecure connection
>without any pushback, verification, or warning to the user.
>
this is correct.
>In fact, would this be considered a security vulnerability? Since it
>may be possible the user thinks the connection should be secure when it
>is not.
>
debatable.
as i understand it, isync's refusal to automatically use LOGIN should be
understood as a legacy mechanism for really old servers that fail to use
LOGINDISABLED.
with SASL, the server is supposed to prevent it.
there is a hypothetical possibility that a mitm attack would force PLAIN
to steal the password, but if you can't trust the connection to the
server, then why did you disable tls?
one could also imagine the server itself being compromised, but in this
case it doesn't matter whether the connection is secure.
another aspect is that isync used to be opportunistic about using ssl by
default, while it's always enforced now. that reduces the value of the
filter.
>> it's not useful to handle errors that cannot happen if the library is
>> reasonably implemented.
>
>The behaviour of potentially returning NULL is explicitly documented, so
>it's well within reason for that to occur.
>
it will occur when an invalid error code is passed. in this case a crash
is a good indicator of the problem, akin to a failed assertion.
there is no _reasonable_ situation in which that function would fail
otherwise, and there won't be.
even if that turned out to be wrong for some bizarre reason, it wouldn't
have security or significant reliability implications, so what?
>> > I was referring to my use of temporary variables across the
>> > patchset and
>> > in general.
>> >
>> i wasn't. i don't like _these_ temporaries.
>
>So are you okay with my other uses of temporaries then?
>
i didn't notice any others that bothered me, but i will tell you when i
do a more in-depth review of a more final version.
i'm not going to have a fundamental debate about that now.
>> > > > (1) They make git diff/blame cleaner by separating operations with
>> > > > newlines, which allows diff/blame to better identify and show
>> > > > the exact operations that were changed.
>> > > that's equally achievable by wrapping the "resolver" call to the
>> > > next line.
>> >
>> > You say later on that such wrapping of arguments deviates from the style
>> > of the codebase and shouldn't be used without sound justification.
>> > [...]
>> >
>> so stick to the wrapping style that is actually used all over the place?
>
>Are you saying I can or cannot wrap here? I don't understand.
>
dude! there are dozens of wrapped function calls in isync. just look at
how it's done. it's really a rather trivial matter of style ...
>> > > you don't seem to have switched your git diff algorithm
>> > > to histogram yet?
>> >
>> > No, I use minimal by default.
>> >
>> any particular reason? saving bytes/lines isn't a very useful objective when
>> reviewing diffs.
>
>I don't have any strong opinions on the matter. I just use minimal
>because I haven't seen many examples of the other algorithms being
>meaningfully better. Though if you'd like to provide some, I'd be happy
>to take a look.
>
i think that just going by "what it says on the label" is quite
reasonable in this case, unless profound evidence to the contrary is
presented.
>> > > > > > +typedef const char *(*imap_auth_cred_t)( void * );
>> > > > > > +
>> > > > > the consequences of having these are obviously ugly.
>> > > > > just factor out imap_auth_conf_t as i hinted at previously.
>> > > > Sure, but just FYI without it the logic will no longer be
>> > > > self-contained. It'll depend on the implementation of the IMAP driver,
>> > > > why would it?
>> >
>> > It'll directly refer to and hence depend on imap_server_conf_t
>> >
>> no, it wouldn't, just like imap_auth_client_t doesn't.
>
>Then how would it call ensure_user() or ensure_password()? Both
>functions require the imap_server_conf_t instance.
>
so make them require an imap_auth_conf_t instance instead?
as you may have noticed, i'm getting annoyed at this point.
if you currently don't have the capacity to properly process what i
write (including the very deliberately chosen several levels of quotes),
then just do it later. i'm really in no hurry.
good luck with your studies!
|
|
From: Seth M. <de...@se...> - 2026-08-01 05:59:36
|
Apologies for the delayed response. I'm back to studying so I may take
longer to respond.
On Sun, 26 Jul 2026 at 18:16:07 +0200, Oswald Buddenhagen wrote:
> On Sat, Jul 25, 2026 at 05:44:14PM +1000, Seth McDonald wrote:
> > GNU SASL does not choose mechanisms the same way Cyrus SASL does. [...]
> >
> ok, fair enough. apparently the api is less helpful than it seems at first
> sight.
>
> but i wonder whether it actually makes sense to filter mechanisms
> client-side beyond what the config says. is there a plausible situation
> where the server would offer a mechanism that the client cannot actually use
> because of local constraints?
We can actually test this by spinning up netcat to act as an IMAP server
for isync (as of master-next) to connect to. Consider the following
exchange (C for client/isync; S for server/netcat).
S: * OK IMAP4 hello
C: 1 CAPABILITY
S: * CAPABILITY IMAP4rev1 AUTH=GSSAPI
S: 1 OK completed
This causes isync to give an error message listing all the SASL
mechanisms it can use, accounting for the information available (since
such information was provided to Cyrus SASL to generate this list). And
when linked with Cryus SASL 2.1.28 packaged for Debian 13, I get the
following list (see [0] for the config file).
SCRAM-SHA-512
SCRAM-SHA-384
SCRAM-SHA-256
SCRAM-SHA-224
SCRAM-SHA-1
DIGEST-MD5
EXTERNAL
CRAM-MD5
NTLM
LOGIN
PLAIN
XOAUTH2
ANONYMOUS
Any mechanisms not in this list we cannot use even if we wanted to,
since we don't provide the necessary information. This includes GSSAPI,
SCRAM-SHA-256-PLUS, and SCRAM-SHA-1-PLUS, among others.
> > And to reiterate, as a user, I don't want a program bothering me about
> > something it can fix itself. If SASL fails, it should attempt to fix
> > itself by falling back to LOGIN before making it the user's problem.
> >
> huh? are you suggesting that isync should ignore what the user explicitly
> configured (noting that LOGIN is in the defaults if the connection is
> encrypted)?
> if not, what _exactly_ is the situation you want changed?
Suppose the intersection of the user configured mechs and the server
mechs is { LOGIN, PLAIN, SCRAM-SHA-256 }. In this case, isync will
attempt to use SCRAM-SHA-256. But suppose it fails to initiate the
authentication session due to a library error.
Speaking as a user, if I saw that the program failed to authenticate
with SCRAM-SHA-256, I would expect it to retry with one of the other
availble mechs (LOGIN and PLAIN). The ideal behaviour would be to retry
with each mech in order of descending security.
Now speaking as a developer, since PLAIN also relies on the same SASL
library, it would likely also fail due to the library error. So it's
fair to not waste effort attempting PLAIN. But LOGIN is implemented
separate to the library, meaning it can still potentially succeed. So
we can match the expected behaviour by attempting to fall back to LOGIN.
But as of current, if the library error is anything other than
SASL_NOMECH, then isync will immediately bail on authentication rather
than attempting the fallback. This is the behaviour I take issue with.
> > that will only ever trigger for a non-compliant IMAP4 server (since
> > PLAIN is required),
> >
> well, no. the example in
> https://datatracker.ietf.org/doc/html/rfc3501#section-6.1.1 shows this to be
> false. however, it also shows that absence of AUTH=PLAIN goes with presence
> of LOGINDISABLED.
Thanks for the correction. I did some experimenting with IMAP servers
and found that LOGINDISABLED is only used when the connection is not
over TLS. So my point holds for encrypted connections (which I believe
are the majority).
> in principle one could just do away with LOGIN, but PLAIN is a poor
> substitute in a non-sasl build due to the complexity.
Actually, after thinking about this, I think I've found a serious bug in
the authentication logic.
isync should only ever send plaintext credentials over an insecure
channel when the user explicitly allows it. It does this for LOGIN by
only commencing authentication over an insecure connection if the config
explicitly includes LOGIN in AuthMechs.
PLAIN also sends plaintext credentials for authentication. But isync
does not perform the same secure channel check for PLAIN that it does
for LOGIN. This means it will use PLAIN over an insecure connection
without any pushback, verification, or warning to the user.
In fact, would this be considered a security vulnerability? Since it
may be possible the user thinks the connection should be secure when it
is not. (I'm not a security expert, so forgive me if this is wrong.)
> > > and error while retrieving an error string would be an internal
> > > error in libsasl or the calling code.
> >
> > The fallback is intended mainly for the latter case. Such an error in
> > the library is (from the perspective of the calling program) always a
> > possibility, so the fallback accounts for this.
> >
> > > in either case i want that to be glaringly obvious, not papered over.
> >
> > Without the fallback, if such an internal error occurs leading to a NULL
> > return value, the program will just segfault when it attempts to read
> > from the NULL pointer.
>
> > Is that what's preferred?
> >
> yes.
> it's not useful to handle errors that cannot happen if the library is
> reasonably implemented.
The behaviour of potentially returning NULL is explicitly documented, so
it's well within reason for that to occur.
> we don't need to treat it as a black box that could
> do anything.
This would be the case if we controlled the library implementation and
linked-to version. But we don't.
The library will continue to be maintained and new versions will be
released. Versions of isync released in the past or today could be
later built with these future libraries. Since we cannot see the
future, these future libraries are literally black boxes. We cannot
know their exact implementation until they release.
We should want the isync at present to play well with the libraries
released in future. If the library later changes in a way that still
adheres to its documentation and isync is not prepared to handle that,
then that's fully on isync, not the library. And we shouldn't allow UX
to worsen if this happens (crashing is the most user unfriendly way of
informing the user of an error).
> > I was referring to my use of temporary variables across the patchset and
> > in general.
> >
> i wasn't. i don't like _these_ temporaries.
So are you okay with my other uses of temporaries then?
> > > > (1) They make git diff/blame cleaner by separating operations with
> > > > newlines, which allows diff/blame to better identify and show
> > > > the exact operations that were changed.
> > > > that's equally achievable by wrapping the "resolver" call to the
> > > next line.
> >
> > You say later on that such wrapping of arguments deviates from the style
> > of the codebase and shouldn't be used without sound justification.
> > [...]
> >
> so stick to the wrapping style that is actually used all over the place?
Are you saying I can or cannot wrap here? I don't understand.
> > > you don't seem to have switched your git diff algorithm
> > > to histogram yet?
> >
> > No, I use minimal by default.
> >
> any particular reason? saving bytes/lines isn't a very useful objective when
> reviewing diffs.
I don't have any strong opinions on the matter. I just use minimal
because I haven't seen many examples of the other algorithms being
meaningfully better. Though if you'd like to provide some, I'd be happy
to take a look.
> > > > > > +typedef const char *(*imap_auth_cred_t)( void * );
> > > > > > +
> > > > > the consequences of having these are obviously ugly.
> > > > > just factor out imap_auth_conf_t as i hinted at previously.
> > > > > Sure, but just FYI without it the logic will no longer be
> > > > self-contained. It'll depend on the implementation of the IMAP driver,
> > > > why would it?
> >
> > It'll directly refer to and hence depend on imap_server_conf_t
> >
> no, it wouldn't, just like imap_auth_client_t doesn't.
Then how would it call ensure_user() or ensure_password()? Both
functions require the imap_server_conf_t instance.
The reason imap_auth_client_t doesn't is precisely because of the use of
imap_auth_cred_t to remove the direct hardcoded dependency on
imap_server_conf_t, and instead allow the calling code (the IMAP driver)
to clearly configure that dependency.
> > and ensure_(user|password)().
> >
> yes, which should be in imap_auth.c.
Do you not think that would be too tangled? Unless you want to move the
cached username and password from imap_server_conf_t to
imap_auth_client_t, which I could certainly try.
> > > > > > +char *
> > > > > > +find_string_list( const string_list_t *list, const char *str )
> > > > > > +
> > > > > > +char *
> > > > > > +find_string_list_case( const string_list_t *list, const char *str )
> > > > > don't try to make analogous interfaces when there is a cost, but
> > > no obvious
> > > advantage for existing use cases.
> >
> > What's the cost?
> >
> the ugly return casts, if nothing else.
>
> > On the other hand, an advantage is a familiar interface.
> >
> finding an entire string in a string list isn't logically the same as
> finding a substring in one string. it's entirely counter-productive to
> pretend that the apis are the same. it's more like QList::contains().
Using a familar interface is not at all saying it is logically the same
as another function. memcpy() and memove() have identical interfaces,
but they serve different purposes.
I like the comparison to QList::contains() though. I don't think it'll
be comparatively as useful a function, but I can certainly use that kind
of interface in the next revision.
Take care,
Seth McDonald.
[0]
IMAPAccount account
Host localhost
Port 12345
Timeout 0
User he...@wo...
Pass LEAKED
TLSType None
IMAPStore remote
Account account
MaildirStore local
SubFolders Verbatim
Path ~/Code/isync/maildir/
Inbox ~/Code/isync/maildir/local-inbox
Channel chan
Far :remote:
Near :local:
CopyArrivalDate yes
SyncState *
--
E9D1 26A5 F0D4 9DF7 792B C2E2 B4BF 4530 D39B 2D51
|
|
From: Oswald B. <osw...@gm...> - 2026-07-31 07:08:32
|
On Wed, Jul 29, 2026 at 10:53:55PM +0300, Ali Hussein wrote: >Would it be useful if I attached the .mbsyncstate.journal file >privately for analysis? > unlikely. but what exactly is the purpose of your mail? do you want to fix your sync state? are you reporting a bug? |
|
From: Ali H. <mr....@gm...> - 2026-07-29 19:54:15
|
Hi I searched the mailing list archives before posting. I found previous reports involving 33-byte journal files filled with NUL bytes, where deleting the journal allowed recovery because .mbsyncstate still existed. My case appears different because: - .mbsyncstate is completely missing - .mbsyncstate.new is empty (0 bytes) - .mbsyncstate.journal is approximately 2.2 MB and contains valid ASCII records - inspecting the file around the reported offset (128959) does not show NUL bytes or an obvious truncation. Would it be useful if I attached the .mbsyncstate.journal file privately for analysis? *Best Regards* *Ali H. Hababi* +967 771228212 E: Mr....@ga... Shoub Zone, Mazra'a, Sana'a, Yemen. |
|
From: Oswald B. <osw...@gm...> - 2026-07-26 16:16:19
|
On Sat, Jul 25, 2026 at 05:44:14PM +1000, Seth McDonald wrote: >GNU SASL does not choose mechanisms the same way Cyrus SASL does. >[...] > ok, fair enough. apparently the api is less helpful than it seems at first sight. but i wonder whether it actually makes sense to filter mechanisms client-side beyond what the config says. is there a plausible situation where the server would offer a mechanism that the client cannot actually use because of local constraints? >And to reiterate, as a user, I don't want a program bothering me about >something it can fix itself. If SASL fails, it should attempt to fix >itself by falling back to LOGIN before making it the user's problem. > huh? are you suggesting that isync should ignore what the user explicitly configured (noting that LOGIN is in the defaults if the connection is encrypted)? if not, what _exactly_ is the situation you want changed? > that will only ever trigger for a non-compliant IMAP4 server (since > PLAIN is required), > well, no. the example in https://datatracker.ietf.org/doc/html/rfc3501#section-6.1.1 shows this to be false. however, it also shows that absence of AUTH=PLAIN goes with presence of LOGINDISABLED. in principle one could just do away with LOGIN, but PLAIN is a poor substitute in a non-sasl build due to the complexity. >> and error while retrieving an error string would be an internal error >> in libsasl or the calling code. > >The fallback is intended mainly for the latter case. Such an error in >the library is (from the perspective of the calling program) always a >possibility, so the fallback accounts for this. > >> in either case i want that to be glaringly obvious, not papered over. > >Without the fallback, if such an internal error occurs leading to a NULL >return value, the program will just segfault when it attempts to read >from the NULL pointer. >Is that what's preferred? > yes. it's not useful to handle errors that cannot happen if the library is reasonably implemented. we don't need to treat it as a black box that could do anything. if it actually does, then someone has some debugging to do. >I was referring to my use of temporary variables across the patchset >and in general. > i wasn't. i don't like _these_ temporaries. >But also, are you implying the "print stringified error code" pattern >cannot contain bugs? Because if not, then how is this irrelevant? > "cannot" is a tad strong, but it's unlikely enough to happen and easy enough to discover, that one can ignore the possibility. >> > (1) They make git diff/blame cleaner by separating operations with >> > newlines, which allows diff/blame to better identify and show >> > the exact operations that were changed. >> > >> that's equally achievable by wrapping the "resolver" call to the next line. > >You say later on that such wrapping of arguments deviates from the style >of the codebase and shouldn't be used without sound justification. >[...] > so stick to the wrapping style that is actually used all over the place? >> you don't seem to have switched your git diff algorithm >> to histogram yet? > >No, I use minimal by default. > any particular reason? saving bytes/lines isn't a very useful objective when reviewing diffs. >> > > > +typedef const char *(*imap_auth_cred_t)( void * ); >> > > > + >> > > the consequences of having these are obviously ugly. >> > > just factor out imap_auth_conf_t as i hinted at previously. >> > >> > Sure, but just FYI without it the logic will no longer be >> > self-contained. It'll depend on the implementation of the IMAP driver, >> > >> why would it? > >It'll directly refer to and hence depend on imap_server_conf_t > no, it wouldn't, just like imap_auth_client_t doesn't. >and ensure_(user|password)(). > yes, which should be in imap_auth.c. that should also clarify how that relates to the other series. >> > > > +char * >> > > > +find_string_list( const string_list_t *list, const char *str ) >> > > > + >> > > > +char * >> > > > +find_string_list_case( const string_list_t *list, const char *str ) >> > > >> don't try to make analogous interfaces when there is a cost, but no >> obvious >> advantage for existing use cases. > >What's the cost? > the ugly return casts, if nothing else. >On the other hand, an advantage is a familiar interface. > finding an entire string in a string list isn't logically the same as finding a substring in one string. it's entirely counter-productive to pretend that the apis are the same. it's more like QList::contains(). |
|
From: Seth M. <de...@se...> - 2026-07-25 07:44:29
|
On Fri, 24 Jul 2026 at 15:36:26 +0200, Oswald Buddenhagen wrote: > On Fri, Jul 24, 2026 at 02:37:41PM +1000, Seth McDonald wrote: > > On Wed, 22 Jul 2026 at 14:57:28 +0200, Oswald Buddenhagen wrote: > > > On Sat, Jul 18, 2026 at 03:29:40PM +1000, Seth McDonald via isync-devel wrote: > > > > The interface's implementation adds minor changes in behaviour to > > > > simplify the authentication logic. This includes always attempting to > > > > fall back to LOGIN when SASL fails and unifying similar error messages. > > > > semantically, that seems just wrong. you need to work a lot harder > > > to > > > convince me that this is a wanted change. > > > > The primary motivation is that the current "flow" of the SASL logic is > > incompatible with the GNU SASL library. > > > upon a cursory look at the gsasl documentation, i don't see how that would > be fundamentally true. I think I touch on this throughout this message. > in fact, i have the impression that you didn't study it particularly > thoroughly, <https://lists.gnu.org/archive/html/help-gsasl/2026-07/threads.html> As I said previously, I do the work and take the time to understand my tools. > given that you thought it necessary to hard-code the list of > available mechanisms. GNU SASL does not choose mechanisms the same way Cyrus SASL does. Both libraries (Cyrus and GNU) have a large set of SASL mechanisms they support. Of these, there is the common subset of mechanisms that mbsync is currently able to use, which is effectively the same for both. (This subset is different to the set of user configuered mechs.) Cyrus first establishes a client context via sasl_client_new(), which involves providing information about the connection. There's also sasl_setprop() to give additional info. Then the later call to sasl_client_start() chooses a mechanism that requires no more than the provided information to be successful. So in effect, it determines the subset of usable mechanisms, then selects from that subset. GNU assumes you have already selected a mechanism by the time you start the authentication with gsasl_client_start(). That is, it gives the caller the responsibility to choose an appropriate mechanism. Which in our case, includes first determining the subset of usable mechanisms. Luckily, GNU SASL's documentation specifies exactly what is needed for each mechanism, so we can know this subset ahead of time. Hence the hardcoded whitelist of mechanisms. And to preempt some responses: "But gsasl_client_mechlist() gives the subset of usable mechanisms." No it doesn't. It gives the set of mechanisms supported by the client side of the library. It does not consider whether we can actually use the mechanisms when accounting for the information we have available. "But gsasl_client_suggest_mechanism() does this for you." No it doesn't. It selects the most secure mechanism of a list that is supported by the library (assuming the list is ordered by ascending security). It does not consider whether we can actually use the mechanism when accounting for the information we have available. "Why not filter the list given by gsasl_client_mechlist() then?" That would involve identifying usable mechanisms by name and removing the others. Since the same information* is provided for each authentication process, these usable mechanisms to identify will be the same for each such process. So by itself, the effect will just be a whitelist but with more steps. That said, upon reflection I do think this could be done in addition to the hardcoded whitelist. Since the program may use an older library version, some of the more recent mechanisms may not be supported. So we can either raise the required version with gsasl_check_version() or intersect the whitelist with the result of gsasl_client_mechlist(). I lean towards the latter. *The same types of information. For example, each authentication process may use different values for the username and password, but they all may use a username and password if necessary. > a different angle is that it isn't necessary to utilize the library's full > potential. it's just fine to duplicate a bit of the library's functionality > if it makes the implementations more uniform. e.g., i don't see any > practical benefit in actually using gsasl's LOGIN support. Sure, which is why I didn't use GNU SASL's LOGIN support in the patch. > > Regarding the falling back to LOGIN, it simplifies the logic from > > unnecessarily complex "if it fails in this specific way, goto here; but > > if it fails like this, goto there" to "if it fails, try LOGIN instead". > > > that description of the status quo doesn't fill me with confidence that you > actually understand it. It currently works by attempting to fallback to LOGIN if at some point during initialisation of the SASL client, the library indicates that no mechanism is usable via SASL_NOMECH. Otherwise if any other error occurs, the process gives a message or two and bails out of any authentication, not just SASL. This logic is tied to Cyrus SASL specifically. Because GNU SASL doesn't choose the SASL mechanism for you, there is no GSASL_NOMECH error. We could treat an empty intersection between the whitelist and the given mech list as such an error, but that will only ever trigger for a non-compliant IMAP4 server (since PLAIN is required), meaning the fallback will almost never actually occur. And to reiterate, as a user, I don't want a program bothering me about something it can fix itself. If SASL fails, it should attempt to fix itself by falling back to LOGIN before making it the user's problem. > > > > +static const char * > > > > +query_sasl_error( sasl_conn_t *ctx, int rc ) > > > > i don't want that obfuscation layer without good reason. > > > > I added it for two reasons: > > (0) It's simpler to have a single function to call to retrieve the > > appropriate error message, rather than manually switching > > between sasl_errdetail() and sasl_errstring() all the time. > > > it's two functions for a good reason, and i think that blurring the two > contexts is actively counter-productive. I don't entirely agree about it blurring the contexts, but I'll drop this reason to focus on the more important second. > > (1) To encompass the following fallback. > > > > > > + const char *err = ctx > > > > + ? sasl_errdetail( ctx ) > > > > + : sasl_errstring( rc, NULL, NULL ); > > > > > > > + return err ? err : "Unknown error"; > > > > what is that fallback for? > > > > From the documentation for sasl_errdetail() (see [0]): > > > > | Returns the string describing the error that occurred, or NULL if no > > | error has occurred, or there was an error retrieving it. > > > calling the function when no error occurred would be an internal error in > isync. > and error while retrieving an error string would be an internal error in > libsasl or the calling code. The fallback is intended mainly for the latter case. Such an error in the library is (from the perspective of the calling program) always a possibility, so the fallback accounts for this. > in either case i want that to be glaringly obvious, not papered over. Without the fallback, if such an internal error occurs leading to a NULL return value, the program will just segfault when it attempts to read from the NULL pointer. Is that what's preferred? If not, then a NULL return value should be handled, which makes a function encompassing that handling useful. > > > > +static int > > > > +process_sasl_step( > > > > + } else { > > > > + const char *err = query_sasl_error( session, rc ); > > > > i don't like these pointless temporaries. > > > > I tend to use them for a few reasons: > > (0) They make debugging line-by-line with GDB easier by keeping calls on > > their own lines, which allows for easy stepping into/over select > > calls. This is especially true for function calls inside the > > conditions of if-statements. > > > this is true, but completely irrelevant for the "print stringified error > code" pattern. I was referring to my use of temporary variables across the patchset and in general. But also, are you implying the "print stringified error code" pattern cannot contain bugs? Because if not, then how is this irrelevant? > > (1) They make git diff/blame cleaner by separating operations with > > newlines, which allows diff/blame to better identify and show > > the exact operations that were changed. > > > that's equally achievable by wrapping the "resolver" call to the next line. You say later on that such wrapping of arguments deviates from the style of the codebase and shouldn't be used without sound justification. If this is sound justification, then you agree I can wrap arguments like I did in the patch. If this is not sound justification, then temporary variables are still the way to go to achieve better diffs/blames. > > (2) They tell you what exactly you're retrieving from the function, > > which may not always be so obvious. For example, if a call > > returns a status, does zero indicate success or failure? A line > > like `if (!foo())` doesn't tell you much, but a line like > > `int bad = !foo();` tells you immediately it means failure. > > > also completely irrelevant in this context. Again, I was referring to temporary variables in general. And in particular here, my use of them in the patchset for return values that are immediately checked in an if condition. > but i forgot to mention something before: judging by the sub-optimality of > some of the hunks, you don't seem to have switched your git diff algorithm > to histogram yet? No, I use minimal by default. But I'm happy to switch to histogram for this project. > > > > +typedef const char *(*imap_auth_cred_t)( void * ); > > > > + > > > the consequences of having these are obviously ugly. > > > just factor out imap_auth_conf_t as i hinted at previously. > > > > Sure, but just FYI without it the logic will no longer be > > self-contained. It'll depend on the implementation of the IMAP driver, > > > why would it? It'll directly refer to and hence depend on imap_server_conf_t and ensure_(user|password)(). > > > > +/* > > > > + * Formats a list of SASL mechanisms supported by both client and server side. > > > > + * The list is space-delimited, including starting and ending with whitespace. > > > > + * Mechanisms are parsed in a case-insensitive manner. > > > > + */ > > > > +void imap_auth_filter_mechs( > > > > this seems like an implementation detail that should not leak > > > through the > > > abstraction. > > > > Not sure I entirely agree. > > The case-insensitive detail [...] > > The space-delimited detail [...] > > > you didn't pay attention to the reply placement ... > i question the function being part of the iface in the first place. Ah, my bad. The function was exposed mainly to separate the mechanism filtering from the rest of the authentication logic. It's not super important and can be folded into the implementation if desired. > > > > +char * > > > > +find_string_list( const string_list_t *list, const char *str ) > > > > + > > > > +char * > > > > +find_string_list_case( const string_list_t *list, const char *str ) > > > > > > the return values make no sense. these should be bools, and the functions > > > called contains_.... > > > > I was aiming for a function analogous to strstr(). It's purpose is to > > find and, if found, return a string within a string list. And like > > strstr(), it can be used secondarily to only check if the string list > > contains the string by checking if the return value is NULL. > > > don't try to make analogous interfaces when there is a cost, but no obvious > advantage for existing use cases. What's the cost? There's no non-negligible runtime penalty to returning a pointer instead of an integer. It may cost a nanosecond or two if the architecture stores pointers as larger than integers, but that's less meaningful than even a typical micro-optimisation. On the other hand, an advantage is a familiar interface. The closer we stick to standard and familiar conventions and interfaces, the easier it is for others to use them. > > > your prior macos keychain patches should be integrated into this > > > series to > > > reduce overall churn. for that purpose, it's ok to either > > > - during refactoring, leave code in its old place when it will be replaced > > > in subsequent patches, or > > > - to add code in a new file that will be logically created only in the > > > subsequent refactoring (i think this is the case applicable here). > > > > I'm afraid I don't see how integrating the keychain patches into this > > patchset will reduce churn. The imap_auth_* interface doesn't touch nor > > take responsibility for either the keychain code or the > > password-querying logic as a whole. It calls (directly or indirectly) > > ensure_password(), but doesn't care how that function works. > > > that argument is just wrong in light of the imap_auth_conf_t discussion > above. That wasn't an argument; I genuinely don't see how it reduces churn. Take care, Seth McDonald. (Not me spending four hours writing an email lol.) -- E9D1 26A5 F0D4 9DF7 792B C2E2 B4BF 4530 D39B 2D51 |
|
From: Oswald B. <osw...@gm...> - 2026-07-24 15:24:53
|
On Fri, Jul 24, 2026 at 02:37:41PM +1000, Seth McDonald wrote:
>On Wed, 22 Jul 2026 at 14:57:28 +0200, Oswald Buddenhagen wrote:
>> On Sat, Jul 18, 2026 at 03:29:40PM +1000, Seth McDonald via isync-devel wrote:
>> > The interface's implementation adds minor changes in behaviour to
>> > simplify the authentication logic. This includes always attempting to
>> > fall back to LOGIN when SASL fails and unifying similar error messages.
>> >
>> semantically, that seems just wrong. you need to work a lot harder to
>> convince me that this is a wanted change.
>
>The primary motivation is that the current "flow" of the SASL logic is
>incompatible with the GNU SASL library.
>
upon a cursory look at the gsasl documentation, i don't see how that
would be fundamentally true.
in fact, i have the impression that you didn't study it particularly
thoroughly, given that you thought it necessary to hard-code the list of
available mechanisms.
a different angle is that it isn't necessary to utilize the library's
full potential. it's just fine to duplicate a bit of the library's
functionality if it makes the implementations more uniform. e.g., i
don't see any practical benefit in actually using gsasl's LOGIN support.
>Regarding the falling back to LOGIN, it simplifies the logic from
>unnecessarily complex "if it fails in this specific way, goto here; but
>if it fails like this, goto there" to "if it fails, try LOGIN instead".
>
that description of the status quo doesn't fill me with confidence that
you actually understand it.
>> > +static const char *
>> > +query_sasl_error( sasl_conn_t *ctx, int rc )
>> >
>> i don't want that obfuscation layer without good reason.
>
>I added it for two reasons:
>(0) It's simpler to have a single function to call to retrieve the
> appropriate error message, rather than manually switching
> between sasl_errdetail() and sasl_errstring() all the time.
>
it's two functions for a good reason, and i think that blurring the two
contexts is actively counter-productive.
>(1) To encompass the following fallback.
>
>> > + const char *err = ctx
>> > + ? sasl_errdetail( ctx )
>> > + : sasl_errstring( rc, NULL, NULL );
>>
>> > + return err ? err : "Unknown error";
>> >
>> what is that fallback for?
>
>From the documentation for sasl_errdetail() (see [0]):
>
>| Returns the string describing the error that occurred, or NULL if no
>| error has occurred, or there was an error retrieving it.
>
calling the function when no error occurred would be an internal error
in isync.
and error while retrieving an error string would be an internal error in
libsasl or the calling code.
in either case i want that to be glaringly obvious, not papered over.
>> > +static int
>> > +process_sasl_step(
>> > + } else {
>> > + const char *err = query_sasl_error( session, rc );
>> >
>> i don't like these pointless temporaries.
>
>I tend to use them for a few reasons:
>(0) They make debugging line-by-line with GDB easier by keeping calls on
> their own lines, which allows for easy stepping into/over select
> calls. This is especially true for function calls inside the
> conditions of if-statements.
>
this is true, but completely irrelevant for the "print stringified error
code" pattern.
>(1) They make git diff/blame cleaner by separating operations with
> newlines, which allows diff/blame to better identify and show
> the exact operations that were changed.
>
that's equally achievable by wrapping the "resolver" call to the next
line. but in this context it's also rather irrelevant.
>(2) They tell you what exactly you're retrieving from the function,
> which may not always be so obvious. For example, if a call
> returns a status, does zero indicate success or failure? A line
> like `if (!foo())` doesn't tell you much, but a line like
> `int bad = !foo();` tells you immediately it means failure.
>
also completely irrelevant in this context.
so same principle as everywhere: don't be verbose unless it adds actual
value.
and both of the above deviations from the established practice in isync
have absolutely no business in a commit that purports to do something
different.
>> > + intersect_mechs(
>> > + common_mechs + 1,
>> > + size - 1,
>> > + any_mech ? server_mechs : client_mechs,
>> > + server_mechs );
>> >
>> that call formatting is rarely used in isync, and looks weird even with the
>> smaller tabs. don't use it without strong reason (long argument list
>> starting beyond column ~60, or arguments with long comments).
>
>For context, my personal rule is: if it's within 80 columns, format as
>one line; otherwise, split the arguments as a separate line if they're
>within 80 columns; otherwise, have each argument on a separate line.
>
well, isync has no hard line length limit, as that just makes no sense
in conjunction with a variable tab width.
in practice i'm aiming for below 120 cols with 4-space tabs, but there
isn't really a rule when to wrap. logical argument grouping and
surrounding line lengths are key factors.
>(I like the 80-column limit as it makes side-by-side diffs a lot lot
>easier to view.)
>
i consider side-by-side diffs irrelevant. i sometimes switch to that view
when the code has been completely rewritten, i.e., there isn't actually
a meaningful local diff to begin with. in this situation, having to
side-scroll isn't all that bad (though still annoying, of course).
but i forgot to mention something before: judging by the sub-optimality
of some of the hunks, you don't seem to have switched your git diff
algorithm to histogram yet?
>So using this case as an example, would you prefer a more compact
>formatting like so:
>
> intersect_mechs(
> common_mechs + 1, size - 1,
> any_mech ? server_mechs : client_mechs, server_mechs );
>
yes, i would.
but that doesn't change the fact that deviating from the predominant
style of the code base needs to be well-justified in the first place.
>> > +typedef const char *(*imap_auth_cred_t)( void * );
>> > +
>> the consequences of having these are obviously ugly.
>> just factor out imap_auth_conf_t as i hinted at previously.
>
>Sure, but just FYI without it the logic will no longer be
>self-contained. It'll depend on the implementation of the IMAP driver,
>
why would it?
>and thus won't be able to be understood or maintained purely as a
>standalone unit (which was partly my goal).
>
i don't see that as a goal per se.
>> > +/*
>> > + * Formats a list of SASL mechanisms supported by both client and server side.
>> > + * The list is space-delimited, including starting and ending with whitespace.
>> > + * Mechanisms are parsed in a case-insensitive manner.
>> > + */
>> > +void imap_auth_filter_mechs(
>> >
>> this seems like an implementation detail that should not leak through the
>> abstraction.
>
>Not sure I entirely agree.
>The case-insensitive detail [...]
>The space-delimited detail [...]
>
you didn't pay attention to the reply placement ...
i question the function being part of the iface in the first place.
>> > +char *
>> > +find_string_list( const string_list_t *list, const char *str )
>> > +
>> > +char *
>> > +find_string_list_case( const string_list_t *list, const char *str )
>>
>> the return values make no sense. these should be bools, and the functions
>> called contains_....
>
>I was aiming for a function analogous to strstr(). It's purpose is to
>find and, if found, return a string within a string list. And like
>strstr(), it can be used secondarily to only check if the string list
>contains the string by checking if the return value is NULL.
>
don't try to make analogous interfaces when there is a cost, but no
obvious advantage for existing use cases.
>> related to other comments, i find it debatable that factoring these
>> out
>> actually makes sense. but if it does, it would have to happen in a separate
>> patch.
>
>So you're okay with patches that add general functions but don't include
>their usage until later patches?
>
that's not at all what i said.
if you want to refactor that aspect, then do it in a separate commit.
only then the effect of the _change_ can be judged without it being
completely drowned out by the surrounding bigger changes.
>> your prior macos keychain patches should be integrated into this
>> series to
>> reduce overall churn. for that purpose, it's ok to either
>> - during refactoring, leave code in its old place when it will be replaced
>> in subsequent patches, or
>> - to add code in a new file that will be logically created only in the
>> subsequent refactoring (i think this is the case applicable here).
>
>I'm afraid I don't see how integrating the keychain patches into this
>patchset will reduce churn. The imap_auth_* interface doesn't touch nor
>take responsibility for either the keychain code or the
>password-querying logic as a whole. It calls (directly or indirectly)
>ensure_password(), but doesn't care how that function works.
>
that argument is just wrong in light of the imap_auth_conf_t discussion
above.
>For (more) context about me, I like to explicitly document functions'
>effects that are relied upon in the codebase. This is because when
>analysing code, I find it very useful to know exactly what a function is
>_supposed_ to do, and to contrast that with what it _actually_ does. I
>don't assume everyone can infer all my intentions (including myself),
>however obvious I think it to be.
>
sure, but there is a cost to maintaining that, and even reading it
(because of needing to verify the ongoing validity). it just doesn't pay
off at the scale and process requirements we are dealing with here.
|
|
From: Seth M. <de...@se...> - 2026-07-24 04:37:56
|
Thanks for the detailed feedback.
On Wed, 22 Jul 2026 at 14:57:28 +0200, Oswald Buddenhagen wrote:
> On Sat, Jul 18, 2026 at 03:29:40PM +1000, Seth McDonald via isync-devel wrote:
> > The interface's implementation adds minor changes in behaviour to
> > simplify the authentication logic. This includes always attempting to
> > fall back to LOGIN when SASL fails and unifying similar error messages.
> >
> semantically, that seems just wrong. you need to work a lot harder to
> convince me that this is a wanted change.
The primary motivation is that the current "flow" of the SASL logic is
incompatible with the GNU SASL library. Many error messages simply do
not apply or cannot occur in the same order. So to ensure minimal
functional difference between the two implementations, I have to make
the current logic for Cyrus SASL more compatible with the new logic for
GNU SASL.
If I don't make these changes, then not only will the two
implementations be more functionally different than necessary, but it
becomes near impossible to have more fine-grained #ifdefs (as you
requested later in the message) due to the divergent logical flow. It's
really one or the other.
Regarding the falling back to LOGIN, it simplifies the logic from
unnecessarily complex "if it fails in this specific way, goto here; but
if it fails like this, goto there" to "if it fails, try LOGIN instead".
And as a user, I don't want the program to bother me about its troubles
if it can sort itself out by trying a different method. I don't care
about the method used as long as it's secure enough and it works.
> structurally, this cannot go into the same patch. do it before or after.
>
> have a look at the patches surrounding previous refactorings to get an idea
> of the things i like to separate from them, and how.
>
> i looked through the history for references, and d5a5da947 seems comparable
> in scope.
> it's clearly changing the code structure in addition to moving the code, but
> notably the visible behavior is not changed.
Thanks; I'll give it a good look.
> > +static const char *
> > +query_sasl_error( sasl_conn_t *ctx, int rc )
> >
> i don't want that obfuscation layer without good reason.
I added it for two reasons:
(0) It's simpler to have a single function to call to retrieve the
appropriate error message, rather than manually switching
between sasl_errdetail() and sasl_errstring() all the time.
(1) To encompass the following fallback.
> > + const char *err = ctx
> > + ? sasl_errdetail( ctx )
> > + : sasl_errstring( rc, NULL, NULL );
>
> > + return err ? err : "Unknown error";
> >
> what is that fallback for?
>From the documentation for sasl_errdetail() (see [0]):
| Returns the string describing the error that occurred, or NULL if no
| error has occurred, or there was an error retrieving it.
> > +static int
> > +process_sasl_step(
> > + } else {
> > + const char *err = query_sasl_error( session, rc );
> >
> i don't like these pointless temporaries.
I tend to use them for a few reasons:
(0) They make debugging line-by-line with GDB easier by keeping calls on
their own lines, which allows for easy stepping into/over select
calls. This is especially true for function calls inside the
conditions of if-statements.
(1) They make git diff/blame cleaner by separating operations with
newlines, which allows diff/blame to better identify and show
the exact operations that were changed.
(2) They tell you what exactly you're retrieving from the function,
which may not always be so obvious. For example, if a call
returns a status, does zero indicate success or failure? A line
like `if (!foo())` doesn't tell you much, but a line like
`int bad = !foo();` tells you immediately it means failure.
I honestly don't see why they shouldn't be used. There's no runtime
cost as they'll be optimised out by the compiler.
> > + intersect_mechs(
> > + common_mechs + 1,
> > + size - 1,
> > + any_mech ? server_mechs : client_mechs,
> > + server_mechs );
> >
> that call formatting is rarely used in isync, and looks weird even with the
> smaller tabs. don't use it without strong reason (long argument list
> starting beyond column ~60, or arguments with long comments).
For context, my personal rule is: if it's within 80 columns, format as
one line; otherwise, split the arguments as a separate line if they're
within 80 columns; otherwise, have each argument on a separate line.
(I like the 80-column limit as it makes side-by-side diffs a lot lot
easier to view.)
So using this case as an example, would you prefer a more compact
formatting like so:
intersect_mechs(
common_mechs + 1, size - 1,
any_mech ? server_mechs : client_mechs, server_mechs );
> > +typedef const char *(*imap_auth_cred_t)( void * );
> > +
> the consequences of having these are obviously ugly.
> just factor out imap_auth_conf_t as i hinted at previously.
Sure, but just FYI without it the logic will no longer be
self-contained. It'll depend on the implementation of the IMAP driver,
and thus won't be able to be understood or maintained purely as a
standalone unit (which was partly my goal).
> > + int force; /* Whether to allow use of LOGIN over an insecure channel. */
> > + int saslir; /* Whether the SASL-IR capability is available. */
> > + int secure; /* Whether the connection is over a secure channel. */
> >
> it's debatable whether these should be structure members. based on their
> lifetime, i'd expect function parameters.
Fair. I just had these as members cause I didn't want too many boolean
parameters.
> > +void imap_auth_new_client( imap_auth_client_t *client );
>
> also, the _client suffixes seem annoying.
> instead, the global functions should get _lib suffixes or something.
Sure, that works.
> > +/*
> > + * Formats a list of SASL mechanisms supported by both client and server side.
> > + * The list is space-delimited, including starting and ending with whitespace.
> > + * Mechanisms are parsed in a case-insensitive manner.
> > + */
> > +void imap_auth_filter_mechs(
> >
> this seems like an implementation detail that should not leak through the
> abstraction.
Not sure I entirely agree. The case-insensitive detail is definitely
relevant as the passed server side mechs are upper case, while the
passed client side mechs may be lower case. So the caller knows they
don't have to format the client side mechs before calling.
The space-delimited detail I agree is an implementation detail, but
should probably be mentioned at least somewhere since it's directly
relied upon for searching the list. I'll probably just move it to the
source file instead of the header.
> > +char *
> > +find_string_list( const string_list_t *list, const char *str )
> > +
> > +char *
> > +find_string_list_case( const string_list_t *list, const char *str )
>
> the return values make no sense. these should be bools, and the functions
> called contains_....
I was aiming for a function analogous to strstr(). It's purpose is to
find and, if found, return a string within a string list. And like
strstr(), it can be used secondarily to only check if the string list
contains the string by checking if the return value is NULL.
> related to other comments, i find it debatable that factoring these out
> actually makes sense. but if it does, it would have to happen in a separate
> patch.
So you're okay with patches that add general functions but don't include
their usage until later patches? Not saying that's bad; I just usually
include such usage as implicit justification for the patch.
> i think it would yield cleaner code to amend HAVE_LIBSASL with SASL_IS_GNU
> rather than having two mutually exclusive defines.
Agreed.
> your prior macos keychain patches should be integrated into this series to
> reduce overall churn. for that purpose, it's ok to either
> - during refactoring, leave code in its old place when it will be replaced
> in subsequent patches, or
> - to add code in a new file that will be logically created only in the
> subsequent refactoring (i think this is the case applicable here).
I'm afraid I don't see how integrating the keychain patches into this
patchset will reduce churn. The imap_auth_* interface doesn't touch nor
take responsibility for either the keychain code or the
password-querying logic as a whole. It calls (directly or indirectly)
ensure_password(), but doesn't care how that function works.
> finally, as i already pointed out in
> https://sourceforge.net/p/isync/mailman/message/59319314/ , i'm not a fan of
> verbosity. document only things that are not obvious, and check first
> whether they can't be made obvious instead.
Good to know; I'll revise the comments.
For (more) context about me, I like to explicitly document functions'
effects that are relied upon in the codebase. This is because when
analysing code, I find it very useful to know exactly what a function is
_supposed_ to do, and to contrast that with what it _actually_ does. I
don't assume everyone can infer all my intentions (including myself),
however obvious I think it to be.
Take care,
Seth McDonald.
[0]
<https://www.cyrusimap.org/sasl/sasl/reference/manpages/library/sasl_errdetail.html>
--
E9D1 26A5 F0D4 9DF7 792B C2E2 B4BF 4530 D39B 2D51
|
|
From: Oswald B. <osw...@gm...> - 2026-07-22 12:57:42
|
On Sat, Jul 18, 2026 at 03:29:40PM +1000, Seth McDonald via isync-devel wrote:
>To authenticate to IMAP servers, mbsync uses SASL if linked with the
>Cyrus SASL library (libsasl2) and falls back to LOGIN otherwise.
>
this is too detailed. the details are not relevant to the next sentence,
so they connect poorly/misleadingly.
>This
>logic was inline in the IMAP driver but was mostly independent of the
>surrounding logic.
>Factor out this authentication logic into its own independent interface
>(imap_auth_*). This isolates the logic
>and thereby allows it to be more
>easily extended with a different SASL library (e.g. GNU SASL).
>
i find that claim debatable. it's also kinda unnecessary, as a good
refactoring should stand on its own merits. one can mention it in
passing as a bonus.
>The interface's implementation adds minor changes in behaviour to
>simplify the authentication logic. This includes always attempting to
>fall back to LOGIN when SASL fails and unifying similar error messages.
>
semantically, that seems just wrong. you need to work a lot harder to
convince me that this is a wanted change.
structurally, this cannot go into the same patch. do it before or after.
have a look at the patches surrounding previous refactorings to get an
idea of the things i like to separate from them, and how.
i looked through the history for references, and d5a5da947 seems
comparable in scope.
it's clearly changing the code structure in addition to moving the code,
but notably the visible behavior is not changed.
>+++ b/src/imap_auth.c
>+static const char *
>+query_sasl_error( sasl_conn_t *ctx, int rc )
>
i don't want that obfuscation layer without good reason.
>+{
>+ const char *err = ctx
>+ ? sasl_errdetail( ctx )
>+ : sasl_errstring( rc, NULL, NULL );
>+ return err ? err : "Unknown error";
>
what is that fallback for?
>+static int
>+process_sasl_step(
>+ } else {
>+ const char *err = query_sasl_error( session, rc );
>
i don't like these pointless temporaries.
don't try to "hide" style changes in the refactoring.
>+ intersect_mechs(
>+ common_mechs + 1,
>+ size - 1,
>+ any_mech ? server_mechs : client_mechs,
>+ server_mechs );
>
that call formatting is rarely used in isync, and looks weird even with
the smaller tabs. don't use it without strong reason (long argument list
starting beyond column ~60, or arguments with long comments).
>+++ b/src/imap_auth.h
as i wrote before, i think putting it into imap_p.h would be preferable.
mostly because i don't want the inconsistency with the other extracted
subsystems, and i don't want to create micro-headers for them, either.
>+typedef const char *(*imap_auth_cred_t)( void * );
>+
the consequences of having these are obviously ugly.
just factor out imap_auth_conf_t as i hinted at previously.
>+/*
>+ * The client side state of an IMAP authentication process.
>+ */
>+typedef struct imap_auth_client {
>+ /* Callback to obtain username and authorization identity. */
>+ imap_auth_cred_t user_cb; /* Is non-NULL. */
>+ void *user_arg; /* May be NULL. */
>+
>+ /* Callback to obtain password. */
>+ imap_auth_cred_t pass_cb; /* Is non-NULL. */
>+ void *pass_arg; /* May be NULL. */
>+
>+ const char *domain; /* E.g. "imap.server.com". Is non-NULL. */
>+ int force; /* Whether to allow use of LOGIN over an insecure channel. */
>+ int saslir; /* Whether the SASL-IR capability is available. */
>+ int secure; /* Whether the connection is over a secure channel. */
>
it's debatable whether these should be structure members. based on their
lifetime, i'd expect function parameters.
>+ int cont; /* Whether another authentication step is expected. */
>+
>+ /*
>+ * Library-dependent session state.
>+ * Currently holds:
>+ * - Cyrus SASL: sasl_conn_t *
>+ * - No library: NULL
>
nope. #ifdef. also above. i don't want dead members.
>+/*
>+ * Initializes a new auth client with a default state.
>+ */
consequently, it should be init_client.
>+void imap_auth_new_client( imap_auth_client_t *client );
also, the _client suffixes seem annoying.
instead, the global functions should get _lib suffixes or something.
>+/*
>+ * Frees all resources associated with an auth client.
>+ * The client structure should not be reused unless it is reinitialized.
>+ */
here, cleanup_client would be more fitting.
>+void imap_auth_free_client( imap_auth_client_t *client );
>+/*
>+ * Formats a list of SASL mechanisms supported by both client and server side.
>+ * The list is space-delimited, including starting and ending with whitespace.
>+ * Mechanisms are parsed in a case-insensitive manner.
>+ */
>+void imap_auth_filter_mechs(
>
this seems like an implementation detail that should not leak through
the abstraction.
>+++ b/src/util.c
>
>+char *
>+find_string_list( const string_list_t *list, const char *str )
>+
>+char *
>+find_string_list_case( const string_list_t *list, const char *str )
the return values make no sense. these should be bools, and the
functions called contains_....
related to other comments, i find it debatable that factoring these out
actually makes sense. but if it does, it would have to happen in a
separate patch.
i didn't comment on everything i find objectionable, because i expect
many things to change fundamentally.
i also didn't mention repetitions, because i expect you to find
analogous cases yourself.
as mentioned in several places, this patch still does way too many
things at once. while you don't necessarily need to start _physically_
from scratch, you really need to do that _logically_. fire up git gui
and add each hunk/line separately, checking whether it actually fits the
scope of the commit. stash and rework as necessary to get a nice series
of atomic commits with convincing commit messages. you won't get
"frivolous" changes past me.
just two notes on the followup patch:
i think it would yield cleaner code to amend HAVE_LIBSASL with
SASL_IS_GNU rather than having two mutually exclusive defines.
secondly, reduce the scope of the #ifdefs. minimizing duplication is
very high up on my priority list.
your prior macos keychain patches should be integrated into this series
to reduce overall churn. for that purpose, it's ok to either
- during refactoring, leave code in its old place when it will be
replaced in subsequent patches, or
- to add code in a new file that will be logically created only in the
subsequent refactoring (i think this is the case applicable here).
in either case, forward declarations can be used to overcome the
temporarily missing locality.
finally, as i already pointed out in
https://sourceforge.net/p/isync/mailman/message/59319314/ , i'm not a
fan of verbosity. document only things that are not obvious, and check
first whether they can't be made obvious instead. the criterion for
"obvious" is "obvious after actually considering the prototype and a
cursory reading of the implementation". as everything else,
documentation also needs to pull its own weight. this isn't a library
whose implementation should be treated as a black box.
|