Migrating to v2 of the Go SDK

The v2 release of the Go SDK represents a significant rethinking of the developer experience. As such there are a few changes to be aware of, both breaking and non-breaking.

Updating your imports

Run go get github.com/osohq/go-oso-cloud/v2 to install v2 of the SDK.

In each place you import go-oso-cloud, add /v2 to the module import path:

Structs

The Name field on the Fact struct has been renamed Predicate.

The Instance struct has been replaced with Value. Unlike Instance, it is invalid for a Value to have an zero-valued ID or Type field.

To distinguish between functions that accept concrete facts and those that accept patterns (such as Get or Delete), the type FactPattern has been introduced. In v1, these were both represented by Fact.

There are also helper functions for constructing Fact, FactPattern, and Value instances in a more ergonomic way:

The migration instructions for each API function contain examples of how to use these helper functions.

Centralized Authorization Data API

The Centralized Authorization Data API has been condensed from 6 methods to 4: Insert, Delete, Get, and Batch.

Tell to Insert

To migrate from Tell to Insert, replace Instances with Values, and wrap the arguments in a call to oso.NewFact:

Delete

To migrate from the previous Delete API, replace Instances with Values, and wrap the arguments in a call to oso.NewFactPattern:

Additionally, the new Delete function supports deleting all facts matching a pattern:

Get

To migrate from the previous Get API, replace Instances with Values and wrap them in a call to oso.NewFactPattern:

If you used an oso.Instance with a Type but no ID to fetch facts with arguments of a particular type (but no particular ID), use oso.ValueOfType instead:

If you used the zero-valued oso.Instance as a wildcard, replace it with nil:

Additionally, it is no longer possible to use a wildcard in the fact predicate in calls to Get.

Bulk to Batch or Delete

To migrate from Bulk to Batch, call OsoClient.Batch, call tx.Delete once for each deletion pattern in the payload, and call tx.Insert once for each fact to insert. For deletes, you will need to convert your Facts to FactPatterns- use the oso.NewFactPattern helper for this. As with Insert and Delete, be sure to replace Instances with Values in your facts, too.

Additionally, the Delete API now handles deleting many facts matching a pattern at once. If you were previously using the Bulk API just to delete many facts at once, you can now use the Delete API directly:

If you used an oso.Instance with a Type but no ID to fetch facts with arguments of a particular type (but no particular ID), use oso.ValueOfType instead:

If you used the zero-valued oso.Instance as a wildcard, replace it with nil:

The migration notes about wildcards apply regardless of whether you use OsoClient.Batch or OsoClient.Delete.

BulkTell to Batch

To migrate from BulkTell to Batch, call OsoClient.Batch and call tx.Insert for each fact in the payload. As with Insert, be sure to replace Instances with Values in your facts, too.

As above, you may find it easier to use the NewFact and NewValue helper functions than to construct Fact and Value structs by hand.

BulkDelete to Batch

To migrate from BulkDelete to Batch, call OsoClient.Batch and call tx.Delete for each fact in the payload. You will need to convert your Facts to FactPatterns- use the oso.NewFactPattern helper for this. As with Delete, be sure to replace Instances with Values in your facts, too.

Additionally, the new Batch function supports deleting all facts matching a pattern:

Query API

We've replaced the Query API with a more powerful and flexible QueryBuilder API with a fluent interface. We've also dropped the AuthorizeResources APIs in favor of the QueryBuilder.

Query to BuildQuery

We recommend taking a look at the reference docs for the new QueryBuilder API. It's more flexible and expressive than the old Query API, and it may let you simplify your application code.

But if you just want to migrate your existing queries as-is, here's how.

Queries with no wildcards

Typically, a query with no wildcards is used to check for the existence of a derived rule or fact.

With the old Query API:

With the new QueryBuilder API:

Queries with type-constrained wildcards

The old Query API let you query for all the results of a particular type by using an oso.Instance with a Type but no ID. To migrate these, replace type-constrained wildcards with a oso.TypedVar(myType) variable.

With the old Query API:

With the new QueryBuilder API:

If you have several type-constrained wildcards in a single query, you may prefer to get results as a map:

Queries with unconstrained wildcards

The old Query API let you use a zero-valued Instance or nil to query for many types of results at once:

In the new QueryBuilder API, this is no longer possible.

Instead, make one request for each concrete type:

Handling wildcards in results

The old Query API sometimes returned results containing a zero-valued oso.Instance, indicating that any value could apply at a particular position. For example:

The new QueryBuilder API will instead return the string "*" to mean the same thing, just like the Check APIs-

Context facts

You can pass context facts into the QueryBuilder by calling the WithContextFacts method before you call Evaluate.

AuthorizeResources to BuildQuery

The AuthorizeResources API was used to authorize many resources for a single actor and action.

With the new QueryBuilder API:

If you are using AuthorizeResourcesWithContext to include context facts, check out the WithContextFacts QueryBuilder function.