Added docs. Added getters with defaults.

Author: dim

doc.go

@@ -0,0 +1,59 @@
+// Copyright (c) 2013 Black Square Media Ltd. All rights reserved.
+// (The MIT License)
+
+// Permission is hereby granted, free of charge, to any person obtaining
+// a copy of this software and associated documentation files (the
+// 'Software'), to deal in the Software without restriction, including
+// without limitation the rights to use, copy, modify, merge, publish,
+// distribute, sublicense, and/or sell copies of the Software, and to
+// permit persons to whom the Software is furnished to do so, subject to
+// the following conditions:
+
+// The above copyright notice and this permission notice shall be
+// included in all copies or substantial portions of the Software.
+
+// THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+// IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+// CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+// TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+/*
+This package implements a parser (with optional validation) and a generator for
+OpenRTB 2.1 requests and responses.
+
+Spec
+
+http://www.iab.net/media/file/OpenRTB-API-Specification-Version-2-1-FINAL.pdf
+
+Usage
+
+  // Handle a HTTP request
+  http.HandleFunc("/bid", func(w http.ResponseWriter, r *http.Request) {
+    defer r.Body().Close()
+
+    req, err := openrtb.ParseRequest(r.Body(), true)
+    if err != nil {
+      log.Println("ERROR %s", err.Error())
+    } else {
+      log.Println("INFO  Received bid request %s", *req.Id)
+    }
+
+    w.WriteHeader(204) // respond with 'no bid'
+  })
+
+Implemented
+
+- Request parsing
+- Most objects
+- PMP additions
+
+Todo
+
+- Response parsing
+- Generating request and responses
+- Content objects
+*/
+package openrtb

openrtb.go

@@ -111,6 +111,22 @@ type Banner struct {
 	Ext      Extensions
 }
 
+// Returns topframe status, with default fallback
+func (b *Banner) IsTopFrame() bool {
+	if b.Topframe != nil {
+		return *b.Topframe == 1
+	}
+	return false
+}
+
+// Returns the position, with default fallback
+func (b *Banner) Position() int {
+	if b.Pos != nil {
+		return *b.Pos
+	}
+	return AD_POS_UNKNOWN
+}
+
 // The "video" object must be included directly in the impression object if the impression offered
 // for auction is an in-stream video ad opportunity.
 type Video struct {
@@ -137,6 +153,30 @@ type Video struct {
 	Ext            Extensions
 }
 
+// Returns the sequence number, with default fallback
+func (v *Video) Seq() int {
+	if v.Sequence != nil {
+		return *v.Sequence
+	}
+	return 1
+}
+
+// Returns the boxing permission status, with default fallback
+func (v *Video) IsBoxingAllowed() bool {
+	if v.Boxingallowed != nil {
+		return *v.Boxingallowed == 1
+	}
+	return true
+}
+
+// Returns the position, with default fallback
+func (v *Video) Position() int {
+	if v.Pos != nil {
+		return *v.Pos
+	}
+	return AD_POS_UNKNOWN
+}
+
 // A site object should be included if the ad supported content is part of a website (as opposed to
 // an application).  A bid request must not contain both a site object and an app object.
 type Site struct {
@@ -156,6 +196,14 @@ type Site struct {
 	Ext      Extensions
 }
 
+// Returns the privacy policy status, with default fallback
+func (s *Site) IsPrivacyPolicy() bool {
+	if s.Privacypolicy != nil {
+		return *s.Privacypolicy == 1
+	}
+	return false
+}
+
 // An "app" object should be included if the ad supported content is part of a mobile application
 // (as opposed to a mobile website).  A bid request must not contain both an "app" object and a
 // "site" object.
@@ -177,6 +225,22 @@ type App struct {
 	Ext      Extensions
 }
 
+// Returns the privacy policy status, with default fallback
+func (a *App) IsPrivacyPolicy() bool {
+	if a.Privacypolicy != nil {
+		return *a.Privacypolicy == 1
+	}
+	return false
+}
+
+// Returns the paid status, with default fallback
+func (a *App) IsPaid() bool {
+	if a.Paid != nil {
+		return *a.Paid == 1
+	}
+	return false
+}
+
 // This object may be useful in the situation where syndicated content contains impressions and
 // does not necessarily match the publisher’s general content.  The exchange might or might not
 // have knowledge of the page where the content is running, as a result of the syndication
@@ -230,6 +294,38 @@ type Device struct {
 	Ext            map[string]string
 }
 
+// Returns the DNT status, with default fallback
+func (d *Device) IsDnt() bool {
+	if d.Dnt != nil {
+		return *d.Dnt == 1
+	}
+	return false
+}
+
+// Returns the JS status, with default fallback
+func (d *Device) IsJs() bool {
+	if d.Js != nil {
+		return *d.Js == 1
+	}
+	return false
+}
+
+// Returns the connection type, with default fallback
+func (d *Device) ConnectionType() int {
+	if d.Connectiontype != nil {
+		return *d.Connectiontype
+	}
+	return CONN_TYPE_UNKNOWN
+}
+
+// Returns the connection type, with default fallback
+func (d *Device) DeviceType() int {
+	if d.Devicetype != nil {
+		return *d.Devicetype
+	}
+	return DEVICE_TYPE_UNKNOWN
+}
+
 // Note that the Geo Object may appear in one or both the Device Object and the User Object.
 // This is intentional, since the information may be derived from either a device-oriented source
 // (such as IP geo lookup), or by user registration information (for example provided to a publisher

openrtb_test.go

@@ -0,0 +1,66 @@
+package openrtb
+
+import (
+	"github.com/stretchr/testify/assert"
+	"testing"
+)
+
+func TestBanner_IsTopFrame(t *testing.T) {
+	b := &Banner{}
+	assert.Equal(t, b.IsTopFrame(), false)
+}
+
+func TestBanner_Position(t *testing.T) {
+	b := &Banner{}
+	assert.Equal(t, b.Position(), 0)
+}
+
+func TestVideo_Seq(t *testing.T) {
+	v := &Video{}
+	assert.Equal(t, v.Seq(), 1)
+}
+
+func TestVideo_IsBoxingAllowed(t *testing.T) {
+	v := &Video{}
+	assert.Equal(t, v.IsBoxingAllowed(), true)
+}
+
+func TestVideo_Position(t *testing.T) {
+	v := &Video{}
+	assert.Equal(t, v.Position(), 0)
+}
+
+func TestSite_IsPrivacyPolicy(t *testing.T) {
+	s := &Site{}
+	assert.Equal(t, s.IsPrivacyPolicy(), false)
+}
+
+func TestApp_IsPrivacyPolicy(t *testing.T) {
+	a := &App{}
+	assert.Equal(t, a.IsPrivacyPolicy(), false)
+}
+
+func TestApp_IsPaid(t *testing.T) {
+	a := &App{}
+	assert.Equal(t, a.IsPaid(), false)
+}
+
+func TestDevice_IsDnt(t *testing.T) {
+	d := &Device{}
+	assert.Equal(t, d.IsDnt(), false)
+}
+
+func TestDevice_IsJs(t *testing.T) {
+	d := &Device{}
+	assert.Equal(t, d.IsJs(), false)
+}
+
+func TestDevice_ConnectionType(t *testing.T) {
+	d := &Device{}
+	assert.Equal(t, d.ConnectionType(), 0)
+}
+
+func TestDevice_DeviceType(t *testing.T) {
+	d := &Device{}
+	assert.Equal(t, d.DeviceType(), 0)
+}

parser.go

@@ -3,6 +3,7 @@ package openrtb
 import (
 	"encoding/json"
 	"errors"
+	"io"
 )
 
 var (
@@ -19,26 +20,37 @@ var (
 	errValidationVideoProtocol    = errors.New("openrtb parse: video protocol missing")
 )
 
-// Parses a raw JSON byte array into a standard-compliant
-// OpenRTB Request struct
-func ParseRequest(rawJson []byte, validate bool) (req *Request, err error) {
-	if err = json.Unmarshal(rawJson, &req); err != nil {
+// Parses an OpenRTB Request struct from an io.Reader
+// Optionally validates and applies defaults to the Request object (recommended)
+func ParseRequest(reader io.Reader, validate bool) (req *Request, err error) {
+	dec := json.NewDecoder(reader)
+	if err = dec.Decode(&req); err != nil {
 		return nil, err
 	}
+	return processReq(req, validate)
+}
 
-	if validate {
-		err = validateReq(req)
+// Parses an OpenRTB Request from bytes
+// Optionally validates and applies defaults to the Request object (recommended)
+func ParseRequestBytes(data []byte, validate bool) (req *Request, err error) {
+	if err = json.Unmarshal(data, &req); err != nil {
+		return nil, err
 	}
+	return processReq(req, validate)
+}
 
-	if err != nil {
-		return nil, err
+// ------------------- Request Helpers ----------------------
+
+func processReq(req *Request, validate bool) (*Request, error) {
+	if validate {
+		if err := validateReq(req); err != nil {
+			return nil, err
+		}
 	}
 
 	return req, nil
 }
 
-// ------------------- Validation Helpers ----------------------
-
 func validateReq(req *Request) error {
 
 	// Validations
@@ -151,18 +163,10 @@ func validateVideo(video *Video) error {
 		video.Boxingallowed = new(int)
 		*video.Boxingallowed = 1
 	}
-	if video.Boxingallowed == nil {
-		video.Boxingallowed = new(int)
-		*video.Boxingallowed = 1
-	}
 	if video.Pos == nil {
 		video.Pos = new(int)
 		*video.Pos = AD_POS_UNKNOWN
 	}
-	if video.Startdelay == nil {
-		video.Startdelay = new(int)
-		*video.Startdelay = VIDEO_START_DELAY_PRE_ROLL
-	}
 
 	return nil
 }

parser_test.go

@@ -1,24 +1,25 @@
 package openrtb
 
 import (
+	"bytes"
 	"github.com/stretchr/testify/assert"
 	"testing"
 )
 
-func TestParseRequest_BlankUnvalidated(t *testing.T) {
-	req, err := ParseRequest([]byte("{}"), false)
+func TestParseRequestBytes_BlankUnvalidated(t *testing.T) {
+	req, err := ParseRequestBytes([]byte("{}"), false)
 	assert.Nil(t, err)
 	assert.IsType(t, &Request{}, req)
 }
 
-func TestParseRequest_BlankValidated(t *testing.T) {
-	req, err := ParseRequest([]byte("{}"), true)
+func TestParseRequestBytes_BlankValidated(t *testing.T) {
+	req, err := ParseRequestBytes([]byte("{}"), true)
 	assert.Nil(t, req)
 	assert.Equal(t, err.Error(), "openrtb parse: request ID missing")
 }
 
-func TestParseRequest_SimpleBanner(t *testing.T) {
-	req, err := ParseRequest(simpleBanner, true)
+func TestParseRequestBytes_SimpleBanner(t *testing.T) {
+	req, err := ParseRequestBytes(simpleBanner, true)
 	assert.Nil(t, err)
 	assert.IsType(t, &Request{}, req)
 
@@ -37,8 +38,8 @@ func TestParseRequest_SimpleBanner(t *testing.T) {
 	assert.Equal(t, *req.User.Buyeruid, "5df678asd8987656asdf78987654")
 }
 
-func TestParseExpandableCreative(t *testing.T) {
-	req, err := ParseRequest(expandableCreative, true)
+func TestParseRequestBytes_ExpandableCreative(t *testing.T) {
+	req, err := ParseRequestBytes(expandableCreative, true)
 	assert.Nil(t, err)
 	assert.IsType(t, &Request{}, req)
 
@@ -53,6 +54,12 @@ func TestParseExpandableCreative(t *testing.T) {
 	assert.Equal(t, *req.User.Data[0].Segment[2].Id, "23423424")
 }
 
+func TestParseRequest_ExpandableCreative(t *testing.T) {
+	req, err := ParseRequest(bytes.NewBuffer(expandableCreative), true)
+	assert.Nil(t, err)
+	assert.IsType(t, &Request{}, req)
+}
+
 var simpleBanner []byte = []byte(`
 {
   "id":"1234534625254",