0 Fork 0

Files

T

Johan Brandhorst-Satzkorn b1d6a1da9a Switch to buf for protobuf generation (#1944 )

* Install buf with go install

This reduces the impact of using buf on our dependency
closure, which was significant. It also avoids potential
issues with building buf given our own internal dependency
constraints. This has caused issues (including crashes!)
in the past.

See https://github.com/cockroachdb/cockroach/issues/67216#issuecomment-874176186
for more discussion on using tool dependencies generally, and
https://github.com/bufbuild/buf/issues/52
for an example of where this sort of thing caused an issue for a user.

* Upgrade buf version

We should migrate to v1 sooner rather than later, as it has some
breaking changes from v0.

* Change buf lint/breaking commands

These commands were moved up one level for v1

* Migrate to buf.yaml to v1

* Remove unused imports

These were uncovered by using "buf lint".

* Use buf v1.3.1

* Depend on googleapis and grpc-gateway via BSR

* Switch to buf for proto generation

* Remove third party dependency

* Remove unused tools and scripts

* Move local protos up one level

* Temporarily don't fail on breaking changes

* Generate CI config

* Fix generation of controller.json

* Replace use of deprecated flag

* Remove unused import, regenerate files

* Remove temporary skipping over breaking check

2022-04-04 13:55:42 -04:00

3.5 KiB

Raw Blame History

Extending Boundary: adding additional field to an existing API

A very high level list of things to-do when you're adding an additional field to an existing API and corresponding CLI command.

Add the new field to a repository

Once you've figured out that you need an additional field in Boundary's domain model, then you need to build in support for your new field from the bottom up starting with a repository's database schema.

Make schema changes:
- Define the new column and provide for the migration of existing data
  - Create a new migration under internal/db/schema/migrations/oss/postgres
Add the new field to the storage protobuf
- storage protobufs are under: internal/proto/controller/storage
- Define a gorm tag for the new field via @gotags (@inject_tag has been deprecated)
- Define a custom_options.v1.mask_mapping for the field which maps the storage this field to the API that field (yes, it's the opposite of how it's defined for the API protobuf)
- Run make proto after modifying storage protobuf
Extend the existing repository function for Updating the resource to incorporate the new field. This could/may entail defining new options for the Update function.
Check the repository's Create function for the resource, since you may need to incorporate the new field here as well.

Add new fields to the API/SDK resource protobufs

Now that the repository supports the new field, you can move on to adding this new field to Boundary's API layer and the generated SDK. The first step in the process is to add it to the API/SDK protobufs.

API protobufs are under: internal/proto/controller/api/resources
Define a custom_options.v1.mask_mapping tag for the field which maps the API this field to the storage that field (yes, it's the opposite of how it's defined for a storage protobuf)
Define a custom_options.v1.generate_sdk_option tag for the SDK
Define a data classification/filter tag for the field via @gotags or the encrypt.Taggable interface which specifies how sensitive/secret/public data will be handled for the API's audit events. Please write unit tests to verify the audit event is properly "redacted" (see the unit tests of TestAuthenticate_Tags and TestAuthenticate for examples).
Run make proto and make api after modifying the API/SDK protobufs

Update the API handler service

Now that the API protobufs have been updated, you can move on to adding this new field to the API service handler.

Service handlers are under: internal/servers/controller/handlers
Incorporate the new field into the handlers updateInRepo func. You'll need to incorporate the inbound protobuf's field with the repository's update function. This could include adding repository options to the Update function call or passing the new field as a parameter to the call. This work will be based on how you extended the repository in the previous steps.
Incorporate the new field into the handler's ToProto function.

Update the CLI's command for updating the resource

At this point, the new field is available via Boundary's API. All that's left is to incorporate it into Boundary's CLI for the appropriate command.

CLI commands are under: internal/cmd/commands
Incorporate the new fields to the command's funcs.go. Just a suggestion here: you may want to define a const for the new field name and reuse it everywhere it's required (which is several places)
Run make cli and make install, before attempting to test cli changes

3.5 KiB Raw Blame History