Skip to content

Usage license #205

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

Closed
wants to merge 2 commits into from
Closed

Usage license #205

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fad5de7
Merge branch 'release_4.6'
kriszyp Jul 15, 2025
21cad49
Add install and get usage licenses
kriszyp Jul 25, 2025
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
5 changes: 4 additions & 1 deletion docs/SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,8 +134,11 @@
* [Transactions](technical-details/reference/transactions.md)
* [Release Notes](technical-details/release-notes/README.md)
* [Harper Tucker (Version 4)](technical-details/release-notes/4.tucker/README.md)
* [4.6.0](technical-details/release-notes/4.tucker/4.6.0.md)
* [4.6.2](technical-details/release-notes/4.tucker/4.6.2.md)
* [4.6.1](technical-details/release-notes/4.tucker/4.6.1.md)
* [4.6.0](technical-details/release-notes/4.tucker/4.6.0.md)
* [4.5.14](technical-details/release-notes/4.tucker/4.5.14.md)
* [4.5.13](technical-details/release-notes/4.tucker/4.5.13.md)
* [4.5.12](technical-details/release-notes/4.tucker/4.5.12.md)
* [4.5.11](technical-details/release-notes/4.tucker/4.5.11.md)
* [4.5.10](technical-details/release-notes/4.tucker/4.5.10.md)
Expand Down
142 changes: 142 additions & 0 deletions docs/developers/operations-api/registration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,149 @@ Returns the registration data of the Harper instance.

---

## Install Usage License

Install a Harper license for a block of usage. Multiple usage blocks may be installed, and they will be used up sequentially, with the earliest installed blocks used first. A license is installed
by creating a string that consists of three base64 encoded blocks, separated by dots. The three blocks consist of:
* header: This is a JSON object with two properties:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems else where in this page and on other page we are using - for lists, not *. We should be consistent.

* typ: should be "Harper-License"
* alg: should be "EdDSA"
Comment on lines +34 to +36
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure how this will eventually be rendered, but maybe the properties should be code?

Suggested change
* header: This is a JSON object with two properties:
* typ: should be "Harper-License"
* alg: should be "EdDSA"
* `header`: This is a JSON object with two properties:
* `typ`: should be "Harper-License"
* `alg`: should be "EdDSA"


This JSON object should be converted to base64 (conversion from utf-8 to base64) and is the first base64 block.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I used base64url encoding originally (mostly just because it's what JWTs use and it seemed the safer choice overall). So unless you changed that, we should specify that here.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did not change the code, so yes, make it base64url if that is the behavior.


* license payload: This is a JSON object with properties:
* id _(required)_ - A unique id for the license
* level _(required)_ - Usage level number
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There was no description of this attribute in the original ticket, so the code currently expects it to be a string. I can adjust it to expect a number, but is there any more context about what this value is and any other constraints that should be placed on it?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This corresponds to the different levels from https://harperdb.atlassian.net/wiki/spaces/SD/pages/34209804/HarperDB+Usage+Pricing+and+Tracking. I don't think we have any functional behavior that depends on this (right now), so it is just informational. We could make this optional (and any type of if that is easier).

* regiondId _(required)_ - The region id where this license can be used
* reads _(required)_ - The number of allowed reads
* readBytes _(required)_ - The number of allowed read bytes
* writes _(required)_ - The number of allowed writes
* writeBytes _(required)_ - The number of allowed write bytes
* realTimeMessages _(required)_ - The number of allowed real-time messages
* realTimeBytes _(required)_ - The number of allowed real-time message bytes
* cpuTime _(optional)_ - The allowed amount of CPU time consumed by application code
* storage _(optional)_ - Maximum of storage that may be used
* expiration _(required_) - The date when this block expires, as an ISO date
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/required_)/required)_/


This JSON object should be converted to base64 (conversion from utf-8 to base64) and is the second base64 block.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This makes me wonder if we need any JSON normalization in here... Otherwise differences that a JSON parser would ignore might result in different base64 encodings.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't the signing of the JSON based on the generated licenses stringification? It seems like the signer can dictate all of that itself without coordination? But if coordination is needed, maybe we can just say without any extra/unnecessary spacing? (the default for JSON.stringify).


For example:
```json
{
"id": "license-717b-4c6c-b69d-b29014054ab7",
"level": 2,
"regionId": "us-nw-2",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This attribute is just called region currently.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Region makes sense to me because of the way we have region + latency sort of grouped together in the block pricing

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, region is fine.

"reads": 2000000000,
"readBytes": 8000000000000,
"writes": 500000000,
"writeBytes": 1000000000000,
"realTimeMessages": 10000000000,
"realTimeBytes": 40000000000000,
"cpuTime": 108000,
"storage": 400000000000000,
"expiration":"2025-07-25T21:17:21.248Z"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"expiration":"2025-07-25T21:17:21.248Z"
"expiration": "2025-07-25T21:17:21.248Z"

}
```

* signature: This is the cryptographic signature, signed by Harper, of the first two blocks, separated by a dot, `header.payload`. This is also converted to base64.

The three base64 blocks are combined to form the `license` property value in the operation.

- operation _(required)_ - must always be `install_usage_license`
- license _(required)_ - This is the combination of the three blocks in the form header.payload.signature
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Elsewhere the value is rendered as inline code.

Suggested change
- license _(required)_ - This is the combination of the three blocks in the form header.payload.signature
- license _(required)_ - This is the combination of the three blocks in the form `header.payload.signature`

### Body

```json
{
"operation": "install_usage_license",
"license": "abc...0123.abc...0123.abc...0123",
}
```

### Response: 200

```json
{
"message": "Successfully installed usage license"
}
```

---

## Get Usage Licenses

This will retrieve and return all active usage licenses, with counts of how much of the limits have been consumed.

- operation _(required)_ - must always be `install_usage_license`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be get_usage_licenses


### Body

```json
{
"operation": "get_usage_licenses"
}
```

### Response: 200

```json
[
{
"id": "license-717b-4c6c-b69d-b29014054ab7",
"level": 2,
"regionId": "us-nw-2",
"reads": 2000000000,
"usedReads": 1100000000,
"readBytes": 8000000000000,
"usedReadBytes": 3000000000000,
"writes": 500000000,
"usedWrites": 300000000,
"writeBytes": 1000000000000,
"usedWriteBytes": 4300000000000,
"realTimeMessages": 10000000000,
"usedRealTimeMessages": 2000000000,
"realTimeBytes": 40000000000000,
"usedRealTimeBytes": 13000000000000,
"cpuTime": 108000,
"usedCpuTime": 41000,
"storage": 400000000000000,
"expiration":"2025-07-25T21:17:21.248Z"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"expiration":"2025-07-25T21:17:21.248Z"
"expiration": "2025-07-25T21:17:21.248Z"

},
{
"id": "license-4c6c-b69d-b29014054ab7-717b",
"level": 2,
"regionId": "us-nw-2",
"reads": 2000000000,
"usedReads": 0,
"readBytes": 8000000000000,
"usedReadBytes": 0,
"writes": 500000000,
"usedWrites": 0,
"writeBytes": 1000000000000,
"usedWriteBytes": 0,
"realTimeMessages": 10000000000,
"usedRealTimeMessages": 0,
"realTimeBytes": 40000000000000,
"usedRealTimeBytes": 0,
"cpuTime": 108000,
"usedCpuTime": 0,
"storage": 400000000000000,
"expiration":"2025-09-25T21:17:21.248Z"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"expiration":"2025-09-25T21:17:21.248Z"
"expiration": "2025-09-25T21:17:21.248Z"

},
{
"id": "license-4c6c-b69d-b29014054ab7-717b",
"level": 2,
"regionId": "us-se-2",
... usage licenses for other regions may be in here as well
]
```

---
Comment on lines +164 to +167
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure what's going on here. Past merge conflict?



## Get Fingerprint

(Deprecated)
Returns the Harper fingerprint, uniquely generated based on the machine, for licensing purposes.

_Operation is restricted to super_user roles only_
Expand All @@ -47,6 +188,7 @@ _Operation is restricted to super_user roles only_

## Set License

(Deprecated)
Sets the Harper license as generated by Harper License Management software.

_Operation is restricted to super_user roles only_
Expand Down
4 changes: 4 additions & 0 deletions docs/technical-details/release-notes/4.tucker/4.5.13.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
### HarperDB 4.5.13
7/12/2025

- Fix cleaning out audit entries when a blob has been removed
4 changes: 4 additions & 0 deletions docs/technical-details/release-notes/4.tucker/4.5.14.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
### HarperDB 4.5.14
7/15/2025

- Use proper back-pressure when copying a table for initial database sync
6 changes: 6 additions & 0 deletions docs/technical-details/release-notes/4.tucker/4.6.2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# 4.6.2
7/15/2025

- Use proper back-pressure when copying a table for initial database sync
- Fix cleaning out audit entries when a blob has been removed
- Fix for running CLI operations when a Harper DB is not installed
6 changes: 6 additions & 0 deletions docs/technical-details/release-notes/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,16 @@

[Meet Tucker](4.tucker/tucker.md) Our 4th Release Pup

[4.6.2 Tucker](4.tucker/4.6.2.md)

[4.6.1 Tucker](4.tucker/4.6.1.md)

[4.6.0 Tucker](4.tucker/4.6.0.md)

[4.5.14 Tucker](4.tucker/4.5.14.md)

[4.5.13 Tucker](4.tucker/4.5.13.md)

[4.5.12 Tucker](4.tucker/4.5.12.md)

[4.5.11 Tucker](4.tucker/4.5.11.md)
Expand Down