Skip to content

feat(docs): document SDK.IsHealthy and link unresolved type references #311

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marythought merged 4 commits into from
Apr 30, 2026
Merged

feat(docs): document SDK.IsHealthy and link unresolved type references #311

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
77b499c
feat(docs): document SDK.IsHealthy reachability probe
marythought Apr 29, 2026
b48e348
fix(docs): link unresolved type references in SDK reference tables
marythought Apr 29, 2026
bfe33b2
fix(docs): link ActionsList type and route obligations link to SDK page
marythought Apr 29, 2026
20a7446
docs: clarify IsHealthy example error handling
marythought Apr 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 17 additions & 5 deletions docs/sdks/authorization.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -602,7 +602,7 @@ await platform.v2.authorization.getDecision({ ... })
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `entityIdentifier` | [`EntityIdentifier`](#entityidentifier) | Yes | The entity requesting access. Use [helpers](#entityidentifier) like `ForEmail(...)` (Go) or `EntityIdentifiers.forEmail(...)` (Java/JS). |
| `action` | `Action` | Yes | The action being performed (e.g., `decrypt`, `read`). |
| `action` | [`Action`](/sdks/policy#action) | Yes | The action being performed (e.g., `decrypt`, `read`). |
| `resource` | [`Resource`](#resource) | Yes | The resource being accessed. Use [helpers](#resource) like `ForAttributeValues(...)` (Go) or `Resources.forAttributeValues(...)` (Java/JS). |

**Example**
Expand Down Expand Up @@ -789,7 +789,7 @@ if (decision?.decision === Decision.PERMIT) {

**Returns**

A [ResourceDecision](#resourcedecision) with a [Decision](#decision) (permit/deny) and any required [obligations](/components/policy/obligations) the consuming application must enforce.
A [ResourceDecision](#resourcedecision) with a [Decision](#decision) (permit/deny) and any required [obligations](/sdks/obligations) the consuming application must enforce.

---

Expand Down Expand Up @@ -827,14 +827,16 @@ await platform.v2.authorization.getDecisionBulk({ ... })

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `decisionRequests` | `[]GetDecisionMultiResourceRequest` | Yes | Each entry contains an entity, action, and one or more resources to evaluate. |
| `decisionRequests` | [`[]GetDecisionMultiResourceRequest`](#getdecisionmultiresourcerequest) | Yes | Each entry contains an entity, action, and one or more resources to evaluate. |

### GetDecisionMultiResourceRequest

Each `GetDecisionMultiResourceRequest` contains:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `entityIdentifier` | [`EntityIdentifier`](#entityidentifier) | Yes | The entity requesting access. |
| `action` | `Action` | Yes | The action being performed. |
| `action` | [`Action`](/sdks/policy#action) | Yes | The action being performed. |
| `resources` | [`[]Resource`](#resource) | Yes | Resources to evaluate, each with an `ephemeralId` for correlation. |

**Example**
Expand Down Expand Up @@ -1114,7 +1116,7 @@ Returned by [GetEntitlements](#getentitlements). One per entity, mapping attribu
| Field | Type | Description |
|-------|------|-------------|
| `ephemeralId` | `string` | Correlates with the entity in the request. |
| `actionsPerAttributeValueFqn` | `map<string, ActionsList>` | Keys are attribute value FQNs. Values are lists of [actions](/sdks/policy#action) the entity can perform on data carrying that attribute value. |
| `actionsPerAttributeValueFqn` | [`map<string, ActionsList>`](#actionslist) | Keys are attribute value FQNs. Values are lists of [actions](/sdks/policy#action) the entity can perform on data carrying that attribute value. |

```go
for _, e := range resp.GetEntitlements() {
Expand All @@ -1132,6 +1134,16 @@ for (const e of resp.entitlements) {
}
```

### ActionsList

A thin wrapper around a list of [`Action`](/sdks/policy#action) used as the value type in `EntityEntitlements.actionsPerAttributeValueFqn`. The wrapper exists because protobuf maps cannot have repeated value types directly.

| Field | Type | Description |
|-------|------|-------------|
| `actions` | [`[]Action`](/sdks/policy#action) | The actions the entity can perform on data carrying the keyed attribute value. |

In Go, reach the underlying slice with `actionsList.GetActions()`. In Java, `actionsList.getActionsList()`. In JavaScript, the value is surfaced directly as an `Actions` object whose `.actions` field is the array.

### GetDecisionMultiResourceResponse

Returned by [GetDecisionBulk](#getdecisionbulk). One per entity+action combination in the request.
Expand Down
32 changes: 32 additions & 0 deletions docs/sdks/platform-client.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ title: Overview
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import JsAuthNote from '../../code_samples/js_auth_note.mdx'
import SdkVersion from '@site/src/components/SdkVersion';

# Overview

Expand Down Expand Up @@ -90,6 +91,37 @@ const platform = new PlatformClient({ ...auth, platformUrl: 'http://localhost:80
</TabItem>
</Tabs>

## Health checks

`IsHealthy` reports whether the platform is reachable and serving requests. Use it in readiness probes, smoke tests, or to gate startup logic on platform availability.

<SdkVersion language="go" version="0.18.0" source="opentdf" />

```go
healthy, err := client.IsHealthy(ctx)
if err != nil {
// err is sdk.ErrHealthCheckUnsupported (IPC mode), or wraps
// sdk.ErrPlatformUnreachable on transport failure or ctx cancellation
log.Printf("health check failed: %v", err)
return
}
Comment thread
marythought marked this conversation as resolved.
if !healthy {
// reachable, but reports NOT_SERVING or UNKNOWN
log.Println("platform is not ready")
}
```

The check honors the supplied `context.Context` for deadlines and cancellation, and propagates OTEL tracing when `otelconnect.NewInterceptor` is registered via `WithExtraClientOptions`.

### Return values

| Result | Meaning |
|---|---|
| `(true, nil)` | Platform reports `SERVING`. |
| `(false, nil)` | Platform is reachable but reports `NOT_SERVING` or `UNKNOWN`. |
| `(false, err)` | Transport failure or context cancellation. The error wraps `sdk.ErrPlatformUnreachable`. |
| `(false, sdk.ErrHealthCheckUnsupported)` | The SDK is configured in IPC mode, which does not support health checks. |
Comment thread
marythought marked this conversation as resolved.

## Response Objects

All platform API calls return protobuf response objects. The way you access fields differs by language: **Go** uses generated getter methods prefixed with `Get`, **Java** uses standard getters, and **JavaScript** uses direct property access with optional chaining.
Expand Down
4 changes: 2 additions & 2 deletions docs/sdks/policy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1616,7 +1616,7 @@ await platform.v1.subjectMapping.updateSubjectConditionSet({ ... })
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` (UUID) | Yes | The subject condition set ID to update. |
| `subjectSets` | `[]SubjectSet` | No | Replaces the entire condition tree. Omit to update metadata only. |
| `subjectSets` | [`[]SubjectSet`](#subjectset) | No | Replaces the entire condition tree. Omit to update metadata only. |
| `metadata` | [`Metadata`](#metadata) | No | Optional [labels](#metadata). |
| `metadataUpdateBehavior` | `string` | No | `METADATA_UPDATE_ENUM_REPLACE` or `METADATA_UPDATE_ENUM_EXTEND` (default). |

Expand Down Expand Up @@ -2345,7 +2345,7 @@ await platform.v1.subjectMapping.matchSubjectMappings({ ... })

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `subjectProperties` | `[]SubjectProperty` | Yes | Key-value pairs from an entity's claims. Each has `externalSelectorValue` (the claim path, e.g., `.clientId`) and `externalValue` (the claim value). |
| `subjectProperties` | [`[]SubjectProperty`](#subjectproperty) | Yes | Key-value pairs from an entity's claims. Each has `externalSelectorValue` (the claim path, e.g., `.clientId`) and `externalValue` (the claim value). |

**Example**

Expand Down
55 changes: 41 additions & 14 deletions docs/sdks/tdf.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -628,7 +628,7 @@ func (s SDK) PrepareBulkDecrypt(ctx context.Context, opts ...BulkDecryptOption)
|-------|------|-------------|
| `Reader` | `io.ReadSeeker` | Source of the encrypted TDF. |
| `Writer` | `io.Writer` | Destination for the decrypted plaintext. |
| `TriggeredObligations` | `RequiredObligations` | Populated after rewrap with obligation FQNs required by this TDF. See [Obligations in bulk decrypt](#obligations-in-bulk-decrypt). |
| `TriggeredObligations` | [`RequiredObligations`](#requiredobligations) | Populated after rewrap with obligation FQNs required by this TDF. See [Obligations in bulk decrypt](#obligations-in-bulk-decrypt). |

**Options**

Expand Down Expand Up @@ -1423,19 +1423,19 @@ The `Manifest` type is returned by [`CreateTDF`](#createtdf) and accessible via
| Field | Type | Description |
|-------|------|-------------|
| `TDFVersion` | `string` | TDF spec version (e.g. `"4.3.0"`). Serialized as `schemaVersion` in the manifest JSON. |
| `EncryptionInformation` | `EncryptionInformation` | Encryption method, key access objects, and integrity information. |
| `Payload` | `Payload` | Metadata about the encrypted payload. |
| `Assertions` | `[]Assertion` | Cryptographically bound or signed statements attached to the TDF. Empty if none were added at encrypt time. |
| `EncryptionInformation` | [`EncryptionInformation`](#encryptioninformation) | Encryption method, key access objects, and integrity information. |
| `Payload` | [`Payload`](#manifest-payload) | Metadata about the encrypted payload. |
| `Assertions` | [`[]Assertion`](#assertion) | Cryptographically bound or signed statements attached to the TDF. Empty if none were added at encrypt time. |

**EncryptionInformation Fields**
#### EncryptionInformation

| Field | Type | Description |
|-------|------|-------------|
| `KeyAccessObjs` | `[]KeyAccess` | One entry per KAS holding a key grant. Split TDFs have multiple entries. |
| `KeyAccessObjs` | [`[]KeyAccess`](#keyaccess) | One entry per KAS holding a key grant. Split TDFs have multiple entries. |
| `Method.Algorithm` | `string` | Encryption algorithm (e.g. `"AES-256-GCM"`). |
| `Policy` | `string` | Base64-encoded policy object. Use [`tdfReader.Policy()`](#policy) to decode. |

**KeyAccess Fields**
#### KeyAccess

| Field | Type | Description |
|-------|------|-------------|
Expand All @@ -1444,7 +1444,7 @@ The `Manifest` type is returned by [`CreateTDF`](#createtdf) and accessible via
| `SplitID` | `string` | Key split identifier. Entries sharing the same ID share a key segment; different IDs represent independent splits. |
| `KID` | `string` | Key identifier on the KAS, if set. |

**Payload Fields**
#### Payload (manifest field) {#manifest-payload}

| Field | Type | Description |
|-------|------|-------------|
Expand Down Expand Up @@ -1503,11 +1503,24 @@ for _, a := range manifest.Assertions {
| Field | Type | Description |
|-------|------|-------------|
| `ID` | `string` | Assertion identifier (matches the `AssertionConfig.ID` used at encrypt time). |
| `Type` | `AssertionType` | `"handling"` or `"other"`. |
| `Scope` | `Scope` | `"tdo"` or `"payload"`. |
| `AppliesToState` | `AppliesToState` | `"encrypted"` or `"unencrypted"`. |
| `Statement` | `Statement` | The assertion content. |
| `Binding` | `Binding` | Cryptographic binding — `Method` (`"jws"`) and `Signature` (JWS token). |
| `Type` | [`AssertionType`](#assertion-types) | `"handling"` or `"other"`. |
| `Scope` | [`Scope`](#scopes) | `"tdo"` or `"payload"`. |
| `AppliesToState` | [`AppliesToState`](#appliestostate) | `"encrypted"` or `"unencrypted"`. |
| `Statement` | [`Statement`](#statement-type) | The assertion content. |
| `Binding` | [`Binding`](#binding) | Cryptographic binding — `Method` (`"jws"`) and `Signature` (JWS token). |

---

### Binding

The cryptographic binding attached to a signed [`Assertion`](#assertion).

**Fields**

| Field | Type | Description |
|-------|------|-------------|
| `Method` | `string` | Binding method. Currently `"jws"`. |
| `Signature` | `string` | The JWS token that binds the assertion to the TDF. |

---

Expand Down Expand Up @@ -1542,11 +1555,25 @@ Passed to `WithAssertionVerificationKeys` when loading a TDF. Maps assertion IDs

| Field | Type | Description |
|-------|------|-------------|
| `DefaultKey` | `AssertionKey` | Fallback key used when no ID-specific key is found. |
| `DefaultKey` | [`AssertionKey`](#assertionkey) | Fallback key used when no ID-specific key is found. |
| `Keys` | `map[string]AssertionKey` | Map of assertion ID to verification key. |

---

### RequiredObligations

Returned by [`Reader.Obligations()`](#obligations) and populated on each `BulkTDF.TriggeredObligations` field after [`PrepareBulkDecrypt`](#bulkdecrypt). Wraps the obligation FQNs the platform requires the consuming application to enforce before granting access to the TDF's payload.

Supported in the Go and JavaScript SDKs.

**Fields**

| Field | Go | JavaScript | Description |
|-------|-----|------------|-------------|
| FQNs / fqns | `FQNs []string` | `fqns: string[]` | Obligation value FQNs required for this TDF. Empty when no obligations are triggered. |

---

<EncryptOptions />

---
Expand Down
Loading