Skip to content

Commit

Permalink
Format
Browse files Browse the repository at this point in the history
  • Loading branch information
@smaye81
smaye81 committed Nov 12, 2024
1 parent 94d810c commit 29bf18b
Showing 1 changed file with 48 additions and 47 deletions.
95 changes: 48 additions & 47 deletions MIGRATING.md
View file
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
# Connect v1 to v2 migration guide

Connect v2 provides new features and simplifies some common APIs. In addition,
it makes use of all the enhancements of Protobuf-ES v2. If you're currently
it makes use of all the enhancements of Protobuf-ES v2. If you're currently
using Connect v1, this document walks you through all you need to know to migrate
and start using it right away.

## Running the migration tool

To help with the process of migrating, we provide a tool called
[@connectrpc/connect-migrate](https://www.npmjs.com/package/@connectrpc/connect-migrate)
To help with the process of migrating, we provide a tool called
[@connectrpc/connect-migrate](https://www.npmjs.com/package/@connectrpc/connect-migrate)
which will take care of dependency and plugin updates as well as a few minor code
changes. So, as a first step, you will need to run the migration tool. To do so,
changes. So, as a first step, you will need to run the migration tool. To do so,
execute the following command:

`npx @connectrpc/[email protected]`

While the tool will do a lot of the dependency legwork for you, there are many
use cases in code that it does not cover. Below, we list everything that has changed in
use cases in code that it does not cover. Below, we list everything that has changed in
v2. Changes that are handled by the migration tool are noted as such.

In summary, the suggested way to migrate to Connect v2 is to first run the migration tool
Expand All @@ -30,7 +30,7 @@ Perhaps the biggest thing to be aware of is that the plugin `protoc-gen-connect-
removed in v2. Connect now relies on service descriptors generated by the Protobuf-ES v2
`protoc-gen-es` and no longer generates code itself.

So the first major part of the migration path is removing any usage of the old
So the first major part of the migration path is removing any usage of the old
`protoc-gen-connect-es` plugin. This could include:

- Removing `protoc-gen-connect-es` from `package.json`.
Expand All @@ -39,7 +39,7 @@ So the first major part of the migration path is removing any usage of the old

The next step is to upgrade any dependencies on [Protobuf-ES packages](https://github.com/bufbuild/protobuf-es?tab=readme-ov-file#packages) to use v2.

The final step is to update the [Connect packages](#packages) in your project
The final step is to update the [Connect packages](#packages) in your project
to use v2.

:white_check_mark: The `connect-migrate` tool will handle all of these changes.
Expand All @@ -53,30 +53,30 @@ example, `npx buf generate`, etc.
There are a few things to be aware with the switch to the Protobuf-ES v2 plugin
as some of the options for that plugin have changed with its v2 release:

* The `import_extension` option is now set to `none` by default, which means it doesn't
add a `.js` extension to import paths. If you use the plugin option
`import_extension=none`, you can delete it. If you require imports to have the
- The `import_extension` option is now set to `none` by default, which means it doesn't
add a `.js` extension to import paths. If you use the plugin option
`import_extension=none`, you can delete it. If you require imports to have the
`.js` extension, use `import_extension=js`.
* The `ts_nocheck` option is now off by default. If you require a `// @ts-nocheck`
- The `ts_nocheck` option is now off by default. If you require a `// @ts-nocheck`
annotation at the top of generated code, use the option `ts_nocheck=true`.

For more information, see the [Protobuf-ES v2 migration guide](https://github.com/bufbuild/protobuf-es/blob/main/MANUAL.md#migrating-from-version-1).

When generating code, you should make sure to delete any now-unused `*_connect.ts`
When generating code, you should make sure to delete any now-unused `*_connect.ts`
files. An easy way to do this is to use the `clean` option provided by the Buf CLI,
introduced in v1.36.0. See the docs [here](https://buf.build/docs/configuration/v2/buf-gen-yaml/?h=clean)
introduced in v1.36.0. See the docs [here](https://buf.build/docs/configuration/v2/buf-gen-yaml/?h=clean)
for specifying `clean` in your config files. Note that you can also specify `--clean`
to any `buf generate` CLI commands you are running.

### Import paths

Once your code is generated and the vestigial `*_connect` files are removed,
Once your code is generated and the vestigial `*_connect` files are removed,
import paths will need to be updated. This is usually an update from `*_connect` to
`*_pb`:

```diff
- import { ElizaService } from "./gen/eliza_connect.js";
+ import { ElizaService } from "./gen/eliza_pb.js";
+ import { ElizaService } from "./gen/eliza_pb.js";
```

:white_check_mark: The `connect-migrate` tool will handle this.
Expand All @@ -87,7 +87,7 @@ As mentioned, Connect now solely uses the `protoc-gen-es` plugin provided by
Protobuf-ES v2. As a result, working with generated code has changed in some
areas.

#### Creating messages
#### Creating messages

To create a new instance, you now call the function `create()` provided by
Protobuf-ES and pass the generated schema:
Expand All @@ -106,15 +106,15 @@ Protobuf-ES and pass the generated schema:
#### Service descriptors

Connect now relies on service descriptors generated by the Protobuf-ES v2
`protoc-gen-es` plugin. The v2 service descriptors aren't much different from
the service descriptors previously generated by Connect v1. The same basic
information i.e. (typed metadata) is still generated, but it's generated by
`protoc-gen-es` now, along with additional information available. For example,
v2 now provides the full descriptor, with features such as [custom options](https://github.com/bufbuild/protobuf-es/blob/v2.2.2/MANUAL.md#custom-options),
`protoc-gen-es` plugin. The v2 service descriptors aren't much different from
the service descriptors previously generated by Connect v1. The same basic
information i.e. (typed metadata) is still generated, but it's generated by
`protoc-gen-es` now, along with additional information available. For example,
v2 now provides the full descriptor, with features such as [custom options](https://github.com/bufbuild/protobuf-es/blob/v2.2.2/MANUAL.md#custom-options),
which can be very useful in interceptors.

One breaking change to be aware with service descriptors is that the access
pattern of the `MethodDescriptor` has slightly changed.
One breaking change to be aware with service descriptors is that the access
pattern of the `MethodDescriptor` has slightly changed.

Service descriptors in Connect v1 looked like this:

Expand All @@ -141,30 +141,31 @@ ElizaService.method.say.idempotency; // MethodOptions_IdempotencyLevel.NoSideEf
```

Note that:
* instead of the plural form `methods`, it now uses the singular `method`.
* the property `kind` for `MethodKind` has been renamed to `methodKind` and it now

- instead of the plural form `methods`, it now uses the singular `method`.
- the property `kind` for `MethodKind` has been renamed to `methodKind` and it now
returns a string.
* the enum type of the `idempotency` property has slightly changed.
- the enum type of the `idempotency` property has slightly changed.

Other than the above, the generated properties remain largely unchanged and
request and responses do not need any updates when initializers are used or
Other than the above, the generated properties remain largely unchanged and
request and responses do not need any updates when initializers are used or
dot notation is used. However, a few noteworthy changes to be aware of:

* The `toPlainMessage` function and the `PlainMessage<T>` type are no longer
necessary. If you create a `proto3` message with `create(UserSchema)`, the
returned object is already a plain object. You can replace the
`PlainMessage<User>` types with `User`. The only difference is that `User` has
- The `toPlainMessage` function and the `PlainMessage<T>` type are no longer
necessary. If you create a `proto3` message with `create(UserSchema)`, the
returned object is already a plain object. You can replace the
`PlainMessage<User>` types with `User`. The only difference is that `User` has
a property `$typeName`, which is a simple string with the full name of
the message like `"example.User"`. This property makes sure you don't pass the
the message like `"example.User"`. This property makes sure you don't pass the
wrong message to a function by accident.
* The `PartialMessage` type has been mostly replaced by `MessageInitShape`, which
- The `PartialMessage` type has been mostly replaced by `MessageInitShape`, which
extracts the init type from a message descriptor.
* A message field using [`google.protobuf.Struct`](https://github.com/bufbuild/protobuf-es/blob/main/MANUAL.md#googleprotobufstruct)
- A message field using [`google.protobuf.Struct`](https://github.com/bufbuild/protobuf-es/blob/main/MANUAL.md#googleprotobufstruct)
is now generated as a more-convenient `JsonObject`.
* `proto2` fields with default values are no longer generated as optional
- `proto2` fields with default values are no longer generated as optional
properties.
* All well-known types and helpers have been moved to an export under
`@bufbuild/protobuf/wkt`. For example, when converting a `google.protobuf.Timestamp`
- All well-known types and helpers have been moved to an export under
`@bufbuild/protobuf/wkt`. For example, when converting a `google.protobuf.Timestamp`
to an ECMAScript `Date` object, it is no longer possible via a method and must
be done via helpers imported from this path.

Expand All @@ -173,21 +174,21 @@ as well as the [Protobuf-ES v2 migration guide](https://github.com/bufbuild/prot

### Other breaking changes

* Promise clients are now the default and the previously-deprecated
- Promise clients are now the default and the previously-deprecated
`createPromiseClient` has been removed. Any callsites using `createPromiseClient`
should be updated to use `createClient`.

:white_check_mark: The `connect-migrate` tool will handle this.

* The gRPC Transport now requires HTTP/2. If you are using `createGrpcTransport`
- The gRPC Transport now requires HTTP/2. If you are using `createGrpcTransport`
and specifying an `httpVersion`, it will fail compilation. Remove the
`httpVersion` property to use the default of HTTP/2.

Note that if you were relying on HTTP/1.1 as part of your gRPC strategy, this
may require bigger architectural changes, but the hope is that this is not a
common problem.

* Previously, Connect allowed request objects with matching shapes to be passed
- Previously, Connect allowed request objects with matching shapes to be passed
to API calls interchangeably as long as the passed object was a superset of the
target type. For example, given the following proto definitions:

Expand Down Expand Up @@ -217,7 +218,7 @@ as well as the [Protobuf-ES v2 migration guide](https://github.com/bufbuild/prot
This was an unintended bug and not a feature. In Connect v2, only the specified
target type will pass compilation.

- We have removed the `credentials` option from transports as well as the `init`
* We have removed the `credentials` option from transports as well as the `init`
option in interceptors. These two options were used to customize `fetch` routines.
Users should now rely on the `fetch` option in transports as a way to perform
these customizations. For example:
Expand All @@ -233,7 +234,7 @@ as well as the [Protobuf-ES v2 migration guide](https://github.com/bufbuild/prot
Connect GET request in server-side interceptors, the property `requestMethod: string`
has been added to intercepted requests. This property is symmetrical to `HandlerContext.requestMethod`.

* Errors details are now a pair of desc and init values. In Connect v1, error
- Errors details are now a pair of desc and init values. In Connect v1, error
details were specified as message instances. In v2, error
details are now an object that specifies both a schema and initialization
object which are both passed to the `create` function of Protobuf-ES. For example:
Expand Down Expand Up @@ -268,7 +269,7 @@ as well as the [Protobuf-ES v2 migration guide](https://github.com/bufbuild/prot
);
```

* `MethodDescriptor` is now self-sufficient. In v1, method descriptors always
- `MethodDescriptor` is now self-sufficient. In v1, method descriptors always
had to be used alongside the service descriptors. In v2, they can now be used
standalone. This means that all callsites that previously passed a service
and method descriptor should now just pass the method descriptor.
Expand All @@ -282,12 +283,12 @@ as well as the [Protobuf-ES v2 migration guide](https://github.com/bufbuild/prot
}
```

* Interceptors for streaming RPCs now use appropriate stream types. In
- Interceptors for streaming RPCs now use appropriate stream types. In
v1, the server used more exact types in interceptors, for example `UnaryRequest`
for server-streaming rpcs while the client always used streaming variants.
This was unintended behavior and has been fixed in v2. Now all streaming RPCs
use the `StreamRequest` and `StreamResponse` types on the server as well.

* Node 16 is no longer supported. Connect v2 now supports Node versions **18.14.1** and up.
- Node 16 is no longer supported. Connect v2 now supports Node versions **18.14.1** and up.

* Connect v2 now requires at least TypeScript **v4.9.5**.
- Connect v2 now requires at least TypeScript **v4.9.5**.

0 comments on commit 29bf18b

Please sign in to comment.