Skip to content

Add GetKeysSummary Api Signature/protos#4

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
G8XSU merged 1 commit into from
Mar 15, 2023
Merged

Add GetKeysSummary Api Signature/protos #4

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
74 changes: 73 additions & 1 deletion app/src/main/proto/vss.proto
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -9,7 +9,7 @@ message GetObjectRequest {
// All APIs operate within a single store_id.
// It is up to clients to use single or multiple stores for their use-case.
// This can be used for client-isolation/ rate-limiting / throttling on the server-side.
// Authorization and billing can also be performed at the storeId level.
// Authorization and billing can also be performed at the store_id level.
string store_id = 1;

// Key for which the value is to be fetched.
Expand DownExpand Up@@ -98,6 +98,78 @@ message PutObjectRequest {
message PutObjectResponse {
}

message ListKeyVersionsRequest {

// store_id is a keyspace identifier.

@devrandomdevrandomJan 12, 2023

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

minor: might make sense to move repeating doc comments to the top of the file, and just link to them in each request proto.

@G8XSUG8XSUJan 13, 2023

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

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

Yeah, i want to do that but there wasn't a clear and nice way to do it.
If we do it the current way, protobuf generated classes have nicely added field docs.

@jkczyzjkczyzJan 25, 2023

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Yeah, i want to do that but there wasn't a clear and nice way to do it. If we do it the current way, protobuf generated classes have nicely added field docs.

Are you saying any top-level docs are not copied anywhere in the generated code? In my past experience, the generated code didn't have any docs at all, so developers would just look at the proto file. But perhaps this has changed.

We should ideally end off in a place where the reader has a high-level summary somewhere and have more detailed explanations as they drill down into messages and fields, IMO. Not sure how this will ultimately look, but I could imagine a few possibilities:

  • High-level summary at top, minimal request/response docs, detailed field docs
  • High-level summary at top, detailed request/response docs, minimal field docs
  • No high-level summary, high-level summary in request/response docs, detailed request/response docs

Regardless of which, we should have some high-level summary somewhere so developers don't have to exhaustively read every field doc to know how everything fits together. Feel free to do in a follow-up, of couse.

@G8XSUG8XSUJan 25, 2023•
edited
Loading

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

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

Are you saying any top-level docs are not copied anywhere in the generated code?

Yes, they get omitted, only field and struct level docs get into generated code.

My current plan is
"High-level summary in project docs, No high-level summary in proto, high-level summary in request/response docs, detailed field docs"

In this way, docs on top of fields and structs will get copied to generated code, and high-level project doc serves as reference for usage. It will also contain examples from client-side code.
Will take it as follow-up.

// Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store)
// All APIs operate within a single store_id.
// It is up to clients to use single or multiple stores for their use-case.
// This can be used for client-isolation/ rate-limiting / throttling on the server-side.
// Authorization and billing can also be performed at the store_id level.
string store_id = 1;

// A key_prefix is a string of characters at the beginning of the key. Prefixes can be used as
// a way to organize key-values in a similar way to directories.
//
// If key_prefix is specified, the response results will be limited to those keys that begin with
// the specified prefix.
//
// If no key_prefix is specified or it is empty (""), all the keys are eligible to be returned in
// the response.
optional string key_prefix = 2;

// page_size is used by clients to specify the maximum number of results that can be returned by
// the server.
// The server may further constrain the maximum number of results returned in a single page.
// If the page_size is 0 or not set, the server will decide the number of results to be returned.
optional int32 page_size = 3;

// page_token is a pagination token.
//
// To query for the first page of ListKeyVersions, page_token must not be specified.
//
// For subsequent pages, use the value that was returned as `next_page_token` in the previous
// page's ListKeyVersionsResponse.
optional string page_token = 4;
}

message ListKeyVersionsResponse {

// Fetched keys and versions.
// Even though this API reuses KeyValue struct, the value sub-field will not be set by the server.
repeated KeyValue key_versions = 1;

@G8XSUG8XSUDec 22, 2022

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

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

Consider: creating a separate struct for KeyVersion instead of re-using KeyValue struct here.

@devrandomdevrandomDec 22, 2022

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I would say here explicitly that the value will be empty. I think it's OK to reuse the struct.


// next_page_token is a pagination token, used to retrieve the next page of results.
// Use this value to query for next_page of paginated ListKeyVersions operation, by specifying
// this value as the `page_token` in the next request.
//
// If next_page_token is empty (""), then the "last page" of results has been processed and
// there is no more data to be retrieved.
//
// If next_page_token is not empty, it does not necessarily mean that there is more data in the
// result set. The only way to know when you have reached the end of the result set is when
// next_page_token is empty.
//
// Caution: Clients must not assume a specific number of key_versions to be present in a page for
// paginated response.
optional string next_page_token = 2;

// global_version is a sequence-number/version of the whole store.
//
// global_version is only returned in response for the first page of the ListKeyVersionsResponse
// and is guaranteed to be read before reading any key-versions.
//
// In case of refreshing the complete key-version view on the client-side, correct usage for
// the returned global_version is as following:
// 1. Read global_version from the first page of paginated response and save it as local variable.
// 2. Update all the key_versions on client-side from all the pages of paginated response.
// 3. Update global_version on client_side from the local variable saved in step-1.
// This ensures that on client-side, all current key_versions were stored at global_version or later.
// This guarantee is helpful for ensuring the versioning correctness if using the global_version
// in PutObject API and can help avoid the race conditions related to it.
optional int64 global_version = 3;
}

// When HttpStatusCode is not ok (200), the response `content` contains a serialized ErrorResponse
// with the relevant ErrorCode and message
message ErrorResponse {
Expand Down
, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
Add GetKeysSummary Api Signature/protos by G8XSU · Pull Request #4 · lightningdevkit/vss-server · GitHub
Skip to content
Add GetKeysSummary Api Signature/protos#4

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

G8XSU
merged 1 commit into

from

Mar 15, 2023
 Merged


Add GetKeysSummary Api Signature/protos
#4
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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


74 changes: 73 additions & 1 deletion
app/src/main/proto/vss.proto

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,7 +9,7 @@ message GetObjectRequest {
 // All APIs operate within a single store_id.
 // It is up to clients to use single or multiple stores for their use-case.
 // This can be used for client-isolation/ rate-limiting / throttling on the server-side.
 // Authorization and billing can also be performed at the storeId level.
 // Authorization and billing can also be performed at the store_id level.
 string store_id = 1;

 // Key for which the value is to be fetched.
Expand DownExpand Up@@ -98,6 +98,78 @@ message PutObjectRequest {
message PutObjectResponse {
}

message ListKeyVersionsRequest {

 // store_id is a keyspace identifier.
@devrandomdevrandomJan 12, 2023

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

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

minor: might make sense to move repeating doc comments to the top of the file, and just link to them in each request proto.
@G8XSUG8XSUJan 13, 2023

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Yeah, i want to do that but there wasn't a clear and nice way to do it.

If we do it the current way, protobuf generated classes have nicely added field docs.
@jkczyzjkczyzJan 25, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

Yeah, i want to do that but there wasn't a clear and nice way to do it. If we do it the current way, protobuf generated classes have nicely added field docs.
Are you saying any top-level docs are not copied anywhere in the generated code? In my past experience, the generated code didn't have any docs at all, so developers would just look at the proto file. But perhaps this has changed.
We should ideally end off in a place where the reader has a high-level summary somewhere and have more detailed explanations as they drill down into messages and fields, IMO. Not sure how this will ultimately look, but I could imagine a few possibilities:
  • High-level summary at top, minimal request/response docs, detailed field docs
  • High-level summary at top, detailed request/response docs, minimal field docs
  • No high-level summary, high-level summary in request/response docs, detailed request/response docs
Regardless of which, we should have some high-level summary somewhere so developers don't have to exhaustively read every field doc to know how everything fits together. Feel free to do in a follow-up, of couse.
@G8XSUG8XSUJan 25, 2023•

edited

Loading

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Are you saying any top-level docs are not copied anywhere in the generated code?
Yes, they get omitted, only field and struct level docs get into generated code.
My current plan is

"High-level summary in project docs, No high-level summary in proto, high-level summary in request/response docs, detailed field docs"
In this way, docs on top of fields and structs will get copied to generated code, and high-level project doc serves as reference for usage. It will also contain examples from client-side code.

Will take it as follow-up.
 // Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store)
 // All APIs operate within a single store_id.
 // It is up to clients to use single or multiple stores for their use-case.
 // This can be used for client-isolation/ rate-limiting / throttling on the server-side.
 // Authorization and billing can also be performed at the store_id level.
 string store_id = 1;

 // A key_prefix is a string of characters at the beginning of the key. Prefixes can be used as
 // a way to organize key-values in a similar way to directories.
 //
 // If key_prefix is specified, the response results will be limited to those keys that begin with
 // the specified prefix.
 //
 // If no key_prefix is specified or it is empty (""), all the keys are eligible to be returned in
 // the response.
 optional string key_prefix = 2;

 // page_size is used by clients to specify the maximum number of results that can be returned by
 // the server.
 // The server may further constrain the maximum number of results returned in a single page.
 // If the page_size is 0 or not set, the server will decide the number of results to be returned.
 optional int32 page_size = 3;

 // page_token is a pagination token.
 //
 // To query for the first page of ListKeyVersions, page_token must not be specified.
 //
 // For subsequent pages, use the value that was returned as `next_page_token` in the previous
 // page's ListKeyVersionsResponse.
 optional string page_token = 4;
}

message ListKeyVersionsResponse {

 // Fetched keys and versions.
 // Even though this API reuses KeyValue struct, the value sub-field will not be set by the server.
 repeated KeyValue key_versions = 1;
@G8XSUG8XSUDec 22, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Consider: creating a separate struct for KeyVersion instead of re-using KeyValue struct here.
@devrandomdevrandomDec 22, 2022

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

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

I would say here explicitly that the value will be empty. I think it's OK to reuse the struct.

 // next_page_token is a pagination token, used to retrieve the next page of results.
 // Use this value to query for next_page of paginated ListKeyVersions operation, by specifying
 // this value as the `page_token` in the next request.
 //
 // If next_page_token is empty (""), then the "last page" of results has been processed and
 // there is no more data to be retrieved.
 //
 // If next_page_token is not empty, it does not necessarily mean that there is more data in the
 // result set. The only way to know when you have reached the end of the result set is when
 // next_page_token is empty.
 //
 // Caution: Clients must not assume a specific number of key_versions to be present in a page for
 // paginated response.
 optional string next_page_token = 2;

 // global_version is a sequence-number/version of the whole store.
 //
 // global_version is only returned in response for the first page of the ListKeyVersionsResponse
 // and is guaranteed to be read before reading any key-versions.
 //
 // In case of refreshing the complete key-version view on the client-side, correct usage for
 // the returned global_version is as following:
 // 1. Read global_version from the first page of paginated response and save it as local variable.
 // 2. Update all the key_versions on client-side from all the pages of paginated response.
 // 3. Update global_version on client_side from the local variable saved in step-1.
 // This ensures that on client-side, all current key_versions were stored at global_version or later.
 // This guarantee is helpful for ensuring the versioning correctness if using the global_version
 // in PutObject API and can help avoid the race conditions related to it.
 optional int64 global_version = 3;
}

// When HttpStatusCode is not ok (200), the response `content` contains a serialized ErrorResponse
// with the relevant ErrorCode and message
message ErrorResponse {
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Add GetKeysSummary Api Signature/protos by G8XSU · Pull Request #4 · lightningdevkit/vss-server · GitHub
Skip to content
Add GetKeysSummary Api Signature/protos#4

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

G8XSU
merged 1 commit into

from

Mar 15, 2023
 Merged


Add GetKeysSummary Api Signature/protos
#4
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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


74 changes: 73 additions & 1 deletion
app/src/main/proto/vss.proto

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,7 +9,7 @@ message GetObjectRequest {
 // All APIs operate within a single store_id.
 // It is up to clients to use single or multiple stores for their use-case.
 // This can be used for client-isolation/ rate-limiting / throttling on the server-side.
 // Authorization and billing can also be performed at the storeId level.
 // Authorization and billing can also be performed at the store_id level.
 string store_id = 1;

 // Key for which the value is to be fetched.
Expand DownExpand Up@@ -98,6 +98,78 @@ message PutObjectRequest {
message PutObjectResponse {
}

message ListKeyVersionsRequest {

 // store_id is a keyspace identifier.
@devrandomdevrandomJan 12, 2023

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

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

minor: might make sense to move repeating doc comments to the top of the file, and just link to them in each request proto.
@G8XSUG8XSUJan 13, 2023

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Yeah, i want to do that but there wasn't a clear and nice way to do it.

If we do it the current way, protobuf generated classes have nicely added field docs.
@jkczyzjkczyzJan 25, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

Yeah, i want to do that but there wasn't a clear and nice way to do it. If we do it the current way, protobuf generated classes have nicely added field docs.
Are you saying any top-level docs are not copied anywhere in the generated code? In my past experience, the generated code didn't have any docs at all, so developers would just look at the proto file. But perhaps this has changed.
We should ideally end off in a place where the reader has a high-level summary somewhere and have more detailed explanations as they drill down into messages and fields, IMO. Not sure how this will ultimately look, but I could imagine a few possibilities:
  • High-level summary at top, minimal request/response docs, detailed field docs
  • High-level summary at top, detailed request/response docs, minimal field docs
  • No high-level summary, high-level summary in request/response docs, detailed request/response docs
Regardless of which, we should have some high-level summary somewhere so developers don't have to exhaustively read every field doc to know how everything fits together. Feel free to do in a follow-up, of couse.
@G8XSUG8XSUJan 25, 2023•

edited

Loading

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Are you saying any top-level docs are not copied anywhere in the generated code?
Yes, they get omitted, only field and struct level docs get into generated code.
My current plan is

"High-level summary in project docs, No high-level summary in proto, high-level summary in request/response docs, detailed field docs"
In this way, docs on top of fields and structs will get copied to generated code, and high-level project doc serves as reference for usage. It will also contain examples from client-side code.

Will take it as follow-up.
 // Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store)
 // All APIs operate within a single store_id.
 // It is up to clients to use single or multiple stores for their use-case.
 // This can be used for client-isolation/ rate-limiting / throttling on the server-side.
 // Authorization and billing can also be performed at the store_id level.
 string store_id = 1;

 // A key_prefix is a string of characters at the beginning of the key. Prefixes can be used as
 // a way to organize key-values in a similar way to directories.
 //
 // If key_prefix is specified, the response results will be limited to those keys that begin with
 // the specified prefix.
 //
 // If no key_prefix is specified or it is empty (""), all the keys are eligible to be returned in
 // the response.
 optional string key_prefix = 2;

 // page_size is used by clients to specify the maximum number of results that can be returned by
 // the server.
 // The server may further constrain the maximum number of results returned in a single page.
 // If the page_size is 0 or not set, the server will decide the number of results to be returned.
 optional int32 page_size = 3;

 // page_token is a pagination token.
 //
 // To query for the first page of ListKeyVersions, page_token must not be specified.
 //
 // For subsequent pages, use the value that was returned as `next_page_token` in the previous
 // page's ListKeyVersionsResponse.
 optional string page_token = 4;
}

message ListKeyVersionsResponse {

 // Fetched keys and versions.
 // Even though this API reuses KeyValue struct, the value sub-field will not be set by the server.
 repeated KeyValue key_versions = 1;
@G8XSUG8XSUDec 22, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Consider: creating a separate struct for KeyVersion instead of re-using KeyValue struct here.
@devrandomdevrandomDec 22, 2022

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

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

I would say here explicitly that the value will be empty. I think it's OK to reuse the struct.

 // next_page_token is a pagination token, used to retrieve the next page of results.
 // Use this value to query for next_page of paginated ListKeyVersions operation, by specifying
 // this value as the `page_token` in the next request.
 //
 // If next_page_token is empty (""), then the "last page" of results has been processed and
 // there is no more data to be retrieved.
 //
 // If next_page_token is not empty, it does not necessarily mean that there is more data in the
 // result set. The only way to know when you have reached the end of the result set is when
 // next_page_token is empty.
 //
 // Caution: Clients must not assume a specific number of key_versions to be present in a page for
 // paginated response.
 optional string next_page_token = 2;

 // global_version is a sequence-number/version of the whole store.
 //
 // global_version is only returned in response for the first page of the ListKeyVersionsResponse
 // and is guaranteed to be read before reading any key-versions.
 //
 // In case of refreshing the complete key-version view on the client-side, correct usage for
 // the returned global_version is as following:
 // 1. Read global_version from the first page of paginated response and save it as local variable.
 // 2. Update all the key_versions on client-side from all the pages of paginated response.
 // 3. Update global_version on client_side from the local variable saved in step-1.
 // This ensures that on client-side, all current key_versions were stored at global_version or later.
 // This guarantee is helpful for ensuring the versioning correctness if using the global_version
 // in PutObject API and can help avoid the race conditions related to it.
 optional int64 global_version = 3;
}

// When HttpStatusCode is not ok (200), the response `content` contains a serialized ErrorResponse
// with the relevant ErrorCode and message
message ErrorResponse {
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Add GetKeysSummary Api Signature/protos by G8XSU · Pull Request #4 · lightningdevkit/vss-server · GitHub
Skip to content
Add GetKeysSummary Api Signature/protos#4

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

G8XSU
merged 1 commit into

from

Mar 15, 2023
 Merged


Add GetKeysSummary Api Signature/protos
#4
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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


74 changes: 73 additions & 1 deletion
app/src/main/proto/vss.proto

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,7 +9,7 @@ message GetObjectRequest {
 // All APIs operate within a single store_id.
 // It is up to clients to use single or multiple stores for their use-case.
 // This can be used for client-isolation/ rate-limiting / throttling on the server-side.
 // Authorization and billing can also be performed at the storeId level.
 // Authorization and billing can also be performed at the store_id level.
 string store_id = 1;

 // Key for which the value is to be fetched.
Expand DownExpand Up@@ -98,6 +98,78 @@ message PutObjectRequest {
message PutObjectResponse {
}

message ListKeyVersionsRequest {

 // store_id is a keyspace identifier.
@devrandomdevrandomJan 12, 2023

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

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

minor: might make sense to move repeating doc comments to the top of the file, and just link to them in each request proto.
@G8XSUG8XSUJan 13, 2023

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Yeah, i want to do that but there wasn't a clear and nice way to do it.

If we do it the current way, protobuf generated classes have nicely added field docs.
@jkczyzjkczyzJan 25, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

Yeah, i want to do that but there wasn't a clear and nice way to do it. If we do it the current way, protobuf generated classes have nicely added field docs.
Are you saying any top-level docs are not copied anywhere in the generated code? In my past experience, the generated code didn't have any docs at all, so developers would just look at the proto file. But perhaps this has changed.
We should ideally end off in a place where the reader has a high-level summary somewhere and have more detailed explanations as they drill down into messages and fields, IMO. Not sure how this will ultimately look, but I could imagine a few possibilities:
  • High-level summary at top, minimal request/response docs, detailed field docs
  • High-level summary at top, detailed request/response docs, minimal field docs
  • No high-level summary, high-level summary in request/response docs, detailed request/response docs
Regardless of which, we should have some high-level summary somewhere so developers don't have to exhaustively read every field doc to know how everything fits together. Feel free to do in a follow-up, of couse.
@G8XSUG8XSUJan 25, 2023•

edited

Loading

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Are you saying any top-level docs are not copied anywhere in the generated code?
Yes, they get omitted, only field and struct level docs get into generated code.
My current plan is

"High-level summary in project docs, No high-level summary in proto, high-level summary in request/response docs, detailed field docs"
In this way, docs on top of fields and structs will get copied to generated code, and high-level project doc serves as reference for usage. It will also contain examples from client-side code.

Will take it as follow-up.
 // Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store)
 // All APIs operate within a single store_id.
 // It is up to clients to use single or multiple stores for their use-case.
 // This can be used for client-isolation/ rate-limiting / throttling on the server-side.
 // Authorization and billing can also be performed at the store_id level.
 string store_id = 1;

 // A key_prefix is a string of characters at the beginning of the key. Prefixes can be used as
 // a way to organize key-values in a similar way to directories.
 //
 // If key_prefix is specified, the response results will be limited to those keys that begin with
 // the specified prefix.
 //
 // If no key_prefix is specified or it is empty (""), all the keys are eligible to be returned in
 // the response.
 optional string key_prefix = 2;

 // page_size is used by clients to specify the maximum number of results that can be returned by
 // the server.
 // The server may further constrain the maximum number of results returned in a single page.
 // If the page_size is 0 or not set, the server will decide the number of results to be returned.
 optional int32 page_size = 3;

 // page_token is a pagination token.
 //
 // To query for the first page of ListKeyVersions, page_token must not be specified.
 //
 // For subsequent pages, use the value that was returned as `next_page_token` in the previous
 // page's ListKeyVersionsResponse.
 optional string page_token = 4;
}

message ListKeyVersionsResponse {

 // Fetched keys and versions.
 // Even though this API reuses KeyValue struct, the value sub-field will not be set by the server.
 repeated KeyValue key_versions = 1;
@G8XSUG8XSUDec 22, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Consider: creating a separate struct for KeyVersion instead of re-using KeyValue struct here.
@devrandomdevrandomDec 22, 2022

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

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

I would say here explicitly that the value will be empty. I think it's OK to reuse the struct.

 // next_page_token is a pagination token, used to retrieve the next page of results.
 // Use this value to query for next_page of paginated ListKeyVersions operation, by specifying
 // this value as the `page_token` in the next request.
 //
 // If next_page_token is empty (""), then the "last page" of results has been processed and
 // there is no more data to be retrieved.
 //
 // If next_page_token is not empty, it does not necessarily mean that there is more data in the
 // result set. The only way to know when you have reached the end of the result set is when
 // next_page_token is empty.
 //
 // Caution: Clients must not assume a specific number of key_versions to be present in a page for
 // paginated response.
 optional string next_page_token = 2;

 // global_version is a sequence-number/version of the whole store.
 //
 // global_version is only returned in response for the first page of the ListKeyVersionsResponse
 // and is guaranteed to be read before reading any key-versions.
 //
 // In case of refreshing the complete key-version view on the client-side, correct usage for
 // the returned global_version is as following:
 // 1. Read global_version from the first page of paginated response and save it as local variable.
 // 2. Update all the key_versions on client-side from all the pages of paginated response.
 // 3. Update global_version on client_side from the local variable saved in step-1.
 // This ensures that on client-side, all current key_versions were stored at global_version or later.
 // This guarantee is helpful for ensuring the versioning correctness if using the global_version
 // in PutObject API and can help avoid the race conditions related to it.
 optional int64 global_version = 3;
}

// When HttpStatusCode is not ok (200), the response `content` contains a serialized ErrorResponse
// with the relevant ErrorCode and message
message ErrorResponse {
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '
Add GetKeysSummary Api Signature/protos by G8XSU · Pull Request #4 · lightningdevkit/vss-server · GitHub
Skip to content
Add GetKeysSummary Api Signature/protos#4

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

G8XSU
merged 1 commit into

from

Mar 15, 2023
 Merged


Add GetKeysSummary Api Signature/protos
#4
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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


74 changes: 73 additions & 1 deletion
app/src/main/proto/vss.proto

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,7 +9,7 @@ message GetObjectRequest {
 // All APIs operate within a single store_id.
 // It is up to clients to use single or multiple stores for their use-case.
 // This can be used for client-isolation/ rate-limiting / throttling on the server-side.
 // Authorization and billing can also be performed at the storeId level.
 // Authorization and billing can also be performed at the store_id level.
 string store_id = 1;

 // Key for which the value is to be fetched.
Expand DownExpand Up@@ -98,6 +98,78 @@ message PutObjectRequest {
message PutObjectResponse {
}

message ListKeyVersionsRequest {

 // store_id is a keyspace identifier.
@devrandomdevrandomJan 12, 2023

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

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

minor: might make sense to move repeating doc comments to the top of the file, and just link to them in each request proto.
@G8XSUG8XSUJan 13, 2023

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Yeah, i want to do that but there wasn't a clear and nice way to do it.

If we do it the current way, protobuf generated classes have nicely added field docs.
@jkczyzjkczyzJan 25, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

Yeah, i want to do that but there wasn't a clear and nice way to do it. If we do it the current way, protobuf generated classes have nicely added field docs.
Are you saying any top-level docs are not copied anywhere in the generated code? In my past experience, the generated code didn't have any docs at all, so developers would just look at the proto file. But perhaps this has changed.
We should ideally end off in a place where the reader has a high-level summary somewhere and have more detailed explanations as they drill down into messages and fields, IMO. Not sure how this will ultimately look, but I could imagine a few possibilities:
  • High-level summary at top, minimal request/response docs, detailed field docs
  • High-level summary at top, detailed request/response docs, minimal field docs
  • No high-level summary, high-level summary in request/response docs, detailed request/response docs
Regardless of which, we should have some high-level summary somewhere so developers don't have to exhaustively read every field doc to know how everything fits together. Feel free to do in a follow-up, of couse.
@G8XSUG8XSUJan 25, 2023•

edited

Loading

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Are you saying any top-level docs are not copied anywhere in the generated code?
Yes, they get omitted, only field and struct level docs get into generated code.
My current plan is

"High-level summary in project docs, No high-level summary in proto, high-level summary in request/response docs, detailed field docs"
In this way, docs on top of fields and structs will get copied to generated code, and high-level project doc serves as reference for usage. It will also contain examples from client-side code.

Will take it as follow-up.
 // Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store)
 // All APIs operate within a single store_id.
 // It is up to clients to use single or multiple stores for their use-case.
 // This can be used for client-isolation/ rate-limiting / throttling on the server-side.
 // Authorization and billing can also be performed at the store_id level.
 string store_id = 1;

 // A key_prefix is a string of characters at the beginning of the key. Prefixes can be used as
 // a way to organize key-values in a similar way to directories.
 //
 // If key_prefix is specified, the response results will be limited to those keys that begin with
 // the specified prefix.
 //
 // If no key_prefix is specified or it is empty (""), all the keys are eligible to be returned in
 // the response.
 optional string key_prefix = 2;

 // page_size is used by clients to specify the maximum number of results that can be returned by
 // the server.
 // The server may further constrain the maximum number of results returned in a single page.
 // If the page_size is 0 or not set, the server will decide the number of results to be returned.
 optional int32 page_size = 3;

 // page_token is a pagination token.
 //
 // To query for the first page of ListKeyVersions, page_token must not be specified.
 //
 // For subsequent pages, use the value that was returned as `next_page_token` in the previous
 // page's ListKeyVersionsResponse.
 optional string page_token = 4;
}

message ListKeyVersionsResponse {

 // Fetched keys and versions.
 // Even though this API reuses KeyValue struct, the value sub-field will not be set by the server.
 repeated KeyValue key_versions = 1;
@G8XSUG8XSUDec 22, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Consider: creating a separate struct for KeyVersion instead of re-using KeyValue struct here.
@devrandomdevrandomDec 22, 2022

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

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

I would say here explicitly that the value will be empty. I think it's OK to reuse the struct.

 // next_page_token is a pagination token, used to retrieve the next page of results.
 // Use this value to query for next_page of paginated ListKeyVersions operation, by specifying
 // this value as the `page_token` in the next request.
 //
 // If next_page_token is empty (""), then the "last page" of results has been processed and
 // there is no more data to be retrieved.
 //
 // If next_page_token is not empty, it does not necessarily mean that there is more data in the
 // result set. The only way to know when you have reached the end of the result set is when
 // next_page_token is empty.
 //
 // Caution: Clients must not assume a specific number of key_versions to be present in a page for
 // paginated response.
 optional string next_page_token = 2;

 // global_version is a sequence-number/version of the whole store.
 //
 // global_version is only returned in response for the first page of the ListKeyVersionsResponse
 // and is guaranteed to be read before reading any key-versions.
 //
 // In case of refreshing the complete key-version view on the client-side, correct usage for
 // the returned global_version is as following:
 // 1. Read global_version from the first page of paginated response and save it as local variable.
 // 2. Update all the key_versions on client-side from all the pages of paginated response.
 // 3. Update global_version on client_side from the local variable saved in step-1.
 // This ensures that on client-side, all current key_versions were stored at global_version or later.
 // This guarantee is helpful for ensuring the versioning correctness if using the global_version
 // in PutObject API and can help avoid the race conditions related to it.
 optional int64 global_version = 3;
}

// When HttpStatusCode is not ok (200), the response `content` contains a serialized ErrorResponse
// with the relevant ErrorCode and message
message ErrorResponse {
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Add GetKeysSummary Api Signature/protos by G8XSU · Pull Request #4 · lightningdevkit/vss-server · GitHub
Skip to content
Add GetKeysSummary Api Signature/protos#4

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

G8XSU
merged 1 commit into

from

Mar 15, 2023
 Merged


Add GetKeysSummary Api Signature/protos
#4
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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


74 changes: 73 additions & 1 deletion
app/src/main/proto/vss.proto

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,7 +9,7 @@ message GetObjectRequest {
 // All APIs operate within a single store_id.
 // It is up to clients to use single or multiple stores for their use-case.
 // This can be used for client-isolation/ rate-limiting / throttling on the server-side.
 // Authorization and billing can also be performed at the storeId level.
 // Authorization and billing can also be performed at the store_id level.
 string store_id = 1;

 // Key for which the value is to be fetched.
Expand DownExpand Up@@ -98,6 +98,78 @@ message PutObjectRequest {
message PutObjectResponse {
}

message ListKeyVersionsRequest {

 // store_id is a keyspace identifier.
@devrandomdevrandomJan 12, 2023

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

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

minor: might make sense to move repeating doc comments to the top of the file, and just link to them in each request proto.
@G8XSUG8XSUJan 13, 2023

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Yeah, i want to do that but there wasn't a clear and nice way to do it.

If we do it the current way, protobuf generated classes have nicely added field docs.
@jkczyzjkczyzJan 25, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

Yeah, i want to do that but there wasn't a clear and nice way to do it. If we do it the current way, protobuf generated classes have nicely added field docs.
Are you saying any top-level docs are not copied anywhere in the generated code? In my past experience, the generated code didn't have any docs at all, so developers would just look at the proto file. But perhaps this has changed.
We should ideally end off in a place where the reader has a high-level summary somewhere and have more detailed explanations as they drill down into messages and fields, IMO. Not sure how this will ultimately look, but I could imagine a few possibilities:
  • High-level summary at top, minimal request/response docs, detailed field docs
  • High-level summary at top, detailed request/response docs, minimal field docs
  • No high-level summary, high-level summary in request/response docs, detailed request/response docs
Regardless of which, we should have some high-level summary somewhere so developers don't have to exhaustively read every field doc to know how everything fits together. Feel free to do in a follow-up, of couse.
@G8XSUG8XSUJan 25, 2023•

edited

Loading

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Are you saying any top-level docs are not copied anywhere in the generated code?
Yes, they get omitted, only field and struct level docs get into generated code.
My current plan is

"High-level summary in project docs, No high-level summary in proto, high-level summary in request/response docs, detailed field docs"
In this way, docs on top of fields and structs will get copied to generated code, and high-level project doc serves as reference for usage. It will also contain examples from client-side code.

Will take it as follow-up.
 // Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store)
 // All APIs operate within a single store_id.
 // It is up to clients to use single or multiple stores for their use-case.
 // This can be used for client-isolation/ rate-limiting / throttling on the server-side.
 // Authorization and billing can also be performed at the store_id level.
 string store_id = 1;

 // A key_prefix is a string of characters at the beginning of the key. Prefixes can be used as
 // a way to organize key-values in a similar way to directories.
 //
 // If key_prefix is specified, the response results will be limited to those keys that begin with
 // the specified prefix.
 //
 // If no key_prefix is specified or it is empty (""), all the keys are eligible to be returned in
 // the response.
 optional string key_prefix = 2;

 // page_size is used by clients to specify the maximum number of results that can be returned by
 // the server.
 // The server may further constrain the maximum number of results returned in a single page.
 // If the page_size is 0 or not set, the server will decide the number of results to be returned.
 optional int32 page_size = 3;

 // page_token is a pagination token.
 //
 // To query for the first page of ListKeyVersions, page_token must not be specified.
 //
 // For subsequent pages, use the value that was returned as `next_page_token` in the previous
 // page's ListKeyVersionsResponse.
 optional string page_token = 4;
}

message ListKeyVersionsResponse {

 // Fetched keys and versions.
 // Even though this API reuses KeyValue struct, the value sub-field will not be set by the server.
 repeated KeyValue key_versions = 1;
@G8XSUG8XSUDec 22, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Consider: creating a separate struct for KeyVersion instead of re-using KeyValue struct here.
@devrandomdevrandomDec 22, 2022

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

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

I would say here explicitly that the value will be empty. I think it's OK to reuse the struct.

 // next_page_token is a pagination token, used to retrieve the next page of results.
 // Use this value to query for next_page of paginated ListKeyVersions operation, by specifying
 // this value as the `page_token` in the next request.
 //
 // If next_page_token is empty (""), then the "last page" of results has been processed and
 // there is no more data to be retrieved.
 //
 // If next_page_token is not empty, it does not necessarily mean that there is more data in the
 // result set. The only way to know when you have reached the end of the result set is when
 // next_page_token is empty.
 //
 // Caution: Clients must not assume a specific number of key_versions to be present in a page for
 // paginated response.
 optional string next_page_token = 2;

 // global_version is a sequence-number/version of the whole store.
 //
 // global_version is only returned in response for the first page of the ListKeyVersionsResponse
 // and is guaranteed to be read before reading any key-versions.
 //
 // In case of refreshing the complete key-version view on the client-side, correct usage for
 // the returned global_version is as following:
 // 1. Read global_version from the first page of paginated response and save it as local variable.
 // 2. Update all the key_versions on client-side from all the pages of paginated response.
 // 3. Update global_version on client_side from the local variable saved in step-1.
 // This ensures that on client-side, all current key_versions were stored at global_version or later.
 // This guarantee is helpful for ensuring the versioning correctness if using the global_version
 // in PutObject API and can help avoid the race conditions related to it.
 optional int64 global_version = 3;
}

// When HttpStatusCode is not ok (200), the response `content` contains a serialized ErrorResponse
// with the relevant ErrorCode and message
message ErrorResponse {
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Add GetKeysSummary Api Signature/protos by G8XSU · Pull Request #4 · lightningdevkit/vss-server · GitHub
Skip to content
Add GetKeysSummary Api Signature/protos#4

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

G8XSU
merged 1 commit into

from

Mar 15, 2023
 Merged


Add GetKeysSummary Api Signature/protos
#4
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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


74 changes: 73 additions & 1 deletion
app/src/main/proto/vss.proto

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,7 +9,7 @@ message GetObjectRequest {
 // All APIs operate within a single store_id.
 // It is up to clients to use single or multiple stores for their use-case.
 // This can be used for client-isolation/ rate-limiting / throttling on the server-side.
 // Authorization and billing can also be performed at the storeId level.
 // Authorization and billing can also be performed at the store_id level.
 string store_id = 1;

 // Key for which the value is to be fetched.
Expand DownExpand Up@@ -98,6 +98,78 @@ message PutObjectRequest {
message PutObjectResponse {
}

message ListKeyVersionsRequest {

 // store_id is a keyspace identifier.
@devrandomdevrandomJan 12, 2023

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

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

minor: might make sense to move repeating doc comments to the top of the file, and just link to them in each request proto.
@G8XSUG8XSUJan 13, 2023

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Yeah, i want to do that but there wasn't a clear and nice way to do it.

If we do it the current way, protobuf generated classes have nicely added field docs.
@jkczyzjkczyzJan 25, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

Yeah, i want to do that but there wasn't a clear and nice way to do it. If we do it the current way, protobuf generated classes have nicely added field docs.
Are you saying any top-level docs are not copied anywhere in the generated code? In my past experience, the generated code didn't have any docs at all, so developers would just look at the proto file. But perhaps this has changed.
We should ideally end off in a place where the reader has a high-level summary somewhere and have more detailed explanations as they drill down into messages and fields, IMO. Not sure how this will ultimately look, but I could imagine a few possibilities:
  • High-level summary at top, minimal request/response docs, detailed field docs
  • High-level summary at top, detailed request/response docs, minimal field docs
  • No high-level summary, high-level summary in request/response docs, detailed request/response docs
Regardless of which, we should have some high-level summary somewhere so developers don't have to exhaustively read every field doc to know how everything fits together. Feel free to do in a follow-up, of couse.
@G8XSUG8XSUJan 25, 2023•

edited

Loading

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Are you saying any top-level docs are not copied anywhere in the generated code?
Yes, they get omitted, only field and struct level docs get into generated code.
My current plan is

"High-level summary in project docs, No high-level summary in proto, high-level summary in request/response docs, detailed field docs"
In this way, docs on top of fields and structs will get copied to generated code, and high-level project doc serves as reference for usage. It will also contain examples from client-side code.

Will take it as follow-up.
 // Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store)
 // All APIs operate within a single store_id.
 // It is up to clients to use single or multiple stores for their use-case.
 // This can be used for client-isolation/ rate-limiting / throttling on the server-side.
 // Authorization and billing can also be performed at the store_id level.
 string store_id = 1;

 // A key_prefix is a string of characters at the beginning of the key. Prefixes can be used as
 // a way to organize key-values in a similar way to directories.
 //
 // If key_prefix is specified, the response results will be limited to those keys that begin with
 // the specified prefix.
 //
 // If no key_prefix is specified or it is empty (""), all the keys are eligible to be returned in
 // the response.
 optional string key_prefix = 2;

 // page_size is used by clients to specify the maximum number of results that can be returned by
 // the server.
 // The server may further constrain the maximum number of results returned in a single page.
 // If the page_size is 0 or not set, the server will decide the number of results to be returned.
 optional int32 page_size = 3;

 // page_token is a pagination token.
 //
 // To query for the first page of ListKeyVersions, page_token must not be specified.
 //
 // For subsequent pages, use the value that was returned as `next_page_token` in the previous
 // page's ListKeyVersionsResponse.
 optional string page_token = 4;
}

message ListKeyVersionsResponse {

 // Fetched keys and versions.
 // Even though this API reuses KeyValue struct, the value sub-field will not be set by the server.
 repeated KeyValue key_versions = 1;
@G8XSUG8XSUDec 22, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Consider: creating a separate struct for KeyVersion instead of re-using KeyValue struct here.
@devrandomdevrandomDec 22, 2022

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

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

I would say here explicitly that the value will be empty. I think it's OK to reuse the struct.

 // next_page_token is a pagination token, used to retrieve the next page of results.
 // Use this value to query for next_page of paginated ListKeyVersions operation, by specifying
 // this value as the `page_token` in the next request.
 //
 // If next_page_token is empty (""), then the "last page" of results has been processed and
 // there is no more data to be retrieved.
 //
 // If next_page_token is not empty, it does not necessarily mean that there is more data in the
 // result set. The only way to know when you have reached the end of the result set is when
 // next_page_token is empty.
 //
 // Caution: Clients must not assume a specific number of key_versions to be present in a page for
 // paginated response.
 optional string next_page_token = 2;

 // global_version is a sequence-number/version of the whole store.
 //
 // global_version is only returned in response for the first page of the ListKeyVersionsResponse
 // and is guaranteed to be read before reading any key-versions.
 //
 // In case of refreshing the complete key-version view on the client-side, correct usage for
 // the returned global_version is as following:
 // 1. Read global_version from the first page of paginated response and save it as local variable.
 // 2. Update all the key_versions on client-side from all the pages of paginated response.
 // 3. Update global_version on client_side from the local variable saved in step-1.
 // This ensures that on client-side, all current key_versions were stored at global_version or later.
 // This guarantee is helpful for ensuring the versioning correctness if using the global_version
 // in PutObject API and can help avoid the race conditions related to it.
 optional int64 global_version = 3;
}

// When HttpStatusCode is not ok (200), the response `content` contains a serialized ErrorResponse
// with the relevant ErrorCode and message
message ErrorResponse {
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Universal Dark Mode - works on any site
(function() {
var enabled = true;
function applyDarkMode() {
if (!enabled) return;
// Create style element if it doesn't exist
var style = document.getElementById('universal-dark-mode-style');
if (!style) {
style = document.createElement('style');
style.id = 'universal-dark-mode-style';
document.head.appendChild(style);
}
// Dark mode CSS - inverts colors but preserves images/video
style.textContent = '
/* Invert everything except media */
html {
filter: invert(1) hue-rotate(180deg) !important;
background: #1a1a2e !important;
}
/* Restore images, videos, iframes, canvas */
img, video, iframe, canvas, svg, picture, [style*="background-image"] {
filter: invert(1) hue-rotate(180deg) !important;
}
/* Preserve specific elements that should not be inverted */
.no-dark-mode, .no-dark-mode *,
[data-theme="light"], [data-theme="light"],
.ace_editor, .ace_editor *,
.CodeMirror, .CodeMirror *,
.monaco-editor, .monaco-editor *,
.markdown-body pre, .markdown-body pre *,
.highlight, .highlight *,
pre code, pre code * {
filter: none !important;
}
/* Fix common UI elements */
.modal, .popup, .dropdown-menu, .tooltip, .popover {
filter: invert(1) hue-rotate(180deg) !important;
background: #2d2d44 !important;
border-color: #444 !important;
}
/* Scrollbars */
::-webkit-scrollbar { background: #1a1a2e !important; }
::-webkit-scrollbar-thumb { background: #444 !important; }
::-webkit-scrollbar-thumb:hover { background: #555 !important; }
/* Selection */
::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
';
}
function removeDarkMode() {
var style = document.getElementById('universal-dark-mode-style');
if (style) style.remove();
}
// Toggle with Alt+Shift+D
document.addEventListener('keydown', function(e) {
if (e.altKey && e.shiftKey && e.key === 'D') {
e.preventDefault();
enabled = !enabled;
if (enabled) {
applyDarkMode();
console.log('[Universal Dark Mode] Enabled');
} else {
removeDarkMode();
console.log('[Universal Dark Mode] Disabled');
}
}
});
// Apply on load
applyDarkMode();
// Re-apply on dynamic content
var observer = new MutationObserver(function(mutations) {
if (enabled && !document.getElementById('universal-dark-mode-style')) {
applyDarkMode();
}
});
observer.observe(document.head, { childList: true });
console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');
})();
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();
Add GetKeysSummary Api Signature/protos by G8XSU · Pull Request #4 · lightningdevkit/vss-server · GitHub
Skip to content
Add GetKeysSummary Api Signature/protos#4

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

G8XSU
merged 1 commit into

from

Mar 15, 2023
 Merged


Add GetKeysSummary Api Signature/protos
#4
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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


74 changes: 73 additions & 1 deletion
app/src/main/proto/vss.proto

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,7 +9,7 @@ message GetObjectRequest {
 // All APIs operate within a single store_id.
 // It is up to clients to use single or multiple stores for their use-case.
 // This can be used for client-isolation/ rate-limiting / throttling on the server-side.
 // Authorization and billing can also be performed at the storeId level.
 // Authorization and billing can also be performed at the store_id level.
 string store_id = 1;

 // Key for which the value is to be fetched.
Expand DownExpand Up@@ -98,6 +98,78 @@ message PutObjectRequest {
message PutObjectResponse {
}

message ListKeyVersionsRequest {

 // store_id is a keyspace identifier.
@devrandomdevrandomJan 12, 2023

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

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

minor: might make sense to move repeating doc comments to the top of the file, and just link to them in each request proto.
@G8XSUG8XSUJan 13, 2023

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Yeah, i want to do that but there wasn't a clear and nice way to do it.

If we do it the current way, protobuf generated classes have nicely added field docs.
@jkczyzjkczyzJan 25, 2023

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

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

Yeah, i want to do that but there wasn't a clear and nice way to do it. If we do it the current way, protobuf generated classes have nicely added field docs.
Are you saying any top-level docs are not copied anywhere in the generated code? In my past experience, the generated code didn't have any docs at all, so developers would just look at the proto file. But perhaps this has changed.
We should ideally end off in a place where the reader has a high-level summary somewhere and have more detailed explanations as they drill down into messages and fields, IMO. Not sure how this will ultimately look, but I could imagine a few possibilities:
  • High-level summary at top, minimal request/response docs, detailed field docs
  • High-level summary at top, detailed request/response docs, minimal field docs
  • No high-level summary, high-level summary in request/response docs, detailed request/response docs
Regardless of which, we should have some high-level summary somewhere so developers don't have to exhaustively read every field doc to know how everything fits together. Feel free to do in a follow-up, of couse.
@G8XSUG8XSUJan 25, 2023•

edited

Loading

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Are you saying any top-level docs are not copied anywhere in the generated code?
Yes, they get omitted, only field and struct level docs get into generated code.
My current plan is

"High-level summary in project docs, No high-level summary in proto, high-level summary in request/response docs, detailed field docs"
In this way, docs on top of fields and structs will get copied to generated code, and high-level project doc serves as reference for usage. It will also contain examples from client-side code.

Will take it as follow-up.
 // Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store)
 // All APIs operate within a single store_id.
 // It is up to clients to use single or multiple stores for their use-case.
 // This can be used for client-isolation/ rate-limiting / throttling on the server-side.
 // Authorization and billing can also be performed at the store_id level.
 string store_id = 1;

 // A key_prefix is a string of characters at the beginning of the key. Prefixes can be used as
 // a way to organize key-values in a similar way to directories.
 //
 // If key_prefix is specified, the response results will be limited to those keys that begin with
 // the specified prefix.
 //
 // If no key_prefix is specified or it is empty (""), all the keys are eligible to be returned in
 // the response.
 optional string key_prefix = 2;

 // page_size is used by clients to specify the maximum number of results that can be returned by
 // the server.
 // The server may further constrain the maximum number of results returned in a single page.
 // If the page_size is 0 or not set, the server will decide the number of results to be returned.
 optional int32 page_size = 3;

 // page_token is a pagination token.
 //
 // To query for the first page of ListKeyVersions, page_token must not be specified.
 //
 // For subsequent pages, use the value that was returned as `next_page_token` in the previous
 // page's ListKeyVersionsResponse.
 optional string page_token = 4;
}

message ListKeyVersionsResponse {

 // Fetched keys and versions.
 // Even though this API reuses KeyValue struct, the value sub-field will not be set by the server.
 repeated KeyValue key_versions = 1;
@G8XSUG8XSUDec 22, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

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

Consider: creating a separate struct for KeyVersion instead of re-using KeyValue struct here.
@devrandomdevrandomDec 22, 2022

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

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

I would say here explicitly that the value will be empty. I think it's OK to reuse the struct.

 // next_page_token is a pagination token, used to retrieve the next page of results.
 // Use this value to query for next_page of paginated ListKeyVersions operation, by specifying
 // this value as the `page_token` in the next request.
 //
 // If next_page_token is empty (""), then the "last page" of results has been processed and
 // there is no more data to be retrieved.
 //
 // If next_page_token is not empty, it does not necessarily mean that there is more data in the
 // result set. The only way to know when you have reached the end of the result set is when
 // next_page_token is empty.
 //
 // Caution: Clients must not assume a specific number of key_versions to be present in a page for
 // paginated response.
 optional string next_page_token = 2;

 // global_version is a sequence-number/version of the whole store.
 //
 // global_version is only returned in response for the first page of the ListKeyVersionsResponse
 // and is guaranteed to be read before reading any key-versions.
 //
 // In case of refreshing the complete key-version view on the client-side, correct usage for
 // the returned global_version is as following:
 // 1. Read global_version from the first page of paginated response and save it as local variable.
 // 2. Update all the key_versions on client-side from all the pages of paginated response.
 // 3. Update global_version on client_side from the local variable saved in step-1.
 // This ensures that on client-side, all current key_versions were stored at global_version or later.
 // This guarantee is helpful for ensuring the versioning correctness if using the global_version
 // in PutObject API and can help avoid the race conditions related to it.
 optional int64 global_version = 3;
}

// When HttpStatusCode is not ok (200), the response `content` contains a serialized ErrorResponse
// with the relevant ErrorCode and message
message ErrorResponse {
Expand Down