feat: add new methods Dataset.createItemsPublicUrl & KeyValueStore.createKeysPublicUrl

[danpoletaev]

When storage resources (Datasets or Key-Value Stores) are set to Restricted, accessing or sharing their data externally becomes difficult due to limited permissions. This PR introduces functionality to generate signed URLs that allow controlled external access to these resources without adding token to the request.

This PR introduces methods to generate signed URLs for Dataset items and Key-Value Store records:

1. Datasets
   dataset(:datasetId).createItemsPublicUrl(options, expiresInMillis)
   → Returns a signed URL like:
   /v2/datasets/:datasetId/items?signature=xxx

2. Key-Value Stores
   keyValueStore(:storeId).createKeysPublicUrl(options, expiresInMillis)
   → Returns a signed URL like:
   /v2/key-value-stores/:storeId/keys?signature=xxx

🕒 Expiration:
The expiresInMillis parameter defines how long the signature is valid.

• If provided, the URL will expire after the specified time.
• If omitted, the URL will never expire.

Note: The signature is included only if the token has WRITE access to the storage. Otherwise, an unsigned URL is returned.

P.S. We're not yet exposing urlSigningSecretKey for datasets, it will be released after PR is merged.

More context here

[janbuchar]

A "public key" already means something completely different. Any chance that the name could be changed?

[danpoletaev]

Sure, we can change the name. How about getPublicKeyListUrl?

[tobice]

Maybe we could do getKeysPublicUrl?

I was thinking about it already on the API PR... to me it makes more sense language-wise. It's not URL for public keys, it's a public URL for keys. But AI disagreed with my thinking so I let it be 😄

[danpoletaev]

AI doesn't like any of them 😄

maybe KeyValueStore.getPublicUrlForKeys() and Dataset.getPublicUrlForItems()?

[danpoletaev]

Gemini actually liked Tobi's proposal 🙃

I've renamed:
dataset(:datasetId).createItemsPublicUrl(options, expiresInMillis)
keyValueStore(:storeId).createKeysPublicUrl(options, expiresInMillis)

Also in API i renamed:

• publicItemsUrl => itemsPublicUrl
• publicKeysUrl => keysPublicUrl

[tobice]

Gemini actually liked Tobi's proposal 🙃

Well, you know, both brains were trained by Google ;D

[tobice]

Generally makes sense but I left a few nits and would like to take another look once it is finished. (Curious mainly about the naming.)

Also kudos for the nice PR description 👏

[tobice]

Maybe we could do getKeysPublicUrl?

I was thinking about it already on the API PR... to me it makes more sense language-wise. It's not URL for public keys, it's a public URL for keys. But AI disagreed with my thinking so I let it be 😄

[tobice]

Suggested change

	const expiresAt = expiresInMillis ? new Date().getTime() + expiresInMillis : null;
	const expiresAt = expiresInMillis ? new Date().getTime() + expiresInMillis : '0';

(opt) Maybe this?

Then in API you'll be able to do:

const parsedExpiresAtMillis = parseInt(expiresAtMillis, 10);
if (parsedExpiresAtMillis > 0 && parsedExpiresAtMillis < new Date().getTime()) {
    // signature expired
    return false;
}

[danpoletaev]

Honestly, I'd keep it as `null, but I updated comments in API 👇

// For non-expiring signatures, we pass 'null' as timestamp.
// If the timestamp is 'null', we don't need to check for expiration.
if (expiresAtMillis !== 'null' && parseInt(expiresAtMillis, 10) < new Date().getTime()) {
  // signature expired
  return false;
}

[tobice]

Uff, well, if this is what you want 😅

[danpoletaev]

well, but it is not required to check for expiresAtMillis !== 'null', I thought it would be more self-explanatory 😄

NaN < new Date().getTime() would always return false

[danpoletaev]

Okay, you're right 😄

In python it will looks ugly, since python has None not null.

expires_at_str = str(expires_at) if expires_at is not None else 'null'

Changing it to 0

[tobice]

Suggested change

*

[janbuchar]

Please update the PR title and description to match the new name 🙂 After that, feel free to merge