Category Archives: software development

RFC: HTTP status 462 (Out For Lunch)

Posted on by
1 
Independent Submission                                   Marko Oikarinen
Request for Comments: 79O6                                     Sysart Oy
Category: Informational                                     1 April 2016 


   The Hypertext Transfer Protocol Status Code 462 (Out For Lunch)


Abstract

   This document specifies a Hypertext Transfer Protocol (HTTP) status
   code for use when a human-backed server resource is unavailable as a
   consequence of said human participating in a process of consuming
   nutritional substances.

Status of This Memo

   This Internet-Draft is not submitted.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF). Note that other groups may also distribute working
   documents as Internet-Drafts. The list of current Internet-Drafts is
   at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time. It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on April 1, 2017.

Copyright Notice

   Copyright (c) 2016 The persons identified as the document authors.  
   No rights reserved.

Table of Contents

   1. Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2. Requirements  . . . . . . . . . . . . . . . . . . . . . . . .   2
   3. 462 Out For Lunch . . . . . . . . . . . . . . . . . . . . . .   3
   4. Security Considerations . . . . . . . . . . . . . . . . . . .   4
   5. International Considerations  . . . . . . . . . . . . . . . .   5
   6. References  . . . . . . . . . . . . . . . . . . . . . . . . .   6
   7. Appendix A. Acknowledgements .  . . . . . . . . . . . . . . .   6
   8. Author's Address  . . . . . . . . . . . . . . . . . . . . . .   6

1. Introduction

   This document specifies a Hypertext Transfer Protocol (HTTP) status
   code for use when a server operation internally utilizes a resource
   implemented in flesh and bone and said resource is currently having
   lunch or is in a post-lunch RESTful state, therefore unable to 
   provide the required resource, thus forcing the server to deny 
   access to the resource or to a set of resources which includes the
   requested resource.

   This status code can be used to provide transparency in circumstances
   where service availability may affect client operations. This
   transparency may be beneficial to end users.

2.  Requirements

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "APRIL", "FOOL", and "DESSERT" in this
   document are to be interpreted as described in [RFC2119]. 

3. 462 Out For Lunch

   This status code indicates that the server is denying access to the
   resource as a consequence of a required human dependency having
   lunch. This status code is not to be confused with status code 
   "461 Out To Lunch" which has to do with server behavior under the 
   influence of cosmic rays when financial considerations have made the
   administrator decide against investing in error-correcting (ECC)
   server random access memory. 

   A human backed resource may be manifested in ways including but not
   limited to: a senior dead-tree archive manager, a microfilm squinter,
   an adidas conveyor, a ticket pusher or a ticket dodger or a
   Just-In-Time (JIT) backend feature developer.

4. Security Considerations

   Server resources addressed with the "coffee:" URI scheme as specified
   in RFC2324 MUST NOT return status code 462, as a HTCPCP/1.0 (Hyper
   Text Coffee Pot Control Protocol) device is expected to be autonomous
   and not utilize humans in its implementation. Such HTTP responses are
   to be considered potentially malicious.

   Clients cannot rely upon the use of the 462 status code. It is
   possible that certain resources utilized by the server might wish to
   avoid transparency, and not disclose that they have left the premises
   in order to dine at the local gentlemen's club.

5. International Considerations

   The use of the 462 status code implies temporary unavailability of
   the resource named in the request. It is expected that a later
   request for the resource may succeed if the resource has recovered
   from the digestive condition.

   When an attempt to access a resource fails with status 462, it is to
   be expected that the recovery time of the server is highly locale
   dependent. In a worst case scenario the situation might involve a six
   course meal with DESSERT and a post-nourishment RESTful period also
   known as a siesta.

6. References

6.1. Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              .

   [RFC2324]  L. Masinter, "Hyper Text Coffee Pot Control Protocol
              (HTCPCP/1.0)", RFC 2324,  1 April 1998,
              .

7. Appendix A.  Acknowledgements

   This document was inspired by RFC 7725 by Tim Bray and borrows some 
   phrases from it with minor adaptations.

8. Author's Address  

   Marko Oikarinen
   Twitter: @whoman4says
   Blog: https://scribblelayer.com/
   Employer: http://sysart.fi/
Advertisement

Enterprise DevOps

Posted on by
Reply

I type the program arguments into an Excel sheet. I write a short description of what I am trying to accomplish. I send the description and the Excel sheet to a person that has access rights to the ticketing system. Repeat three times. The next day she reads my emails and submits the three tickets.

The three tickets get assigned to three persons in a country where work used to be cheaper than here. They type the program arguments from the Excel sheet into the scripts that will run the programs. They mark the tickets resolved. Corporate metrics show exemplary ticket handling response times.

Next week another ticket gets resolved and a tester gets access rights to the system. She runs a test case for my use case. It doesn’t work. I request access to the log files from the server admin. Next day I have the logs and find out that the second script failed to trigger the third script due to file access rights. No problem, that is easy to fix.

I write a short description of what I am trying to accomplish. I send the description with an Excel sheet to a person that has access rights to the ticketing system. I realize that this is state of the art in Enterprise DevOps in 2016.

Scribble Layer – beyond the model

Posted on by
Reply

In the fall of 2010 we at Sysart organized a small conference at Helsinki and Oulu. Daniel Wellner and I did our presentation on how to keep the domain model unambiguous. Jimmy Nilsson was the featured guest and talked about building a domain model.

In his presentation Jimmy said something that caught my ear: “The user should be able to save invalid data“. The concept is explained in chapter 7 of his book Applying Domain-Driven Design and Patterns. The book says: “All States, Even When in Error, Should be Savable”. The idea is simple but not widely applied – when a user cannot complete all the required information the application should still allow saving the partial work he or she has done.

The concept stuck in my mind. Every now and then a situation comes up where this idea seems to fit. Think of a doctor entering a diagnosis into a patient care application. A diagnosis entry form might contain a dozen fields. It would seem useful that the doctor could enter just the most important data while with the patient, save the entry and complete it later. But applications tend to be too eager and demand everything to be completely valid on first save.

Then I stumbled upon StaffPad. StaffPad is an application for writing music. Writing music. Not typing, not mousing around. Writing music the old-fashioned way, with a pen. As a songwriter I was immediately intrigued. Could this application make notating random ideas into a computer feasible for me? I always preferred pen and paper because I disliked the input methods in all the music applications I tried.

Staffpad

StaffPad

The pen works really well for entering notes, rests and other symbols. But what happens when StaffPad does not recognise your writing? It applies Jimmy’s advice and saves the unrecognized strokes as part of the page. If you print the score, the mystery symbols are not discarded, they get printed too. A human can read and play the scribbles assuming your handwriting is legible. The only thing StaffPad cannot do is play the notes because the meaning of the unrecognized strokes is a mystery to the application.

This is good, but StaffPad takes it a step further. Sometimes the user wants to express something that can not be codified in the domain model. Western musical notation has a huge amount of symbols and it is not feasible to implement all of them in an application. StaffPad has a clever way around this problem: an extra layer (think Photoshop layers) on top of the notation where you can draw whatever you like. A scribble layer. You can jot down obscure electric guitar performance symbols or draw a picture of your favorite game character. The layer is domain-aware – it intelligently attaches to bars, and is formatted into each musicians parts on printouts.

Staffpad-scribble-layer

Is this idea of a separate unstructured layer placed on top of the model presentation useful in other applications? I sure would like to annotate source code with small drawings in my IDE and have them follow the source anywhere it goes. Do you know applications that implement a similar idea?

Links:

 

Garbage in – default out?

Posted on by
Reply

We were freshly into production with this system that had a lot of moving parts. The whole system consisted of several big monolithic applications and half a dozen newer microservice-style services integrated into a “living organism”.

A user was not getting the results she expected. We investigated the problem and found out that a service we were calling was not returning some of the data we were interested in. In particular, data older than three months was not seen by us. A support person for the service said: ‘you should use wide search if you want to see the older items’. But wait – we were using wide search, always had been!

I double-checked the code and sure enough, it did say widesearch=”true”. Strange. So I blew the dust off the API spec and found this: widesearch=”1|0”. Yikes, the value should be a number! And I had coded this, totally my bad. I guess I’ve grown too used to using true and false for boolean values in XML. We were a month into production when we found out we were not using wide search. Never had been!  

Why did we not get an error when we called the service with bad parameters? 1 and 0 look like numbers to me, but the service had been happily accepting the string “true” all along. I decided to run a little experiment against the service in the test environment: 

<request key="..." widesearch=”anything goes?” />
   → 
<response>OK ...valid search results...</response>.

Okay, so it seems there is no validation of the parameter whatsoever. The code probably reads something like this: 

if("1".equals(request.attr("widesearch")) ...

Why did we not find this bug during testing? This integration point was hammered a lot because during the project there were a lot of version updates on both sides of the API fence. Before going into production, the integration was in use for at least half a year in the testing environment. Somehow we just managed to not hit the three-month limit. For us ‘widesearch’ was just a mandatory constant we had to set in the API, not a thing that would be interesting to test.

Now, imagine that the service actually checked that the parameters in the API call have correct data types. We would have found our bug on day one of testing. Actually earlier – the first time we tried to call the test service. Silently choosing a default when the input is garbage does a big disservice to making the whole system robust.

When computers talk to computers it is better to be strict in the protocol. Problems get flushed out way quicker.

Large systems… designed?!?

Posted on by
Reply

In his excellent talk on DDD & Microservices Eric Evans had a slide that said “Not all of a large system will be well designed”. Yes, that does match my experience with software systems very well. However, I originally misread the sentence as “Not all large systems will be designed”. I think the misread version sounds true too. I can certainly state with confidence that “not all large systems were designed”. That is because they just happened 🙂

Stackoverflow.com is great but … always RTFM

Posted on by
Reply

Back in the good (?!?) old days of C++ and WinAPI … I was reviewing this bit of code. There was a Windows API call to some registry manipulation function. The next line was an identical call to the exact same function with the exact same parameters and a comment /*this must be here*/. Whaaat?

A quick peek to the MSDN documentation and it was immediately obvious: “oh, he’s disregarding the out-parameter and the return value”. The developer had not read the documentation and therefore did not understand how the API worked.

This was the day I realized not all developers read the documentation of the libraries and tools they use. Sometimes people just fiddle with it until it works… or at least seems to work. Since then I’ve encountered lots of examples of hack-it-until-it-obeys gone wrong. Sometimes you see very strange and unnecessarily complex log4j or log4net configuration files due to the writer not understanding the logger hierarchy and how appenders relate to it.

When I use a tool that is new to me, I like to try to get my mental model aligned with the tool developers. Usually you can get the big picture by reading just the introductory chapters of the manual.

Libraries can also hide nasty surprises buried deep in the documentation. Like this bit from the jQuery css()-method:

“When a number is passed as the value, jQuery will convert it to a string and add px to the end of that string.”

Except, it is not really buried very deep. It is the third paragraph in the method description. I do not tend to read API documentation front to back like a book but anytime I use a method I have not used before, I like to see what the API developers had to say about it.

Browsing the documentation can also give you positive surprises. Fast forward to the land of C# in 2015. I was reviewing some ASP.NET MVC code together with the team member who wrote it. It looked alright to me. The code was using System.Web.Mvc.OutputCacheAttribute.

[HttpGet]
[OutputCache(Duration = 8*3600)] /* 8 hours */
public ActionResult GetCoolStuff() { … }

I said: “Looks OK to me… … … BTW, have you used this cache thing before? Have you read the API docs?”
“err… no.”
“Well, let’s go see if we find anything useful.”

No need to wade through all the methods & properties, ‘remarks’ is where the important stuff is. In this case we found this sentence: “To avoid code duplication, you can set a cache profile in the Web.config file instead of setting cache values individually in pages.” Hey, if we use that we can change the cache invalidation time on the fly.

[HttpGet]
[OutputCache(CacheProfile = "CoolStuffOutputCache")]
public ActionResult GetCoolStuff() { … }

It took us all of 2 minutes to browse to MSDN and read the remarks section of the OutputCache class. We gained the ability to change the cache settings on the fly. The original version would have needed a recompile if we wanted to change the cache invalidation time.

Known your tools. Stackoverflow is awesome but to really know your way around you must Read The Fine Manual.