Define, document, and release a stable (v1) version.

[creachadair]

This module is currently versioned for development (v0).

Where practical, I try to avoid breaking API changes. However, when I do need to change the API I've adopted the convention of incrementing the minor version number. For other changes I will generally only increment the patch number. Hence, v0.11.1 to v0.11.2 should be a "safe" (non-breaking) upgrade, whereas v0.12.1 to v0.13.0 includes visible API effects that may require client code to be updated.

This issue was created to track the definition and release of a stable (v1) version. Broadly: I would like to trim down the API as much as possible for such a release.

Summary of Changes

package jrpc2

• Export the fields of the Error type, remove unnecessary methods (b11415d, c677bac, 14261a3, 37bcf3b)
• Remove redundant context value functions (d4361e1)
• Remove the built-in "rpc.cancel" implementation (Remove non-standard cancellation protocol handling #49)
• Rework the jrpc2.Network return signature (Update the Network helper to return a tuple. #51)
• Move command-line tools and examples to a submodule (f3f3c4c)
• Rework the text logger interface to not require a standard logger (bfa778d)
• Remove the "AllowV1" client and server settings (Remove the client and server "AllowV1" settings. #61)
• Remove the request-check hook (Remove the CheckRequest server option. #62)
• Remove the parameter wrapping hooks (Remove support for parameter injection. #82)
• Simplify the Handler type (Replace the Handler interface with a plain function type. #90)
• Collapse the code package into the root (Collapse the code package into jrpc2. #97)

package jhttp

• Simplify the Bridge implementation (jhttp: extend and simplify request processing hooks #65, jhttp: Remove the CheckRequest bridge hook #67)
• Add a GET bridge (jhttp: add a Getter type to handle GET requests #68)

package channel

• Remove the separate Sender and Receiver interfaces (65bf9ad)
• Remove the unused WithTrigger wrapper channel (a5d1a82)

package handler

• Remove the NewService constructor (0ee4b78)
• Remove the Varint framing (2534128)
• Add support for positional handler function parameters (Support positional argument in wrapped handlers #59)
• Remove support for variadic handler functions (4780235)

package server

• Simplify the "service" runner API (4bb7b22)
• Make the loop listener interface easier to implement (31ce9d5)
• Make the loop and accepter accept contexts (server: update context plumbing #66)
• Remove the Run helper (server: remove the Run helper #92)

Other

• Remove the jctx package (Remove support for parameter injection. #82)
• Remove the metrics package and use expvar instead (Replace idiosyncratic metrics collector with expvar. #89)
• Remove the registration mechanism for error codes (code: remove the code registration hooks #91)

[creachadair]

Candidates for removal:

1. handler.NewService. Apart from the convenience of extracting the names, this has no real advantage over explicitly constructing the map. Moreover, it cannot handle unexported methods, and the names it assigns are whatever Go uses, not necessarily what a service definition requires. Better to let the caller be explicit. ✅ 0ee4b78
2. channel.Varint. Convert to example code. ✅ 2534128

[creachadair]

I would like to simplify the server package somewhat, and improve the naming. The terms "service", "simple", and "static" are used confusingly, and I think should be cut down.

My current thinking is to consolidate "simple" and "static" into a single concept: A "static" service implementation is one without a meaningful constructor. Instead of a separate type for single-throw services, the package can have a top-level Run function that does the work.

✅ 4bb7b22

[creachadair]

Possible server simplification: Re-combine the Wait and WaitStatus methods, and give the error reported by Wait a documented concrete type. Now, Wait reports the underlying error; with this change it would always return a status value.

❌ Decided not to do this; conflating these two doesn't save much and the semantics are different enough to be worth keeping separate.

[creachadair]

Possible error simplification: Export most or all of the fields of the *Error type, and drop the methods. Support for marshaling and unmarshling JSON is still necessary, but making the type usable directly is more idiomatic.

✅ b11415d

[creachadair]

Possible server simplification: Now that the server is exposed to handlers via the context, there is no longer any need for separate top-level PushNotify, PushCallback, or ServerMetrics functions.

To get rid of ServerMetrics would require adding a method to expose it, though.

✅ d4361e1

[creachadair]

Remove the parameter-wrapping context plumbing hooks. This was meant as a transparent way to encode context settings, but it was a lot of overhead for relatively little use.

✅ #82

[creachadair]

Replace the custom metrics collector plumbing with the standard expvar package. This will make it easier to export metrics to more conventional collectors like Prometheus.

✅ #89

[creachadair]

Simplify the Handler type to be a plain function instead of an interface.

✅ #90

[creachadair]

Rip out the registration mechanism for error code values. In practice any package that wants to define custom codes has to keep track of them anyway, so that the client can coordinate with the server. The additional hook for cosmetics in the default error string is just not worthwhile.

✅ #91

[creachadair]

Look for usage of the server.Run function and see if we can get rid of it or adapt the use.

✅ #92

[creachadair]

Convert handler.Func into a plain type alias and remove the repetition of the type signature in the Check plumbing.

✅ e1278b5

[creachadair]

I think the package has reached a stable enough API that it's time to cut a v1. The remaining tasks will be:

• Do a thorough audit of the package, type, and function docs (Update doc comments throughout the module. #98).
• Update the README to reflect the stable API and remove the old language about pre-v1 tags (3540e6c).
• Update and simplify the playground example linked from the README.
• Survey existing use to make sure I haven't missed something important.

I haven't decided whether to bother with a separate release branch; I think probably not. If a v2 release becomes desirable I'll clone the code into a submodule, it's not that big a project.

[radeksimko]

I'm not sure if it needs to change the API in any way to account for this - probably not necessarily backwards incompatible way - but unless you're already keeping eye, I'd recommend checking out the proposal for structured logging which was recently accepted: golang/go#56345

[creachadair]

Thanks for flagging that. I don't think the server and client debug logs would benefit much from adding structure, but if an application wants to use structured logs in handlers, it would be easy to plumb through a logger via the NewContext server option and handlers could use it, e.g.,

type slogKey struct{}

func WithLogger(ctx context.Context, s *slog.Logger) context.Context {
   return context.WithValue(ctx, slogKey{}, s)
}

func Logger(ctx context.Context) *slog.Logger {
   if s := ctx.Value(slogKey{}); s != nil {
      return s.(*slog.Logger)
   }
   return slog.Default()
}

opts := &jrpc2.ServerOptions{
  NewContext: func() context.Context {
    return WithLogger(context.Background(), myLogger)
  },
}

func Handle(ctx context.Context, req *jrpc2.Request) (any, error) {
   Logger(ctx).Info("hello from handler", "method", req.Method())
   return "ok", nil
}

or words to that effect.

I'm a little disappointed that this API got approved as-written, but I don't see any obvious compatibility concerns. If we later need to bolt structured logging on to the existing debug facility, it wouldn't be too bad to add another hook to the options.

[creachadair]

v1.0.0 is now tagged and available.