How to Specs: Outside and Inside Views Josh Larson @mutatedshrimp
Software Has Two Sides
Software Has Two Sides
Software Has Two Sides An Inside
Software Has Two Sides An Inside And An Outside
Software Has Two Sides An Inside How it works And An Outside
Software Has Two Sides An Inside How it works And An Outside What it does
Reflected In Code Organization Inside Outside
Reflected In Code Organization Inside (/src) Outside
Reflected In Code Organization Inside (/src) Outside public static int[] factorize(int input) { int[] result = []; for(int fact = 2; input > 1; fact++) { while(input % fact == 0) { result.add(fact); } } return fact; }
Reflected In Code Organization Inside (/src) Outside (/test) public static int[] factorize(int input) { int[] result = []; for(int fact = 2; input > 1; fact++) { while(input % fact == 0) { result.add(fact); } } return fact; }
Reflected In Code Organization Inside (/src) public static int[] factorize(int input) { int[] result = []; for(int fact = 2; input > 1; fact++) { while(input % fact == 0) { result.add(fact); } } return fact; } Outside (/test) @Test public void testtwo() { assertequals([2], factorize(2)); } /*... */ @Test public void testthreefifty() { assertequals([2, 5, 5, 7], factorize(350); }
Reflected In System Architecture
Reflected In System Architecture
Reflected In System Architecture???
Reflected In System Architecture???
Reflected In System Architecture??? filter
Reflected In System Architecture??? filter map reduce
Reflected In System Architecture???!!! filter map reduce
Reflected In System Architecture???!!! filter map reduce
Reflected In System Architecture Frontend Backend???!!! filter map reduce
Reflected In System Architecture Frontend Backend???!!! filter map reduce Outside Inside
This all applies to specs, too!
Examples from the CoAP Spec https://tools.ietf.org/html/rfc7252
Context Interlude CoAP: Constrained Application Protocol Request/Response model Similar operations as HTTP Works over UDP Optimized for low-power devices
Context Interlude CoAP: Constrained Application Protocol Request/Response model Similar operations as HTTP Almost, but not entirely unlike. (https://tools.ietf. org/html/rfc7252#ref-hhgttg) Works over UDP Optimized for low-power devices
Context Interlude CoAP: Constrained Application Protocol Request/Response model Yes, the CoAP spec references the Hitchhiker s Guide to the Galaxy. Yes, this makes me very, very happy. Similar operations as HTTP Almost, but not entirely unlike. (https://tools.ietf. org/html/rfc7252#ref-hhgttg) Works over UDP Optimized for low-power devices
It doesn t make him happy though http://wallpoper.com/images/00/21/19/11/movie-hitchhikers-guide-to-the-galaxy_00211911.
Quiz Time!
Inside or Outside View? 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Ver T TKL Code Message ID +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Token (if any, TKL bytes)... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Options (if any)... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1 1 1 1 1 1 1 1 Payload (if any)... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 7: Message Format
Inside or Outside View? 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Ver T TKL Code Message ID +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Inside Token (if any, TKL bytes)... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Options (if any)... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1 1 1 1 1 1 1 1 Payload (if any)... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 7: Message Format
Inside View! This has all the trappings of an inside view! Details about how the UDP packet is laid out No context about what the Token, or TKL, or Options, etc, are Necessary for implementers Can be ignored by users
Inside or Outside View? Client Server Client Server CON [0xbc90] CON [0xbc91] GET /temperature GET /temperature (Token 0x71) (Token 0x72) +-----------------> +-----------------> ACK [0xbc90] ACK [0xbc91] 2.05 Content 4.04 Not Found (Token 0x71) (Token 0x72) "22.5 C" "Not found" <-----------------+ <-----------------+ Figure 7: Two GET Requests with Piggbacked Responses
Inside or Outside View? Client Server Client Server CON [0xbc90] CON [0xbc91] GET /temperature GET /temperature (Token 0x71) (Token 0x72) +-----------------> +-----------------> Outside ACK [0xbc90] ACK [0xbc91] 2.05 Content 4.04 Not Found (Token 0x71) (Token 0x72) "22.5 C" "Not found" <-----------------+ <-----------------+ Figure 7: Two GET Requests with Piggbacked Responses
Outside View! Shows two use cases Shows some examples of responses that can come back from a GET request
Outside View! Shows two use cases Shows some examples of responses that can come back from a GET request Shows tokens and message ID s and CON/ACK s
Outside View! Shows two use cases Shows some examples of responses that can come back from a GET request Shows tokens and message ID s and CON/ACK s? Let s look again
Inside or Outside? Client Server Client Server CON [0xbc90] CON [0xbc91] GET /temperature GET /temperature (Token 0x71) (Token 0x72) +-----------------> +-----------------> ACK [0xbc90] ACK [0xbc91] 2.05 Content 4.04 Not Found (Token 0x71) (Token 0x72) "22.5 C" "Not found" <-----------------+ <-----------------+ Figure 7: Two GET Requests with Piggbacked Responses
This View Is Mixed Outside Sample Interactions Request Methods Response Codes Inside Message Details Tokens Message ID s
An Outside View Is One That a User Might Care About
Outside CoAP Views Methods are GET, POST, PUT, and DELETE GET does and guarantees POST does and doesn t promise Response codes look like 2.05 or 4.04, and they mean
Advanced Outside CoAP Views CON guarantees acknowledgement of receipt, even if a response is slow. That acknowledgement comes in the form of an ACK. NON does not have that guarantee.
An Inside View Is One That An Implementer Needs, But a User Can Ignore
Inside CoAP Views Bits 8-15 determine the code. For instance 10000100 means Not Found, and 00000011 is a PUT request. On sending a CON, the sender must resend, using exponential back-off, until it receives an ACK with the same message ID (bits 16-31), or until some timeout is reached. On receiving a repeat CON (repeat determined by the message ID), the receiver must not re-apply the command, but must send the same response it sent the first time.
Inside or Outside? On receipt of a CON, if handling the request is fast, the receiver may send the response message inside the ACK, rather than sending the response as a separate message. Client Server Client Server CON/GET CON/GET +------> versus +------> ACK ACK/205 <------+ <------+ CON/205 <------+ ACK +------>
Inside or Outside? On receipt of a CON, if handling the request is fast, the receiver may send the response message inside the ACK, rather than sending the response as a separate message. Client Server Client Server CON/GET Inside CON/GET +------> versus +------> ACK ACK/205 <------+ <------+ CON/205 <------+ ACK +------>
Inside Views... Include Optimizations That CoAP can Piggyback responses is an optimization. It does not impact how the end-user will use the protocol at all.
Proposal: In Any Spec, Put All of the Inside View Material First
What Would the CoAP Spec look like?
CoAP Spec The Outside View: Request/Response Model: The requests are GET, etc For a GET, you must provide a URI, and optionally, you may provide The valid responses to a GET request are If you are an expert user, you may want to avoid bandwidth and send messages as NON instead of CON.
At This Point, The One Using a CoAP Library Can Stop Reading
CoAP Spec, Continued... Bytes 8-16 signify the request or response code. Valid values are:...and the rest +------+--------+-----------+ Code Name Reference +------+--------+-----------+ 0.01 GET [RFC7252] 0.02 POST [RFC7252] 0.03 PUT [RFC7252] 0.04 DELETE [RFC7252] +------+--------+-----------+
Questions?