doc

Protocol Documentation

Table of Contents

• uggly.proto

  • Cookie

  • DivBox

  • DivBoxes

  • DivScroll

  • Elements

  • FeedRequest

  • FeedResponse

  • Form

  • FormActivation

  • FormData

  • KeyStroke

  • Link

  • PageListing

  • PageRequest

  • PageResponse

  • Style

  • TextBlob

  • TextBox

  • TextBoxData

  • Cookie.SameSite

  • Feed

  • Page

• Scalar Value Types

Top

uggly.proto

Cookie

Cookie loosly follows the cookie spec (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie) but does not include protections for browser side code as today the uggly spec does not support client side code.

Field	Type	Label	Description
key	string		standard key or field name of cookie
value	string		standard value of cookie
server	string		the server which requested this cookie to be set. should be server only without including port e.g., "localhost" or "mysubdomain.domain.com"
private	bool		private Cookies will never be sent back to server
expires	string		date when cookie expires relative to client in RFC1123 format. If improperly formatted will just be ignored and cookie will be treated as session cookie.
sameSite	Cookie.SameSite		information on whether this cookie should only be sent to the server that requested it
page	string		if this cookie should only be sent back on specific pages
secure	bool		if this cookie should only be sent when connection is secure
metadata	bool		indicates that this cookie should be sent in header metadata instead of body. This is useful if the server wants to pre-filter traffic, for example if a request is not authenticated it can avoid processing the full PageRequest

DivBox

DivBox is a core element of the protocol. No content can exist outside of a DivBox. It requires that some basic properties are included such as fill and border geometry but the rawContents property is open to fill with whatever content is desired.

Field	Type	Label	Description
name	string		the name of the divBox. Used when attaching TextBlobs and forms
border	bool		whether the div should add a border
borderW	int32		the width of the border, will stay inside the stated overall dimensions and work its way inward
borderChar	int32		The character to use as a border character (e.g., "#") but represented as rune For example, in Python this would be 'ord("#")' and Go it would be []rune("#")[0]
fillChar	int32		if the DivBox should be filled with a char as a texture. Follows same rune rules as borderChar.
startX	int32		position on the X axis where the box should start
startY	int32		position on the Y axis where the box should start
width	int32		overall width of the box
Height	int32		overall height of the box
borderSt	Style		style to use when rendering border char
fillSt	Style		style to use when rendering fill char

DivBoxes

DivBoxes is an array of DivBox

Field	Type	Label	Description
boxes	DivBox	repeated

DivScroll

If a KeyStroke is of type DivScroll then this contains information about which DivBox to scroll and whether or not the direction is down = true or down = false (e.g., 'up')

WARNING: Not currently implemented in 'uggly-client'

Field	Type	Label	Description
divName	string
down	bool

Elements

Elements contains all non-DivBox related content that could be included in a PageResponse. Right now this contains TextBlobs and Forms but will be used for future elements if needed. For example, if determined that clients should handle all Table rendering in the future or something. Right now tables would have to be stick built by the server using DivBoxes and TextBlobs

Field	Type	Label	Description
textBlobs	TextBlob	repeated
forms	Form	repeated

FeedRequest

A FeedRequest really needs no properties as it's just a call from the client for the server to send a Feed if it has one.

Field	Type	Label	Description
sendData	bool		reserved for future use

FeedResponse

A FeedResponse is essentially a list of Pages that the server wishes to expose to the client. The server can obviously choose to hide some Pages or if it generates Pages dynamically it may not even be able to provide an accurate listing.

Field	Type	Label	Description
pages	PageListing	repeated
notes	string		reserved for future use

Form

The Form is sent by the server to the client as part of the PageResponse. It contains the Form name, the DivBox it should be placed within (TextBox PositionX and Y coordinates are relative to the containing DivBox) and a list of the TextBox's included in this form. It also supports a parameter for a Link that can be used as a return address when this Form is submitted in a PageRequest

Field	Type	Label	Description
name	string		The name of the form. This will be used in formActivation keystrokes and for atributing formData in PageRequests
divName	string		the DivName that the form should be rendered within. All of the elements of the form will be rendered relative to this divBox
textBoxes	TextBox	repeated	The textboxes to be included in this form
submitLink	Link		The link that this form will call when the form's submit action (e.g., 'enter') is triggered

FormActivation

If a KeyStroke is of type FormActivation then this contains the name of the form which should be activated for that keystroke

Field	Type	Label	Description
formName	string

FormData

FormData contains the form name and any TextBoxData that was in the form when the FormData was sent in the PageRequest

Field	Type	Label	Description
name	string
textBoxData	TextBoxData	repeated

KeyStroke

KeyStroke indicates an action that will be executed when the keyStroke is prssed by the client. This could be one of Link (e.g., new PageRequest), DivScroll (indicates the client should attempt to re-render textblobs that exceed their containing DivBox's capacity), or FormActivation which would look for a form with the given name on the client's current page.

Field	Type	Label	Description
keyStroke	string		a string representation of a key on a keyboard. For rune keys (e.g., "j") simply use the single character. For more complex keys refer to the string representation from the tcell package: https://github.com/gdamore/tcell/blob/master/key.go#L83

The client may have certain keys reserved that will never be honored. In the current "uggly-client" this includes: F1, F2, F3, F4, F5, F6, F7, and F10 | | link | Link | | | | divScroll | DivScroll | | | | formActivation | FormActivation | | |

Link

Link contains information about keyboard shortcuts and destinations for actions. The client will determine from context whether a Link is to a server page or is to be used to pass polling context to a Form that it already receieved in a PageResponse.

Field	Type	Label	Description
keyStroke	string		a repeat of the keystroke used in the parent KeyStroke TODO: not sure what happens if they don't match
pageName	string		the name of the page to be requested in the new PageRequest
server	string		the server to be used in the new PageRequest
port	string		the port to be used in the new PageRequest
secure	bool		whether or not the new PageRequest should be secure (TLS)
stream	bool		whether or not the new PageRequest is a stream

PageListing

A PageListing is basically a key/value pair of page name and an optional description. The client can choose to render this however it wants and the client injects it's own "links" to this content. This is a lazy way of exposing all the server's content without having to build nav menus and manage links

Field	Type	Label	Description
name	string
description	string

PageRequest

A PageRequest contains the name of the desired page and some metadata about the cient height and width. The server can choose to ignore the width and height if it insists on statically sized content. Also, the server could generate a PageResponse saying something like "this server insists on a minimum height to view content" for example.

Field	Type	Label	Description
name	string		The name of the page being requested
clientWidth	int32		The width of the client at the time of the request
clientHeight	int32		The height of the client at the time of the request
formData	FormData	repeated	data from form submissions or could be used to send generic key value pairs
server	string		the intended server for the request
port	string		the intended port for the request
secure	bool		whether or not the connection should be secure (TLS)
sendCookies	Cookie	repeated	Cookies that are intended to be sent from client to server
stream	bool		whether or not the request is for a page stream

PageResponse

The PageResponse contains modular content that the server wishes the client to display in the form of DivBoxes, Elements, and Links.

Field	Type	Label	Description
divBoxes	DivBoxes		divBoxes contains all of the divBoxes to be rendered for this page
elements	Elements		elements contains all of the non divBox elements to be rendered for this page
name	string		the name of the page to be rendered
keyStrokes	KeyStroke	repeated	a list of keystrokes that the client should honor, these could be of type link, formActivation, or divScroll
setCookies	Cookie	repeated	any cookies that the server is requesting the client to set for future requests
streamDelayMs	int32		if the response is part of a stream then this is the time in milliseconds the client should wait before drawing the next request

Style

Style is a base property used in divBox fill, border fill, and textboxes with fg being foreground color, bg being background color, and attr being text attributes like strikethrough and underline.

It's essentially a passthrough of the capabilities of tcell's style https://github.com/gdamore/tcell/blob/master/style.go

Field	Type	Label	Description
fg	string		a string representation of the color for the foreground (i.e., text)
bg	string		a string representation of the color for the background
attr	string		attr would be things like underline or bold if the client terminal supports it. Experimentation with this has proven that '4' is the only dependable value

TextBlob

TextBlob is a special kind of element that natively understands text blocks intended for human readability. Obviously it has a content property but also understands things like text style and text wrap when the text is larger than the width of the container it was assigned to.

A TextBlob can be assigned to multiple Divs in case you wanted to re-use text in multiple places for some reason.

Field	Type	Label	Description
content	string		The actual content. Could be almost any length but be aware of the size of the containing div.
wrap	bool		whether or not the text should wrap if it exceeds the width of it's divbox
style	Style
divNames	string	repeated	the divs this text should be attached to. Generally it's just one.

TextBox

TextBox contains the properties sent by the server for the client to render.

Field	Type	Label	Description
name	string		the name of this textBox. Will be used as the key in the key:value during submission
tabOrder	int32		the order in which this field will activate when user is tabbing through form fields
defaultValue	string		the default value that will be placed in the box
description	string		a description of the text box (e.g., "passwords should include special chars") which can optionally be drawn to the left of the textbox
positionX	int32		relative within DivBox
positionY	int32		relative within DivBox
height	int32		currently textBoxes only utilize a single line
width	int32		text that goes beyond the width will horozontially scroll to fit
styleCursor	Style		style for the cursor within the box. ForeGround color is meaningless
styleFill	Style		style for the box fill or background. Foreground and Background should probably match styleText so as not to clash
styleText	Style		style of the text that is being typed into box.
styleDescription	Style		style for the description that is rendered to the left of the box
showDescription	bool		whether or not to render the description. Design consideration: This will be rendered as far to the left of the textBox's positionX attribute as to fit the description.
password	bool		whether or not this field is a password, e.g, it's contents will be hidden while typing

TextBoxData

TextBoxData contains the text box's field name and whatever contents were in it when the PageRequest was sent with FormData

Field	Type	Label	Description
name	string
contents	string

Cookie.SameSite

Name	Number	Description
STRICT	0	cookie only sent to same site that set it
NONE	1	cookie can be sent cross site but only if Secure is set

Feed

Feed service can be implemented by the server and must provide a FeedResponse for a given FeedRequest. This is to be used as somewhat of a server index of available Pages when the server chooses to implement. It is strongly encouraged to implement a Feed because it makes for quality of life improvements for the client's user

Method Name	Request Type	Response Type	Description
GetFeed	FeedRequest	FeedResponse

Page

In order for a server to serve any content it must implement the Page service which returns PageResponse for a given PageRequest

Method Name	Request Type	Response Type	Description
GetPage	PageRequest	PageResponse
GetPageStream	PageRequest	PageResponse stream

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)