refactor(general): rename repodiag.logWriteSyncer (#4109)

* refactor(general): clarify comments

* refactor(general): rename `repodiag.logWriteSyncer`

This name reflects:
- the function of the struct; and
- the interface it implements (`zapcore.WriteSyncer`)

internal/repodiag/log_manager.go

@@ -24,7 +24,9 @@
 
 // LogManager manages writing encrypted log blobs to the repository.
 type LogManager struct {
-	enabled atomic.Bool // set by enable(), logger is ineffective until called
+	// Set by Enable(). Log blobs are not written to the repository until
+	// Enable() is called.
+	enabled atomic.Bool
 
 	// InternalLogManager implements io.Writer and we must be able to write to the
 	// repository asynchronously when the context is not provided.
@@ -50,7 +52,7 @@ func (m *LogManager) NewLogger() *zap.SugaredLogger {
 
 	rand.Read(rnd[:]) //nolint:errcheck
 
-	w := &internalLogger{
+	w := &logWriteSyncer{
 		m:      m,
 		prefix: blob.ID(fmt.Sprintf("%v%v_%x", LogBlobPrefix, clock.Now().Local().Format("20060102150405"), rnd)),
 	}
@@ -63,7 +65,8 @@ func (m *LogManager) NewLogger() *zap.SugaredLogger {
 		w, zap.DebugLevel), zap.WithClock(zaplogutil.Clock())).Sugar()
 }
 
-// Enable enables writing any buffered logs to repository.
+// Enable enables writing log blobs to repository.
+// Logs are not written to the repository until Enable is called.
 func (m *LogManager) Enable() {
 	if m == nil {
 		return

internal/repodiag/log_write_syncer.go

@@ -11,9 +11,8 @@
 	"github.com/kopia/kopia/repo/blob"
 )
 
-// internalLogger represents a single log session that saves log files as blobs in the repository.
-// The logger starts disabled and to actually persist logs enable() must be called.
-type internalLogger struct {
+// logWriteSyncer writes a sequence of log messages as blobs in the repository.
+type logWriteSyncer struct {
 	nextChunkNumber atomic.Int32
 
 	m  *LogManager
@@ -30,7 +29,7 @@ type internalLogger struct {
 	prefix blob.ID // +checklocksignore
 }
 
-func (l *internalLogger) Write(b []byte) (int, error) {
+func (l *logWriteSyncer) Write(b []byte) (int, error) {
 	if l != nil {
 		l.maybeEncryptAndWriteChunkUnlocked(l.addAndMaybeFlush(b))
 	}
@@ -38,7 +37,7 @@ func (l *internalLogger) Write(b []byte) (int, error) {
 	return len(b), nil
 }
 
-func (l *internalLogger) maybeEncryptAndWriteChunkUnlocked(data gather.Bytes, closeFunc func()) {
+func (l *logWriteSyncer) maybeEncryptAndWriteChunkUnlocked(data gather.Bytes, closeFunc func()) {
 	if data.Length() == 0 {
 		closeFunc()
 		return
@@ -60,7 +59,7 @@ func (l *internalLogger) maybeEncryptAndWriteChunkUnlocked(data gather.Bytes, cl
 	l.m.encryptAndWriteLogBlob(prefix, data, closeFunc)
 }
 
-func (l *internalLogger) addAndMaybeFlush(b []byte) (payload gather.Bytes, closeFunc func()) {
+func (l *logWriteSyncer) addAndMaybeFlush(b []byte) (payload gather.Bytes, closeFunc func()) {
 	l.mu.Lock()
 	defer l.mu.Unlock()
 
@@ -77,7 +76,7 @@ func (l *internalLogger) addAndMaybeFlush(b []byte) (payload gather.Bytes, close
 }
 
 // +checklocks:l.mu
-func (l *internalLogger) ensureWriterInitializedLocked() io.Writer {
+func (l *logWriteSyncer) ensureWriterInitializedLocked() io.Writer {
 	if l.gzw == nil {
 		l.buf = gather.NewWriteBuffer()
 		l.gzw = gzip.NewWriter(l.buf)
@@ -88,7 +87,7 @@ func (l *internalLogger) ensureWriterInitializedLocked() io.Writer {
 }
 
 // +checklocks:l.mu
-func (l *internalLogger) flushAndResetLocked() (payload gather.Bytes, closeFunc func()) {
+func (l *logWriteSyncer) flushAndResetLocked() (payload gather.Bytes, closeFunc func()) {
 	if l.gzw == nil {
 		return gather.Bytes{}, func() {}
 	}
@@ -105,13 +104,13 @@ func (l *internalLogger) flushAndResetLocked() (payload gather.Bytes, closeFunc
 	return res, closeBuf
 }
 
-func (l *internalLogger) logUnexpectedError(err error) {
+func (l *logWriteSyncer) logUnexpectedError(err error) {
 	if err == nil {
 		return
 	}
 }
 
-func (l *internalLogger) Sync() error {
+func (l *logWriteSyncer) Sync() error {
 	l.mu.Lock()
 	data, closeFunc := l.flushAndResetLocked()
 	l.mu.Unlock()

repo/content/content_manager.go

@@ -735,7 +735,7 @@ func (bm *WriteManager) getOrCreatePendingPackInfoLocked(ctx context.Context, pr
 		return pp, nil
 	}
 
-	bm.repoLogManager.Enable()
+	bm.repoLogManager.Enable() // signal to the log manager that a write operation will be attempted so it is OK to write log blobs to the repo
 
 	b := gather.NewWriteBuffer()