entity.go

// Copyright 2017 Pilosa Corp.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
//
// 1. Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright
// notice, this list of conditions and the following disclaimer in the
// documentation and/or other materials provided with the distribution.
//
// 3. Neither the name of the copyright holder nor the names of its
// contributors may be used to endorse or promote products derived
// from this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
// CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
// INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
// MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
// BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
// SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
// WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
// DAMAGE.

package pdk

import (
	"encoding/binary"
	"encoding/json"
	"math"
	"reflect"
	"time"

	"github.com/pkg/errors"
)

// IRI is either a full IRI, or will map to one when the record in which it is
// contained is processed in relation to a context:
// (https://json-ld.org/spec/latest/json-ld/#the-context)
type IRI string

// Property represents a Predicate, and can be turned into a Predicate IRI by a context
type Property string
type Context map[string]interface{}

// Entity is the "root" node of a graph branching out from a certain resource
// denoted by the Subject. This is a convenience vs just handling a list of
// Triples as we expect to structure indexing around a particular class of thing
// which we ingest many instances of as records.
type Entity struct {
	Subject IRI `json:"@id"`
	Objects map[Property]Object
}

func (e *Entity) Equal(e2 *Entity) error {
	if e.Subject != e2.Subject {
		return errors.Errorf("subject '%v' != '%v", e.Subject, e2.Subject)
	}
	return equal(e, e2)
}

func equal(o, o2 Object) error {
	if reflect.TypeOf(o) != reflect.TypeOf(o2) {
		return errors.Errorf("objs are different types: %T and %T", o, o2)
	}
	switch o.(type) {
	case *Entity:
		e, e2 := o.(*Entity), o2.(*Entity)
		if len(e.Objects) != len(e2.Objects) {
			return errors.Errorf("entities have different number of objects, %d and %d", len(e.Objects), len(e2.Objects))
		}
		for pred, obj := range e.Objects {
			obj2, ok := e2.Objects[pred]
			if !ok {
				return errors.Errorf("object 2 has no value at %v", pred)
			}
			eqErr := equal(obj, obj2)
			if eqErr != nil {
				return errors.Wrapf(eqErr, "%v", pred)
			}
		}
	case Objects:
		os, os2 := o.(Objects), o2.(Objects)
		if len(os) != len(os2) {
			return errors.Errorf("object slices have different lengths, %d and %d", len(os), len(os2))
		}
		for i := 0; i < len(os); i++ {
			obj1, obj2 := os[i], os2[i]
			eqErr := equal(obj1, obj2)
			if eqErr != nil {
				return errors.Wrapf(eqErr, "index %d", i)
			}
		}
	default:
		_, ok := o.(Literal)
		_, ok2 := o2.(Literal)
		if !(ok && ok2) {
			return errors.Errorf("expected two literals, but got '%v' and '%v' of %T and %T", o, o2, o, o2)
		}
		if o != o2 {
			return errors.Errorf("'%v' and '%v' not equal", o, o2)
		}
	}
	return nil
}

var (
	ErrPathNotFound   = errors.New("path not found in Entity")
	ErrNotALiteral    = errors.New("value at path is not a Literal")
	ErrEmptyPath      = errors.New("path is empty")
	ErrUnexpectedType = errors.New("unexpected type")
)

// Literal gets the literal at the path in the Entity.
func (e *Entity) Literal(path ...string) (Literal, error) {
	var cur = e
	var ok bool
	var lit Literal
	for i, prop := range path {
		var val Object
		val, ok = cur.Objects[Property(prop)]
		if !ok {
			return nil, ErrPathNotFound
		}
		if i == len(path)-1 {
			lit, ok = val.(Literal)
			if !ok {
				return nil, errors.Wrapf(ErrNotALiteral, "%#v", cur)
			}
			return lit, nil
		}
		cur, ok = val.(*Entity)
		if !ok {
			return nil, ErrPathNotFound
		}
	}
	return nil, ErrEmptyPath
}

// F64 tries to get a float64 at the given path in the Entity.
func (e *Entity) F64(path ...string) (F64, error) {
	lit, err := e.Literal(path...)
	if err != nil {
		return 0, errors.Wrap(err, "getting literal")
	}
	f64, ok := lit.(F64)
	if !ok {
		return 0, errors.Wrapf(ErrUnexpectedType, "%#v not a float64", lit)
	}
	return f64, nil
}

// NewEntity returns a newly allocated Entity.
func NewEntity() *Entity {
	return &Entity{
		Objects: make(map[Property]Object),
	}
}

// SetPath ensures that a path exists, creating Entities along the way if
// necessary. If it encounters a non-Entity, it will return an error.
func (e *Entity) SetPath(path ...string) (*Entity, error) {
	var cur = e
	for i, prop := range path {
		val, ok := cur.Objects[Property(prop)]
		if !ok {
			cur.Objects[Property(prop)] = NewEntity()
			cur = cur.Objects[Property(prop)].(*Entity)
			continue
		}
		cur, ok = val.(*Entity)
		if !ok {
			return nil, errors.Wrapf(ErrPathNotFound, "depth %d property %v, not an entity %#v", i, prop, val)
		}
	}
	return cur, nil
}

// SetString
func (e *Entity) SetString(value string, path ...string) error {
	if len(path) == 0 {
		return ErrEmptyPath
	}
	ent, err := e.SetPath(path[:len(path)-1]...)
	if err != nil {
		return errors.Wrap(err, "setting path")
	}
	ent.Objects[Property(path[len(path)-1])] = S(value)
	return nil
}

// EntityWithContext associates a Context
// (https://json-ld.org/spec/latest/json-ld/#the-context) with an Entity so that
// it can be Marshaled to valid and useful JSON-LD.
type EntityWithContext struct {
	Entity
	Context Context `json:"@context"`
}

// Object is an interface satisfied by all things which may appear as objects in
// RDF triples. All literals are objects, but not all objects are literals.
type Object interface {
	isObj()
}

type Objects []Object

func (o Objects) isObj() {}
func (e *Entity) isObj() {}

// MarshalJSON is a custom JSON marshaler for Entity objects to ensure that they
// serialize to valid JSON-LD (https://json-ld.org/ spec/latest/json-ld/). This
// allows for easy (if not particularly performant) interoperation with other
// variants of RDF linked data.
func (e *Entity) MarshalJSON() ([]byte, error) {
	// TODO - this implementation does a lot of in-memory copying for simplicity, can probably be optimized.
	ret := make(map[Property]interface{})
	if e.Subject != "" {
		ret["@id"] = e.Subject
	}
	for k, v := range e.Objects {
		if val, exists := ret[k]; exists {
			return nil, errors.Errorf("invalid entity for json: '%v' already exists at '%v', can't add '%v'", val, k, v)
		}
		ret[k] = v
	}
	return json.Marshal(ret)
}

// Literal interface is implemented by types which correspond to RDF Literals.
type Literal interface {
	literal()
}

type B bool

func (B) literal() {}

func (B B) MarshalJSON() ([]byte, error) {
	ret := map[string]interface{}{
		"@type":  "xsd:boolean",
		"@value": bool(B),
	}
	return json.Marshal(ret)
}

type S string

func (S) literal() {}

// TODO define and specifically support these things
// type Location struct {
// 	Latitude  float64 `json:"latitude"`
// 	Longitude float64 `json:"longitude"`
// }

// func (l *Location) MarshalJSON() ([]byte, error) {
// 	ret := make(map[string]interface{})
// 	ret["@type"] = "http://schema.org/GeoCoordinates"
// 	ret["latitude"] = l.Latitude
// 	ret["longitude"] = l.Longitude
// 	return json.Marshal(ret)
// }

// type IPv4 net.IP

// func (ip IPv4) MarshalJSON() ([]byte, error) {
// 	ret := map[string]interface{}{
// 		"@type":  "http://schema.pilosa.com/v0.1/ipv4",
// 		"@value": fmt.Sprintf("%s", ip),
// 	}
// 	return json.Marshal(ret)
// }

// type IPv6 net.IP

// func (ip IPv6) MarshalJSON() ([]byte, error) {
// 	ret := map[string]interface{}{
// 		"@type":  "http://schema.pilosa.com/v0.1/ipv6",
// 		"@value": fmt.Sprintf("%s", ip),
// 	}
// 	return json.Marshal(ret)
// }

type Time time.Time

func (Time) literal() {}

type F32 float32

func (F32) literal() {}

func (F F32) MarshalJSON() ([]byte, error) {
	ret := map[string]interface{}{
		"@type":  "xsd:float",
		"@value": float32(F),
	}
	return json.Marshal(ret)
}

type F64 float64

func (F64) literal() {}

func (F F64) MarshalJSON() ([]byte, error) {
	ret := map[string]interface{}{
		"@type":  "xsd:double",
		"@value": float64(F),
	}
	return json.Marshal(ret)
}

type I int

func (I) literal() {}

func (I I) MarshalJSON() ([]byte, error) {
	ret := map[string]interface{}{
		"@type":  "xsd:long",
		"@value": int(I),
	}
	return json.Marshal(ret)
}

func (i *I) UnmarshalJSON(b []byte) error {
	var m map[string]interface{}
	if err := json.Unmarshal(b, &m); err != nil {
		return err
	}
	*i = I((m["@value"]).(float64))
	return nil
}

type I8 int8

func (I8) literal() {}

func (I I8) MarshalJSON() ([]byte, error) {
	ret := map[string]interface{}{
		"@type":  "xsd:byte",
		"@value": int8(I),
	}
	return json.Marshal(ret)
}

func (i *I8) UnmarshalJSON(b []byte) error {
	var m map[string]interface{}
	if err := json.Unmarshal(b, &m); err != nil {
		return err
	}
	*i = I8((m["@value"]).(float64))
	return nil
}

type I16 int16

func (I16) literal() {}

func (I I16) MarshalJSON() ([]byte, error) {
	ret := map[string]interface{}{
		"@type":  "xsd:short",
		"@value": int16(I),
	}
	return json.Marshal(ret)
}

func (i *I16) UnmarshalJSON(b []byte) error {
	var m map[string]interface{}
	if err := json.Unmarshal(b, &m); err != nil {
		return err
	}
	*i = I16((m["@value"]).(float64))
	return nil
}

type I32 int32

func (I32) literal() {}

func (I I32) MarshalJSON() ([]byte, error) {
	ret := map[string]interface{}{
		"@type":  "xsd:int",
		"@value": int32(I),
	}
	return json.Marshal(ret)
}

func (i *I32) UnmarshalJSON(b []byte) error {
	var m map[string]interface{}
	if err := json.Unmarshal(b, &m); err != nil {
		return err
	}
	*i = I32((m["@value"]).(float64))
	return nil
}

type I64 int64

func (I64) literal() {}

func (I I64) MarshalJSON() ([]byte, error) {
	ret := map[string]interface{}{
		"@type":  "xsd:long",
		"@value": int64(I),
	}
	return json.Marshal(ret)
}

func (i *I64) UnmarshalJSON(b []byte) error {
	var m map[string]interface{}
	if err := json.Unmarshal(b, &m); err != nil {
		return err
	}
	*i = I64((m["@value"]).(float64))
	return nil
}

type U uint

func (U) literal() {}

func (U U) MarshalJSON() ([]byte, error) {
	ret := map[string]interface{}{
		"@type":  "unsignedLong",
		"@value": uint(U),
	}
	return json.Marshal(ret)
}

type U8 uint8

func (U8) literal() {}

func (U U8) MarshalJSON() ([]byte, error) {
	ret := map[string]interface{}{
		"@type":  "unsignedByte",
		"@value": uint8(U),
	}
	return json.Marshal(ret)
}

type U16 uint16

func (U16) literal() {}

func (U U16) MarshalJSON() ([]byte, error) {
	ret := map[string]interface{}{
		"@type":  "unsignedShort",
		"@value": uint16(U),
	}
	return json.Marshal(ret)
}

type U32 uint32

func (U32) literal() {}

func (U U32) MarshalJSON() ([]byte, error) {
	ret := map[string]interface{}{
		"@type":  "unsignedInt",
		"@value": uint32(U),
	}
	return json.Marshal(ret)
}

type U64 uint64

func (U64) literal() {}

func (U U64) MarshalJSON() ([]byte, error) {
	ret := map[string]interface{}{
		"@type":  "unsignedLong",
		"@value": uint64(U),
	}
	return json.Marshal(ret)
}

func (B) isObj()    {}
func (S) isObj()    {}
func (Time) isObj() {}
func (F32) isObj()  {}
func (F64) isObj()  {}
func (I) isObj()    {}
func (I8) isObj()   {}
func (I16) isObj()  {}
func (I32) isObj()  {}
func (I64) isObj()  {}
func (U) isObj()    {}
func (U8) isObj()   {}
func (U16) isObj()  {}
func (U32) isObj()  {}
func (U64) isObj()  {}

// Note: if we start adding lots more literals, reserve numbers 128 and greater.
// Right now, ToBytes and FromBytes use a single byte at the start of the value
// to denote the type - if we grow to 128, we can use first column as a marker to
// signify that the type is now two bytes.
const (
	bID = iota + 1 // reserve 0 for some future use.
	sID
	f32ID
	f64ID
	iID
	i8ID
	i16ID
	i32ID
	i64ID
	uID
	u8ID
	u16ID
	u32ID
	u64ID
)

// ToBytes converts a literal into a typed byte slice representation.
func ToBytes(l Literal) []byte {
	switch l := l.(type) {
	case B:
		if l {
			return []byte{bID, 1}
		}
		return []byte{bID, 0}
	case S:
		return append([]byte{sID}, l[:]...)
	case F32:
		ret := make([]byte, 5)
		ret[0] = f32ID
		binary.BigEndian.PutUint32(ret[1:], math.Float32bits(float32(l)))
		return ret
	case F64:
		ret := make([]byte, 9)
		ret[0] = f64ID
		binary.BigEndian.PutUint64(ret[1:], math.Float64bits(float64(l)))
		return ret
	case I:
		ret := make([]byte, 9)
		ret[0] = iID
		binary.BigEndian.PutUint64(ret[1:], uint64(l))
		return ret
	case I8:
		return []byte{i8ID, byte(l)}
	case I16:
		ret := make([]byte, 3)
		ret[0] = i16ID
		binary.BigEndian.PutUint16(ret[1:], uint16(l))
		return ret
	case I32:
		ret := make([]byte, 5)
		ret[0] = i32ID
		binary.BigEndian.PutUint32(ret[1:], uint32(l))
		return ret
	case I64:
		ret := make([]byte, 9)
		ret[0] = i64ID
		binary.BigEndian.PutUint64(ret[1:], uint64(l))
		return ret
	case U:
		ret := make([]byte, 9)
		ret[0] = uID
		binary.BigEndian.PutUint64(ret[1:], uint64(l))
		return ret
	case U8:
		return []byte{u8ID, byte(l)}
	case U16:
		ret := make([]byte, 3)
		ret[0] = u16ID
		binary.BigEndian.PutUint16(ret[1:], uint16(l))
		return ret
	case U32:
		ret := make([]byte, 5)
		ret[0] = u32ID
		binary.BigEndian.PutUint32(ret[1:], uint32(l))
		return ret
	case U64:
		ret := make([]byte, 9)
		ret[0] = u64ID
		binary.BigEndian.PutUint64(ret[1:], uint64(l))
		return ret
	default:
		panic("should have covered all literal types in ToBytes switch")
	}
}

// ToString converts a Literal into a string with a type byte prepended.
func ToString(l Literal) string {
	return string(ToBytes(l))
}

// FromString converts a Literal encoded with ToString back to a Literal.
func FromString(s string) Literal {
	return FromBytes([]byte(s))
}

// FromBytes converts an encoded byte slice (from ToBytes) back to a Literal.
// DEV: May add an error and bounds checking.
func FromBytes(bs []byte) Literal {
	// if len(bs) < 2 {
	// 	return nil, errors.Errorf("byte slice too short: %x", bs)
	// }
	switch bs[0] {
	case bID:
		return B(bs[1] > 0)
	case sID:
		return S(string(bs[1:]))
	case f32ID:
		return F32(math.Float32frombits(binary.BigEndian.Uint32(bs[1:])))
	case f64ID:
		return F64(math.Float64frombits(binary.BigEndian.Uint64(bs[1:])))
	case iID:
		return I(binary.BigEndian.Uint64(bs[1:]))
	case i8ID:
		return I8(bs[1])
	case i16ID:
		return I16(binary.BigEndian.Uint16(bs[1:]))
	case i32ID:
		return I32(binary.BigEndian.Uint32(bs[1:]))
	case i64ID:
		return I64(binary.BigEndian.Uint64(bs[1:]))
	case uID:
		return U(binary.BigEndian.Uint64(bs[1:]))
	case u8ID:
		return U8(bs[1])
	case u16ID:
		return U16(binary.BigEndian.Uint16(bs[1:]))
	case u32ID:
		return U32(binary.BigEndian.Uint32(bs[1:]))
	case u64ID:
		return U64(binary.BigEndian.Uint64(bs[1:]))
	default:
		panic("should have covered all literal types in FromBytes switch")
	}
}