Field-Limits

From The Socknet

Important: For this doc to apply, a function's spec has to indicate that this doc applies. If every function used field-limits, then every call to a function would need to be preceded by a call to this function.

Some functions store data and of course care must be taken that the data to be stored will fit in the space allotted by the provider. In normal use, String or object fields can be assumed to hold at least 255 characters. For greater character counts, this system enables length-limit discovery.

Contents 1 The Function 2 Data Types 2.1 String 2.2 Number 2.3 Boolean 2.4 Object 2.5 Undefined Field Type 2.6 Arrays 3 Considerations

The Function

Object fields are typically stored as JSON bytes and may contain any valid JSON data. The length of all fields may be checked via a call to the field-limits function. Results follow the pattern exemplified by this partial call inquiring about service-register:

POST field-limits
{ function: "service-register"
}

->
{ from: {
	protocols: {
			"*": { public_data: 4096 }
	           }
 	}
}

When calling, it is necessary to already be familiar with the structure of the function queried because the results do not define or explain the structure of the request object, they only tell limits.

Any part of the structure that is of variable type (may contain string, object, number or boolean) will be considered non-entrant. For example in the service-register function, the public_data field may hold anything, so no information is given about the insides of that field, only about the entire field.

The "*" shown matches any field. Try not to name custom fields with a *, you'll confuse people.

Data Types

The meaning of the values given by this function is slightly different depending on the type of data that the field is intended to hold. If a field does not hold the right data type, then the function should fail, so the number would be irrelevant.

String

If a field holds a String the number indicates that the string itself (ie, excluding escapes and quotes) must have character length less than or equal to the amount given. This is irrespective of the number of bytes required to hold a given character. (This rule should be revisited.)

Number

If the field holds a number, the number should be treated as a string.

Boolean

If the field holds a boolean, the field-limit really isn't necessary, because booleans can fit in any space with at least one bit.

Object

When a field holds an object, the number given indicates the maximum byte-count for the JSON form of that object. JSON is always in UTF-8, therefore the byte-count is equal to the character-count.

Undefined Field Type

If the type that the field should hold is allowed to be any type, then the field acts like an object for the purposes of this function.

Arrays

The treatment of arrays is implied by the rest of the rules.

If the field in the response contains a number, then the array is treated like an object.

If the field in the response contains an array with exactly one number, then it indicates the limit for items that are in the array. Each item must follow the rules for the expected datatype.

Considerations

Any field which is stored as JSON bytes will be processed and then reJSON'd by the receiving party (at least for security reasons) before being stored. It may have extra whitespace squeezed out of it at that time. When a call is made, it is the receiver's job to address extra whitespace, if the data doesn't already fit where it belongs. It is the sender's job to ensure that the data could fit in the byte-count indicated when the whitespace is squeezed out. (That's right, everybody has a job.)

In the event that a message is unstorable due to excess bytes, an error will be given, such as:

->
{ error: { title: "Unstorable data length",
           explanation: "some text that mentions the data field's name",
           code: ###
         }
}