ducky/devices

     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/devices.go	Thu Nov 12 20:33:26 2015 -0800
     1.3 @@ -0,0 +1,209 @@
     1.4 +package devices
     1.5 +
     1.6 +import (
     1.7 +	"errors"
     1.8 +	"log"
     1.9 +	"time"
    1.10 +
    1.11 +	"golang.org/x/net/context"
    1.12 +
    1.13 +	"code.secondbit.org/uuid.hg"
    1.14 +)
    1.15 +
    1.16 +var (
    1.17 +	// ErrDeviceNotFound is returned when the specified device couldn't be found.
    1.18 +	ErrDeviceNotFound = errors.New("device not found")
    1.19 +)
    1.20 +
    1.21 +// Device represents a specific device that updates can be pushed to.
    1.22 +type Device struct {
    1.23 +	ID        uuid.ID
    1.24 +	Name      string
    1.25 +	Owner     uuid.ID
    1.26 +	Type      DeviceType
    1.27 +	Created   time.Time
    1.28 +	LastSeen  time.Time
    1.29 +	PushToken string
    1.30 +}
    1.31 +
    1.32 +// ApplyChange returns a Device that is a copy of the passed Device,
    1.33 +// but with the passed DeviceChange applied.
    1.34 +func ApplyChange(d Device, change DeviceChange) Device {
    1.35 +	result := d
    1.36 +	if change.Name != nil {
    1.37 +		result.Name = *change.Name
    1.38 +	}
    1.39 +	if change.Owner != nil {
    1.40 +		result.Owner = *change.Owner
    1.41 +	} else {
    1.42 +		// We don't want to accidentally leave a slice that
    1.43 +		// is owned by both behind.
    1.44 +		result.Owner = d.Owner.Copy()
    1.45 +	}
    1.46 +	if change.Type != nil {
    1.47 +		result.Type = *change.Type
    1.48 +	}
    1.49 +	if change.Created != nil {
    1.50 +		result.Created = *change.Created
    1.51 +	}
    1.52 +	if change.LastSeen != nil {
    1.53 +		result.LastSeen = *change.LastSeen
    1.54 +	}
    1.55 +	if change.PushToken != nil {
    1.56 +		result.PushToken = *change.PushToken
    1.57 +	}
    1.58 +	return result
    1.59 +}
    1.60 +
    1.61 +// DeviceType is an enum specifying which type of Device it is. Usually,
    1.62 +// this is something like `android_phone` or `android_tablet`.
    1.63 +type DeviceType string
    1.64 +
    1.65 +// DeviceChange represents a set of changes to a Device that will be used
    1.66 +// to update a Device.
    1.67 +type DeviceChange struct {
    1.68 +	DeviceID  uuid.ID
    1.69 +	Name      *string
    1.70 +	Owner     *uuid.ID
    1.71 +	Type      *DeviceType
    1.72 +	Created   *time.Time
    1.73 +	LastSeen  *time.Time
    1.74 +	PushToken *string
    1.75 +}
    1.76 +
    1.77 +// Storer is an interface to control how data is stored in and retrieved from
    1.78 +// the datastore.
    1.79 +type Storer interface {
    1.80 +	GetDevices(ids []uuid.ID, c context.Context) (map[string]Device, error)
    1.81 +	UpdateDevice(change DeviceChange, c context.Context) error
    1.82 +	DeleteDevices(ids []uuid.ID, c context.Context) error
    1.83 +	CreateDevices(devices []Device, c context.Context) error
    1.84 +	ListDevicesByOwner(user uuid.ID, c context.Context) ([]Device, error)
    1.85 +
    1.86 +	// These are used for testing only.
    1.87 +	Factory(c context.Context) (Storer, error)
    1.88 +	Destroy(c context.Context) error
    1.89 +}
    1.90 +
    1.91 +// GetMany returns as many of the Devices specified by the passed IDs as possible.
    1.92 +// They are returned as a map, with the key being the string version of the ID.
    1.93 +// No error will be returned if a Device can't be found.
    1.94 +func GetMany(ids []uuid.ID, c context.Context) (map[string]Device, error) {
    1.95 +	results := map[string]Device{}
    1.96 +	storer, err := getStorer(c)
    1.97 +	if err != nil {
    1.98 +		log.Printf("Error retrieving Storer: %+v\n", err)
    1.99 +		return results, err
   1.100 +	}
   1.101 +	results, err = storer.GetDevices(ids, c)
   1.102 +	if err != nil {
   1.103 +		log.Printf("Error retrieving Devices from %T: %+v\n", storer, err)
   1.104 +		return results, err
   1.105 +	}
   1.106 +	return results, nil
   1.107 +}
   1.108 +
   1.109 +// Get returns the Device specified by the passed ID. If the Device can't be found,
   1.110 +// an ErrDeviceNotFound error is returned.
   1.111 +func Get(id uuid.ID, c context.Context) (Device, error) {
   1.112 +	results, err := GetMany([]uuid.ID{id}, c)
   1.113 +	if err != nil {
   1.114 +		return Device{}, err
   1.115 +	}
   1.116 +	result, ok := results[id.String()]
   1.117 +	if !ok {
   1.118 +		return Device{}, ErrDeviceNotFound
   1.119 +	}
   1.120 +	return result, nil
   1.121 +}
   1.122 +
   1.123 +// Update applies the DeviceChange to the passed Device, and returns the result. If
   1.124 +// the Device can't be found, an ErrDeviceNotFound error was returned.
   1.125 +func Update(device Device, change DeviceChange, c context.Context) (Device, error) {
   1.126 +	storer, err := getStorer(c)
   1.127 +	if err != nil {
   1.128 +		log.Printf("Error retrieving Storer: %+v\n", err)
   1.129 +		return Device{}, err
   1.130 +	}
   1.131 +	change.DeviceID = device.ID
   1.132 +	err = storer.UpdateDevice(change, c)
   1.133 +	if err != nil {
   1.134 +		return Device{}, err
   1.135 +	}
   1.136 +	return ApplyChange(device, change), nil
   1.137 +}
   1.138 +
   1.139 +// DeleteMany removes the passed IDs from the datastore. No error is returned if the
   1.140 +// ID doesn't correspond to a Device in the datastore.
   1.141 +func DeleteMany(ids []uuid.ID, c context.Context) error {
   1.142 +	storer, err := getStorer(c)
   1.143 +	if err != nil {
   1.144 +		log.Printf("Error retrieving Storer: %+v\n", err)
   1.145 +		return err
   1.146 +	}
   1.147 +	return storer.DeleteDevices(ids, c)
   1.148 +}
   1.149 +
   1.150 +// Delete removes the passed ID from the datastore. No error is returned if the ID doesn't
   1.151 +// correspond to a Device in the datastore.
   1.152 +func Delete(id uuid.ID, c context.Context) error {
   1.153 +	return DeleteMany([]uuid.ID{id}, c)
   1.154 +}
   1.155 +
   1.156 +// CreateMany stores the passed Devices in the datastore, assigning default values if
   1.157 +// necessary. The Devices that were ultimately stored (including any default values, if
   1.158 +// applicable) are returned.
   1.159 +func CreateMany(devices []Device, c context.Context) ([]Device, error) {
   1.160 +	storer, err := getStorer(c)
   1.161 +	if err != nil {
   1.162 +		log.Printf("Error retrieving Storer: %+v\n", err)
   1.163 +		return []Device{}, err
   1.164 +	}
   1.165 +	modified := make([]Device, 0, len(devices))
   1.166 +	for _, device := range devices {
   1.167 +		if device.ID.IsZero() {
   1.168 +			device.ID = uuid.NewID()
   1.169 +		}
   1.170 +		if device.Created.IsZero() {
   1.171 +			device.Created = time.Now()
   1.172 +		}
   1.173 +		if device.LastSeen.IsZero() {
   1.174 +			device.LastSeen = time.Now()
   1.175 +		}
   1.176 +		modified = append(modified, device)
   1.177 +	}
   1.178 +	err = storer.CreateDevices(devices, c)
   1.179 +	if err != nil {
   1.180 +		return []Device{}, err
   1.181 +	}
   1.182 +	return modified, nil
   1.183 +}
   1.184 +
   1.185 +// Create stores the passed Device in the datastore, assigning default values if
   1.186 +// necessary. The Devices that were ultimately stored (including any default values, if
   1.187 +// applicable) are returned.
   1.188 +func Create(device Device, c context.Context) (Device, error) {
   1.189 +	devices, err := CreateMany([]Device{device}, c)
   1.190 +	if err != nil {
   1.191 +		return Device{}, err
   1.192 +	}
   1.193 +	// There should never be a case where we don't return a result.
   1.194 +	// Ideally, we'd return an error here instead of letting the panic
   1.195 +	// happen, but seeing as I can't come up with a reason the error would
   1.196 +	// occur, I'm having trouble coming up with a reasonable error to return.
   1.197 +	return devices[0], nil
   1.198 +}
   1.199 +
   1.200 +// ListByOwner returns a slice of all the Devices with an Owner property that
   1.201 +// matches the passed ID. There's no guarantee on the order the Devices will be
   1.202 +// returned in.
   1.203 +func ListByOwner(user uuid.ID, c context.Context) ([]Device, error) {
   1.204 +	// BUG(paddy): Eventually, we'll need to support paging for devices. But right now, I don't foresee any user creating enough of them to make pagination worthwhile.
   1.205 +	storer, err := getStorer(c)
   1.206 +	if err != nil {
   1.207 +		log.Printf("Error retrieving Storer: %+v\n", err)
   1.208 +		return []Device{}, err
   1.209 +	}
   1.210 +	devices, err := storer.ListDevicesByOwner(user, c)
   1.211 +	return devices, err
   1.212 +}