feat: support start time parameter on read changes (#158)

* fix : change default retry policy

* feat-support-start_time-parameter-on-read_changes

* Update Changelog

- Add default retry change to changelog
- Add PR reference to new changelog entries

* chore: update changelog adding credit on retry policy change

---------

Co-authored-by: Ovindu Atukorala <[email protected]>

Author: ryanpq

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [Unreleased](https://github.com/openfga/go-sdk/compare/v0.6.3...HEAD)
+
+- feat: add support for `start_time` parameter in `ReadChanges` endpoint (#158)
+- feat: change default retry policy to `3` from `15` - thanks @ovindu-a (#158)
+
 ## v0.6.3
 
 ### [0.6.3](https://github.com/openfga/go-sdk/compare/v0.6.2...v0.6.3) (2024-10-22)

README.md

@@ -102,7 +102,7 @@ to update `go.mod` and `go.sum` if you are using them.
 
 We strongly recommend you initialize the `OpenFgaClient` only once and then re-use it throughout your app, otherwise you will incur the cost of having to re-initialize multiple times or at every request, the cost of reduced connection pooling and re-use, and would be particularly costly in the client credentials flow, as that flow will be preformed on every request.
 
-> The `openfgaClient` will by default retry API requests up to 15 times on 429 and 5xx errors.
+> The `openfgaClient` will by default retry API requests up to 3 times on 429 and 5xx errors.
 
 #### No Credentials
 
@@ -439,6 +439,7 @@ options := ClientReadChangesOptions{
     ContinuationToken: openfga.PtrString("eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ=="),
     // You can rely on the store id set in the configuration or override it for this specific request
     StoreId: openfga.PtrString("01FQH7V8BEG3GPQW93KTRFR8JB"), 
+    StartTime: openfga.PtrString("2022-01-01T00:00:00Z"),
 }
 data, err := fgaClient.ReadChanges(context.Background()).Body(body).Options(options).Execute()
 
@@ -899,7 +900,7 @@ data, err := fgaClient.WriteAssertions(context.Background()).
 
 ### Retries
 
-If a network request fails with a 429 or 5xx error from the server, the SDK will automatically retry the request up to 15 times with a minimum wait time of 100 milliseconds between each attempt.
+If a network request fails with a 429 or 5xx error from the server, the SDK will automatically retry the request up to 3 times with a minimum wait time of 100 milliseconds between each attempt.
 
 To customize this behavior, create an `openfga.RetryParams` struct and assign values to the `MaxRetry` and `MinWaitInMs` fields. `MaxRetry` determines the maximum number of retries (up to 15), while `MinWaitInMs` sets the minimum wait time between retries in milliseconds.
 
@@ -959,6 +960,7 @@ Class | Method | HTTP request | Description
  - [Any](docs/Any.md)
  - [Assertion](docs/Assertion.md)
  - [AssertionTupleKey](docs/AssertionTupleKey.md)
+ - [AuthErrorCode](docs/AuthErrorCode.md)
  - [AuthorizationModel](docs/AuthorizationModel.md)
  - [CheckRequest](docs/CheckRequest.md)
  - [CheckRequestTupleKey](docs/CheckRequestTupleKey.md)
@@ -977,6 +979,7 @@ Class | Method | HTTP request | Description
  - [ExpandRequestTupleKey](docs/ExpandRequestTupleKey.md)
  - [ExpandResponse](docs/ExpandResponse.md)
  - [FgaObject](docs/FgaObject.md)
+ - [ForbiddenResponse](docs/ForbiddenResponse.md)
  - [GetStoreResponse](docs/GetStoreResponse.md)
  - [InternalErrorCode](docs/InternalErrorCode.md)
  - [InternalErrorMessageResponse](docs/InternalErrorMessageResponse.md)

api_open_fga.go

@@ -40,6 +40,7 @@ type OpenFgaApi interface {
 	A `contextual_tuples` object may also be included in the body of the request. This object contains one field `tuple_keys`, which is an array of tuple keys. Each of these tuples may have an associated `condition`.
 	You may also provide an `authorization_model_id` in the body. This will be used to assert that the input `tuple_key` is valid for the model specified. If not specified, the assertion will be made against the latest authorization model ID. It is strongly recommended to specify authorization model id for better performance.
 	You may also provide a `context` object that will be used to evaluate the conditioned tuples in the system. It is strongly recommended to provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.
+	By default, the Check API caches results for a short time to optimize performance. You may specify a value of `HIGHER_CONSISTENCY` for the optional `consistency` parameter in the body to inform the server that higher conisistency is preferred at the expense of increased latency. Consideration should be given to the increased latency if requesting higher consistency.
 	The response will return whether the relationship exists in the field `allowed`.
 
 	Some exceptions apply, but in general, if a Check API responds with `{allowed: true}`, then you can expect the equivalent ListObjects query to return the object, and viceversa.
@@ -139,6 +140,18 @@ type OpenFgaApi interface {
 	}
 	```
 	will return `{ "allowed": true }`, even though a specific user of the userset `group:finance#member` does not have the `reader` relationship with the given object.
+	### Requesting higher consistency
+	By default, the Check API caches results for a short time to optimize performance. You may request higher consistency to inform the server that higher consistency should be preferred at the expense of increased latency. Care should be taken when requesting higher consistency due to the increased latency.
+	```json
+	{
+	  "tuple_key": {
+	     "user": "group:finance#member",
+	     "relation": "reader",
+	     "object": "document:2021-budget"
+	  },
+	  "consistency": "HIGHER_CONSISTENCY"
+	}
+	```
 
 		 * @param ctx _context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
 		 * @param storeId
@@ -265,6 +278,7 @@ type OpenFgaApi interface {
 	An `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID will be used. It is strongly recommended to specify authorization model id for better performance.
 	You may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.
 	You may also provide a `context` object that will be used to evaluate the conditioned tuples in the system. It is strongly recommended to provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.
+	By default, the Check API caches results for a short time to optimize performance. You may specify a value of `HIGHER_CONSISTENCY` for the optional `consistency` parameter in the body to inform the server that higher conisistency is preferred at the expense of increased latency. Consideration should be given to the increased latency if requesting higher consistency.
 	The response will contain the related objects in an array in the "objects" field of the response and they will be strings in the object format `<type>:<id>` (e.g. "document:roadmap").
 	The number of objects in the response array will be limited by the execution timeout specified in the flag OPENFGA_LIST_OBJECTS_DEADLINE and by the upper bound specified in the flag OPENFGA_LIST_OBJECTS_MAX_RESULTS, whichever is hit first.
 	The objects given will not be sorted, and therefore two identical calls can give a given different set of objects.
@@ -304,7 +318,7 @@ type OpenFgaApi interface {
 	You may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.
 	You may also provide a `context` object that will be used to evaluate the conditioned tuples in the system. It is strongly recommended to provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.
 	The response will contain the related users in an array in the "users" field of the response. These results may include specific objects, usersets
-	or type-bound public access. Each of these types of results is encoded in its own type and not represented as a string.In cases where a type-bound public acces result is returned (e.g. `user:*`), it cannot be inferred that all subjects
+	or type-bound public access. Each of these types of results is encoded in its own type and not represented as a string.In cases where a type-bound public access result is returned (e.g. `user:*`), it cannot be inferred that all subjects
 	of that type have a relation to the object; it is possible that negations exist and checks should still be queried
 	on individual subjects to ensure access to that document.The number of users in the response array will be limited by the execution timeout specified in the flag OPENFGA_LIST_USERS_DEADLINE and by the upper bound specified in the flag OPENFGA_LIST_USERS_MAX_RESULTS, whichever is hit first.
 	The returned users will not be sorted, and therefore two identical calls may yield different sets of users.
@@ -435,7 +449,7 @@ type OpenFgaApi interface {
 
 	/*
 	 * ReadAssertions Read assertions for an authorization model ID
-	 * The ReadAssertions API will return, for a given authorization model id, all the assertions stored for it. An assertion is an object that contains a tuple key, and the expectation of whether a call to the Check API of that tuple key will return true or false.
+	 * The ReadAssertions API will return, for a given authorization model id, all the assertions stored for it.
 	 * @param ctx _context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
 	 * @param storeId
 	 * @param authorizationModelId
@@ -629,7 +643,7 @@ type OpenFgaApi interface {
 
 	/*
 	 * WriteAssertions Upsert assertions for an authorization model ID
-	 * The WriteAssertions API will upsert new assertions for an authorization model id, or overwrite the existing ones. An assertion is an object that contains a tuple key, and the expectation of whether a call to the Check API of that tuple key will return true or false.
+	 * The WriteAssertions API will upsert new assertions for an authorization model id, or overwrite the existing ones. An assertion is an object that contains a tuple key, the expectation of whether a call to the Check API of that tuple key will return true or false, and optionally a list of contextual tuples.
 	 * @param ctx _context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
 	 * @param storeId
 	 * @param authorizationModelId
@@ -728,6 +742,7 @@ To arrive at a result, the API uses: an authorization model, explicit tuples wri
 A `contextual_tuples` object may also be included in the body of the request. This object contains one field `tuple_keys`, which is an array of tuple keys. Each of these tuples may have an associated `condition`.
 You may also provide an `authorization_model_id` in the body. This will be used to assert that the input `tuple_key` is valid for the model specified. If not specified, the assertion will be made against the latest authorization model ID. It is strongly recommended to specify authorization model id for better performance.
 You may also provide a `context` object that will be used to evaluate the conditioned tuples in the system. It is strongly recommended to provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.
+By default, the Check API caches results for a short time to optimize performance. You may specify a value of `HIGHER_CONSISTENCY` for the optional `consistency` parameter in the body to inform the server that higher conisistency is preferred at the expense of increased latency. Consideration should be given to the increased latency if requesting higher consistency.
 The response will return whether the relationship exists in the field `allowed`.
 
 Some exceptions apply, but in general, if a Check API responds with `{allowed: true}`, then you can expect the equivalent ListObjects query to return the object, and viceversa.
@@ -845,6 +860,20 @@ the following query
 
 ```
 will return `{ "allowed": true }`, even though a specific user of the userset `group:finance#member` does not have the `reader` relationship with the given object.
+### Requesting higher consistency
+By default, the Check API caches results for a short time to optimize performance. You may request higher consistency to inform the server that higher consistency should be preferred at the expense of increased latency. Care should be taken when requesting higher consistency due to the increased latency.
+```json
+
+	{
+	  "tuple_key": {
+	     "user": "group:finance#member",
+	     "relation": "reader",
+	     "object": "document:2021-budget"
+	  },
+	  "consistency": "HIGHER_CONSISTENCY"
+	}
+
+```
 
   - @param ctx _context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
   - @param storeId
@@ -2290,6 +2319,7 @@ func (r ApiListObjectsRequest) Execute() (ListObjectsResponse, *_nethttp.Respons
 An `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID will be used. It is strongly recommended to specify authorization model id for better performance.
 You may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.
 You may also provide a `context` object that will be used to evaluate the conditioned tuples in the system. It is strongly recommended to provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.
+By default, the Check API caches results for a short time to optimize performance. You may specify a value of `HIGHER_CONSISTENCY` for the optional `consistency` parameter in the body to inform the server that higher conisistency is preferred at the expense of increased latency. Consideration should be given to the increased latency if requesting higher consistency.
 The response will contain the related objects in an array in the "objects" field of the response and they will be strings in the object format `<type>:<id>` (e.g. "document:roadmap").
 The number of objects in the response array will be limited by the execution timeout specified in the flag OPENFGA_LIST_OBJECTS_DEADLINE and by the upper bound specified in the flag OPENFGA_LIST_OBJECTS_MAX_RESULTS, whichever is hit first.
 The objects given will not be sorted, and therefore two identical calls can give a given different set of objects.
@@ -2867,7 +2897,7 @@ An `authorization_model_id` may be specified in the body. If it is not specified
 You may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.
 You may also provide a `context` object that will be used to evaluate the conditioned tuples in the system. It is strongly recommended to provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.
 The response will contain the related users in an array in the "users" field of the response. These results may include specific objects, usersets
-or type-bound public access. Each of these types of results is encoded in its own type and not represented as a string.In cases where a type-bound public acces result is returned (e.g. `user:*`), it cannot be inferred that all subjects
+or type-bound public access. Each of these types of results is encoded in its own type and not represented as a string.In cases where a type-bound public access result is returned (e.g. `user:*`), it cannot be inferred that all subjects
 of that type have a relation to the object; it is possible that negations exist and checks should still be queried
 on individual subjects to ensure access to that document.The number of users in the response array will be limited by the execution timeout specified in the flag OPENFGA_LIST_USERS_DEADLINE and by the upper bound specified in the flag OPENFGA_LIST_USERS_MAX_RESULTS, whichever is hit first.
 The returned users will not be sorted, and therefore two identical calls may yield different sets of users.
@@ -3550,7 +3580,7 @@ func (r ApiReadAssertionsRequest) Execute() (ReadAssertionsResponse, *_nethttp.R
 
 /*
  * ReadAssertions Read assertions for an authorization model ID
- * The ReadAssertions API will return, for a given authorization model id, all the assertions stored for it. An assertion is an object that contains a tuple key, and the expectation of whether a call to the Check API of that tuple key will return true or false.
+ * The ReadAssertions API will return, for a given authorization model id, all the assertions stored for it.
  * @param ctx _context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
  * @param storeId
  * @param authorizationModelId
@@ -4489,6 +4519,7 @@ type ApiReadChangesRequest struct {
 	type_             *string
 	pageSize          *int32
 	continuationToken *string
+	startTime         *time.Time
 }
 
 func (r ApiReadChangesRequest) Type_(type_ string) ApiReadChangesRequest {
@@ -4503,6 +4534,10 @@ func (r ApiReadChangesRequest) ContinuationToken(continuationToken string) ApiRe
 	r.continuationToken = &continuationToken
 	return r
 }
+func (r ApiReadChangesRequest) StartTime(startTime time.Time) ApiReadChangesRequest {
+	r.startTime = &startTime
+	return r
+}
 
 func (r ApiReadChangesRequest) Execute() (ReadChangesResponse, *_nethttp.Response, error) {
 	return r.ApiService.ReadChangesExecute(r)
@@ -4571,6 +4606,9 @@ func (a *OpenFgaApiService) ReadChangesExecute(r ApiReadChangesRequest) (ReadCha
 		if r.continuationToken != nil {
 			localVarQueryParams.Add("continuation_token", parameterToString(*r.continuationToken, ""))
 		}
+		if r.startTime != nil {
+			localVarQueryParams.Add("start_time", parameterToString(*r.startTime, ""))
+		}
 		// to determine the Content-Type header
 		localVarHTTPContentTypes := []string{}
 
@@ -5136,7 +5174,7 @@ func (r ApiWriteAssertionsRequest) Execute() (*_nethttp.Response, error) {
 
 /*
  * WriteAssertions Upsert assertions for an authorization model ID
- * The WriteAssertions API will upsert new assertions for an authorization model id, or overwrite the existing ones. An assertion is an object that contains a tuple key, and the expectation of whether a call to the Check API of that tuple key will return true or false.
+ * The WriteAssertions API will upsert new assertions for an authorization model id, or overwrite the existing ones. An assertion is an object that contains a tuple key, the expectation of whether a call to the Check API of that tuple key will return true or false, and optionally a list of contextual tuples.
  * @param ctx _context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
  * @param storeId
  * @param authorizationModelId

api_open_fga_test.go

@@ -18,6 +18,7 @@ import (
 	"fmt"
 	"net/http"
 	"testing"
+	"time"
 
 	"github.com/jarcoal/httpmock"
 	"github.com/openfga/go-sdk/credentials"
@@ -794,9 +795,11 @@ func TestOpenFgaApi(t *testing.T) {
 				return resp, nil
 			},
 		)
+		startTime, err := time.Parse(time.RFC3339, "2022-01-01T00:00:00Z")
 		got, response, err := apiClient.OpenFgaApi.ReadChanges(context.Background(), "01GXSB9YR785C4FYS3C0RTG7B2").
 			Type_("repo").
 			PageSize(25).
+			StartTime(startTime).
 			ContinuationToken("eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==").
 			Execute()
 		if err != nil {