proposal: x/time: rate-limited Writer for bandwidth control

[mohanson]

Proposal Details

Summary

This proposal requests the addition of a Writer type that implements io.Writer with built-in rate limiting capabilities to control write operations' bandwidth consumption. This feature would enable developers to easily implement bandwidth throttling for network connections, file operations, and other I/O scenarios.

Motivation

Current Problem

Currently, implementing rate limiting for I/O operations requires:

1. Manual integration of rate limiting logic with I/O operations
2. Scattered rate limiting code throughout applications
3. Complex coordination between multiple rate limiters (global vs per-connection)
4. No standardized approach for bandwidth control

Use Cases

1. Network Bandwidth Management: Limit upload/download speeds for individual connections or globally
2. Server Resource Protection: Prevent individual clients from consuming excessive bandwidth
3. Fair Resource Allocation: Ensure equitable bandwidth distribution among multiple clients
4. Background Process Throttling: Limit bandwidth usage of background sync operations
5. Testing and Simulation: Simulate network conditions with controlled bandwidth

Proposed Solution

API Design

// Writer is an io.Writer that applies rate limiting to write operations.
//
// For example, to limit a reader's read speed to 1KB/s:
//
//	limits := rate.NewLimiter(rate.Every(time.Second/1024.0), 1024)
//	reader := io.TeeReader(os.Stdin, NewWriter(limits))
//
// Or, to limit a writer's write speed to 1KB/s:
//
//	writer := io.MultiWriter(os.Stdout, NewWriter(limits))
type Writer struct {
	li *rate.Limiter
}

// Write writes data to the underlying writer, applying rate limiting based on
// the configured limits.
func (l *Writer) Write(p []byte) (int, error) {
	l.li.WaitN(context.Background(), len(p))
	return len(p), nil
}

// NewWriter creates a new Writer that limits write operations by a limiter.
func NewWriter(limiter *rate.Limiter) *Writer {
	return &Writer{li: limits}
}

Usage Examples

Basic Reader Rate Limiting

limits := rate.NewLimiter(rate.Every(time.Second/1024.0), 1024) // 1KB per second
reader := io.TeeReader(os.Stdin, NewWriter(limits))
reader.Read(...)

Basic Writer Rate Limiting

limits := rate.NewLimiter(rate.Every(time.Second/1024.0), 1024) // 1KB per second
writer := io.MultiWriter(os.Stdout, NewWriter(limits))
writer.Write(...)

Network Connection Rate Limiting

Containing both global and per-connection limits:

l, _ := net.Listen("tcp", "127.0.0.1:8080")

// A global connection limit for all connections. 1MB per second.
globalLimits := rate.NewLimiter(rate.Every(time.Second/1024/1024), 1024*1024)

for {
    cli, _ := l.Accept()

    // A single connection limit. 1KB per second.
    singleLimits := rate.NewLimiter(rate.Every(time.Second/1024), 1024) // 1KB per second

    // Make a reader that applies both global and single connection limits.
    var cliReader io.Reader = cli
    cliReader = io.TeeReader(cli, NewWriter(globalLimits))       // Apply global connection read limit
    cliReader = io.TeeReader(cliReader, NewWriter(singleLimits)) // Apply single connection read limit

    go func() {
        io.Copy(io.Discard, cliReader) // Discard all data read from the connection, simulating processing.
    }()
}

Conclusion

The addition of a rate-limited Writer type would provide a clean, composable solution for bandwidth control in Go applications. It follows established patterns in the standard library (io.TeeReader and io.MultiWriter) while addressing a common need in network programming, file operations, and resource management scenarios.

This feature would significantly simplify the implementation of bandwidth-aware applications and provide a standardized approach to rate limiting across the Go ecosystem.

[gabyhelp]

Related Issues

• proposal: io: add LimitWriter #54548 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[seankhliao]

given how simple the implementation is, this falls in to the category of https://go.dev/doc/faq#x_in_std unless we see it being widely used in existing codebases.

[mohanson]

Hi, I know you closed this issue, but maybe we can discuss the "duplication of effort" that developers put in to implement this. Many large open source projects implement their own I/O rate limiting for read/write operations, which is very common in network applications. For example:

• frp: https://github.com/fatedier/frp/tree/master/pkg/util/limit It directly wraps an io.Reader/io.Writer inside a struct.
• rclone: https://github.com/rclone/rclone/blob/a7dd78756904d031d7eb7fe2448f9361f6adbc80/fs/accounting/token_bucket.go#L165-L179 It chooses to manually implement rate limiting logic in read/write functions, a very "handcrafted" implementation.
• goproxy: https://github.com/snail007/goproxy/blob/master/utils/io-limiter.go The basic implementation logic is completely consistent with frp.
• daze: https://github.com/libraries/daze/blob/0f4fa9d84f522e0dd5b7a2147067214f0a59c018/protocol/ashe/engine.go#L237-L241 Using the same approach as this proposal

Developers widely demand rate limiting for network applications. As you can see, manually implementing this functionality from scratch is not easy. In contrast, this proposal provides a common and easy solution.