Hertz Release v0.6.0
Projects:
In version 0.6.0 of Hertz, in addition to regular iterative optimization, we also brought several important features.
HTTP Trailer support
In Hertz v0.6.0, we support encoding and parsing of HTTP Trailer.
https://github.com/cloudwego/hertz-examples/tree/main/trailer
- Write Trailer
// server
func handler(ctx context.Context, c *app.RequestContext){
c.Response.Header.Trailer().Set("Hertz", "Good")
}
// client
req.Header.Trailer().Set("Hertz", "Good")
- Read Trailer
// server
func handler(ctx context.Context, c *app.RequestContext){
c.Request.Header.Trailer().Get("Hertz")
}
// client
resp.Header.Trailer().Get("Hertz")
HTTP/1.1 supports for Response Writer hijacking
In Hertz v0.6.0, we extended the HTTP/1.1 write request approach. Based on the original write request flow, we support users to hijack the Response Writer in the business handler/middleware to achieve a more flexible write request approach.In simple terms, all the original “underlying write” logic is unified behind the handler/middleware return, which has two obvious limitations.
- The user has no control over the timing of the request flush to the other end
- For the scenario of incremental data generation & real-time writing to the peer by chunk, the usage is relatively complicated and restrictive on top of the old architecture
Based on this, we extend a Writer that provides the ability to flush request headers and request bodies on its own, while providing support for users to send chunk data on demand. See https://github.com/cloudwego/hertz/pull/610 for a detailed implementation.
Major Changes
Added an interface definition that extends Writer,
Writers
that implement this interface can be used to hijack Response Writer:type ExtWriter interface { io.Writer Flush() error // Finalize will be called by framework before the writer is released. // Implementations must guarantee that Finalize is safe for multiple calls. Finalize() error }
Provides a
Chunk Writer
that implements the above interface (you can refer to this for similar requirements):chunkedBodyWrite
HTTP/1.1 does the corresponding processing (skipping the default write request logic) for Response write operations where the Writer has been hijacked, and finally calls the
Finalize()
method of theExtWriter
interface to complete a request write back
Usage
As above, Hertz provides a default ExtWriter
implementation to meet the user’s active flush needs in the handler/middleware, and it is very simple to use.
h.GET("/flush/chunk", func(ctx context.Context, c *app.RequestContext) {
// Hijack the writer of response
c.Response.HijackWriter(resp.NewChunkedBodyWriter(&c.Response, c.GetWriter()))
for i := 0; i < 10; i++ {
c.Write([]byte(fmt.Sprintf("chunk %d: %s", i, strings.Repeat("hi~", i)))) // nolint: errcheck
c.Flush() // nolint: errcheck
time.Sleep(200 * time.Millisecond)
}
})
Scaffolding Tool Usage Optimization & Best Practices
In hz v0.6.0, we have made a number of optimizations to the organization of the generated code, allowing for a more flexible code organization
Major Optimization
- The
new
command supports the “router_dir” option and works with the existing “handler_dir” and “model_dir” to fully customize the path to the IDL generation product; it also persists these custom options in the “.hz” file, which can be read automatically duringupdate
, reducing the complexity of the command - Add the ability to search up the “go.mod” file so that hertz can share the same “go module” with other projects when it is a subproject
- Add the ability to reference third-party IDL products in the “handler”, so that IDL products can be maintained separately in the third-party repository and not stored in the project directory, further enhancing IDL management capabilities
Best Practices
We have rewritten “biz-demo/easy-note” with “hz v0.6.0” to take advantage of the following hz features
- Generate hertz client call code for accessing “api server” based on IDL using the capabilities of “hz client”
- Reorganize the “api server” code with custom “router_dir”, “handler_dir”, and “model_dir” options, and remove the “biz” directory restriction
- Use the ability to “search up go.mod” so that “api server” can share the same “go module” as a subproject of “easy-note”
- Use the ability of “handler to refer to third-party IDL products” and the ability of “hz model” to store IDL products separately in the “easy-note” project and not in the “api server” subproject
Full Release Note
The complete Release Note can refer to: