A CRUD address service with a mutex-locked repository

The complete source of webServices_addresses.ek9, compiled by the EK9 compiler. Shown on webServices.html.

#!ek9
defines module site.webServices.addresses

  defines type
    //Just for strong typing - no constraints
    AddressId as String

  defines record
    Address
      id <- AddressId()
      street <- String()
      street2 <- String()
      city <- String()
      state <- String()
      zipcode <- String()

      Address()
        ->
          id as AddressId
          street as String
          street2 as String
          city as String
          state as String
          zipcode as String

        this.id :=: id
        this.street :=: street
        this.street2 :=: street2
        this.city :=: city
        this.state :=: state
        this.zipcode :=: zipcode

      Address()
        -> from as Address
        this :=: from

      Address()
        -> from as Optional of Address
        if from?
          this :=: from.get()

      //Copy
      operator :=:
        -> from as Address
        id :=: from.id
        street :=: from.street
        street2 :=: from.street2
        city :=: from.city
        state :=: from.state
        zipcode :=: from.zipcode

      //Merge only if incoming address parts are set
      operator :~:
        -> address as Address
        if address.street?
          street :=: address.street
        if address.street2?
          street2 :=: address.street2
        if address.city?
          city :=: address.city
        if address.state?
          state :=: address.state
        if address.zipcode?
          zipcode :=: address.zipcode

      override operator ? as pure
        //street2 is optional and can be omitted
        <- rtn as Boolean: id? and street? and city? and state? and zipcode?

  defines text for "en"
    AddressToOutputFormat

      toJSON()
        -> address as Address
        `{
"address":
    {
    "id": "${address.id}",
    "street": "${address.street}",${optionalJSON("street2", address.street2)}
    "city": "${address.city}",
    "state": "${address.state}",
    "zipcode": "${address.zipcode}"
    }
}`

  defines function

    //Used for specific operations to be applied to a set of addresses
    addressOperation() as abstract
      ->
        addresses as AddressAccess
        address as Address

    //deals with wrapping the operation in the calls to deal with mutex lock.
    safeOperation()
      ->
        lockedAddressSet as MutexLock of AddressSet
        address as Address
        operation as addressOperation

      accessKey <- (address, operation) extends MutexKey of AddressSet as function
          operation(lockedItem, address)

      require lockedAddressSet.enter(accessKey)

    //The built-in JSON type reads the text; a part that is not there stays unset.
    addressFromJson()
      -> addressInJSONFormat as String
      <- rtn as Address: Address()

      parsed <- JSON().parse(addressInJSONFormat)
      if parsed.isOk()
        address <- parsed.ok().get("address")
        rtn.id: AddressId(textOf(address, "id"))
        rtn.street: textOf(address, "street")
        rtn.street2: textOf(address, "street2")
        rtn.city: textOf(address, "city")
        rtn.state: textOf(address, "state")
        rtn.zipcode: textOf(address, "zipcode")

    //The text a JSON property holds (not its JSON form, which is quoted).
    textOf()
      ->
        json as JSON
        property as String
      <- rtn as String: cat [json.get(property)] | collect as String

    copyAddress()
      -> from as Address
      <- to as Address: Address(from)

    wrapInBrackets()
      -> mainValue as String
      <- rtn as String: `[ ${mainValue} ]`

    commaSeparated()
      ->
        firstPart String
        secondPart String
      <-
        rtn as String: firstPart? and secondPart? <- `${firstPart},${secondPart}` : String()

    addressToJSON()
      -> address as Address
      <- addressAsString as String: AddressToOutputFormat("en").toJSON(address)

    addressListToJSON()
      -> addresses as List of Address
      <- listAsString as String: cat addresses
        | map with addressToJSON
        | join with commaSeparated
        | map with wrapInBrackets
        | collect as String

    //An unset value must not end up in the text: interpolating it would leave the whole text unset.
    optionalJSON() as pure
      ->
        name as String
        mainValue as String
      <-
        rtn as String: mainValue? <- ` "${name}": "${mainValue}",` else ""

  defines trait

    AddressAccess

      hash()
        <- rtn as String: String()

      hashOfAddress()
        -> id as AddressId
        <- rtn as String?
        require id?
        rtn: String()

      byId()
        -> id as AddressId
        <- rtn as Address?

      listAll()
        <- rtn as List of Address: List() of Address

      operator +=
        -> address as Address
        require address?

      operator -=
        -> address as Address
        require address?

      //merge with an existing address
      operator :~:
        -> address as Address
        require address?

      //replace an existing address
      operator :^:
        -> address as Address
        require address?

      operator contains as pure
        -> addressId as AddressId
        <- rtn as Boolean: Boolean()

  defines class

    AddressSet with trait of AddressAccess
      //The etag of the whole set: the hash of every address's own hash, so the same addresses give the same etag.
      hash as String: String()
      addresses <- Dict() of (AddressId, Address)
      hashes <- Dict() of (AddressId, String)

      override hash()
        <- rtn as String: this.hash

      //Unset for an address that is not held.
      override hashOfAddress()
        -> id as AddressId
        <- rtn as String: hashes.getOrDefault(id, String())

      override byId()
        -> id as AddressId
        <- rtn as Address: Address(addresses.getOrDefault(id, Address()))

      override listAll()
        <- rtn <- List() of Address

        iter <- addresses.values()
        cat iter | map with copyAddress > rtn

      private includeAddress()
        -> address as Address

        copy <- Address(address)
        addresses += DictEntry(copy.id, copy)
        hashes += DictEntry(copy.id, Digest().SHA256(addressToJSON(copy)))
        updateHash()

      private updateHash()
        allHashes <- cat hashes.values() | collect as String
        hash :=: Digest().SHA256(allHashes)

      override operator +=
        -> address as Address
        require address?

        if this not contains address
          includeAddress(address)

      override operator -=
        -> address as Address
        require address.id?

        addresses -= address.id
        hashes -= address.id
        updateHash()

      override operator :~:
        -> address as Address
        require address.id?
        //We don't assert whole address because it can be partial

        currentAddress <- addresses.getOrDefault(address.id, Address())
        if currentAddress?
          //make a new copy and then merge the two.
          updatedAddress <- Address(currentAddress)
          updatedAddress :~: address
          includeAddress(updatedAddress)

      override operator :^:
        -> address as Address
        require address?

        if this contains address
          includeAddress(address)

      operator contains as pure
        -> address as Address
        <- rtn as Boolean: this contains address.id

      override operator contains as pure
        -> addressId as AddressId
        <- rtn as Boolean: addresses contains addressId

      default operator ?

    //Example of wrapping shared data set in a mutex lock.
    LockableAddressSet with trait of AddressAccess
      lockedAddressSet as MutexLock of AddressSet: MutexLock(AddressSet())

      override hash()
        <- rtn as String: String()
        accessKey <- (rtn) is MutexKey of AddressSet as function
          rtn :=: lockedItem.hash()

        require lockedAddressSet.enter(accessKey)

      override hashOfAddress()
        -> id as AddressId
        <- rtn as String: String()
        accessKey <- (id, rtn) is MutexKey of AddressSet as function
          rtn :=: lockedItem.hashOfAddress(id)

        require lockedAddressSet.enter(accessKey)

      override byId()
        -> id as AddressId
        <- rtn as Address: Address()
        accessKey <- (id, rtn) is MutexKey of AddressSet as function
          rtn :=: lockedItem.byId(id)

        require lockedAddressSet.enter(accessKey)

      override listAll()
        <- rtn <- List() of Address
        accessKey <- (rtn) is MutexKey of AddressSet as function
          rtn += lockedItem.listAll()

        require lockedAddressSet.enter(accessKey)

      override operator +=
        -> address as Address

        //You can inline this simple dynamic function if you wish
        //Also used named parameters
        safeOperation(
          lockedAddressSet: lockedAddressSet,
          address: address,
          operation: () is addressOperation (addresses += address)
          )

      override operator -=
        -> address as Address

        //Or you can inline all on one line.
        safeOperation(lockedAddressSet, address, () is addressOperation (addresses -= address))

      override operator :~:
        -> address as Address

        //Or define a dynamic function and pass in as delegate (my preferred way)
        operation <- () is addressOperation
          addresses :~: address
        safeOperation(lockedAddressSet, address, operation)

      override operator :^:
        -> address as Address
        operation <- () is addressOperation
          addresses :^: address
        safeOperation(lockedAddressSet, address, operation)

      override operator contains as pure
        -> addressId as AddressId
        <- rtn as Boolean: false
        accessKey <- (addressId, rtn) is MutexKey of AddressSet as function
          rtn :=: lockedItem contains addressId

        require lockedAddressSet.enter(accessKey)

      default operator ?

  defines function

    plainNonCacheableHTTPResponse()
      <- rtn as HTTPResponse: () with trait of HTTPResponse
        override cacheControl() as pure
          <- rtn as String: "no-store,max-age=0"
        override contentType() as pure
          <- rtn as String: "text/plain"
        override contentLanguage() as pure
          <- rtn as String: "en"
        default operator ?

    cacheableHTTPResponse()
      <- rtn as HTTPResponse: () with trait of HTTPResponse
        override cacheControl() as pure
          <- rtn as String: "public,max-age=5,must-revalidate"
        override contentType() as pure
          <- rtn as String: "application/json"
        override contentLanguage() as pure
          <- rtn as String: "en"
        default operator ?

    //The answer to a change: a status (and a body or location if there is one) decided before it is made.
    //Named parameters in the dynamic variable capture, and 'by' to delegate the rest of the trait.
    outcomeHTTPResponse()
      ->
        status as Integer
        detail as String
        location as String
      <-
        response as HTTPResponse: (
            status: status,
            detail: detail,
            location: location,
            nonCacheable: plainNonCacheableHTTPResponse()
          ) with trait of HTTPResponse by nonCacheable

          override status() as pure
            <- rtn as Integer: status
          override content()
            <- rtn as Bytes: detail? <- Bytes().withUtf8(detail) else Bytes()
          override contentLocation() as pure
            <- rtn as String: location
          default operator ?

  defines class

    ByETagHTTPResponse with trait of HTTPResponse by delegate
      delegate as HTTPResponse?
      addressId as AddressId?
      provideContentLocation as Boolean?

      status <- Integer()
      etagOfAddress <- String()

      default private ByETagHTTPResponse()

      //The etag is the hash of the address: when there is none, the address is not there.
      ByETagHTTPResponse()
        ->
          addressId as AddressId
          etagOfAddress as String
          delegate as HTTPResponse
          provideContentLocation as Boolean
        require addressId? and delegate? and provideContentLocation?

        this.addressId: addressId
        this.provideContentLocation: provideContentLocation
        this.delegate: delegate
        this.etagOfAddress :=: etagOfAddress
        if etagOfAddress?
          status :=: 200
        else
          status :=: 404

      ByETagHTTPResponse()
        ->
          addressId as AddressId
          etagOfAddress as String
          delegate as HTTPResponse
        this(
          addressId: addressId,
          etagOfAddress: etagOfAddress,
          delegate: delegate,
          provideContentLocation: true
          )

      override etag()
        <- rtn as String: etagOfAddress
      override status() as pure
        <- rtn as Integer: status
      override contentLocation() as pure
        <- rtn as String: String()
        httpBadRequest <- 400
        rtn: status < httpBadRequest and provideContentLocation <- `/addresses/${addressId}` else String()
      default operator ?
  <?-
    REST web service.
    Each method does its work first, then answers with a response that already knows its status:
    the server asks a response for its headers and status before it asks for its content.
  -?>
  defines service
    //The Name of the and the uri it is mapped to
    Addresses for :/addresses open

      //It is still possible to use dynamic variable capture, like this.
      byId() as GET for :/{address-id}
        -> id as String :=: PATH "address-id" //required because different name
        <- response as HTTPResponse?

        repository as Repository!
        addressId <- AddressId(id)
        address <- repository.addresses().byId(addressId)
        delegate <- ByETagHTTPResponse(addressId, repository.addresses().hashOfAddress(addressId), cacheableHTTPResponse())
        response: (address, delegate) with trait of HTTPResponse by delegate
          override content()
            <- rtn as Bytes: address? <- Bytes().withUtf8(addressToJSON(address)) else Bytes()
          default operator ?

      //A POST
      operator += for :/
        -> request as HTTPRequest :=: REQUEST
        <- response as HTTPResponse?

        repository as Repository!
        address <- addressFromJson(request.content().toText("utf-8"))
        status <- 201
        detail <- String()
        location <- String()

        //But the server sets the ID!
        if address.id?
          status := 422 //unprocessable entity
          detail: "Do not supply ID in Address, server will set this"
        else
          address.id: AddressId(GUID())
          if not address?
            status := 422 //unprocessable entity
            detail: "An address needs a street, city, state and zipcode"
          else if repository.addresses() contains address.id
            status := 409 //conflict
          else
            repository.addresses() += address
            location: `/addresses/${address.id}`

        response: outcomeHTTPResponse(status, detail, location)

      //A DELETE
      operator -= for :/{id}
        -> id as String //Assume PATH
        <- response as HTTPResponse?

        repository as Repository!
        addressId <- AddressId(id)
        status <- 404 //not found

        //Only if the address is there can we delete it!
        if repository.addresses() contains addressId
          repository.addresses() -= repository.addresses().byId(addressId)
          status := 204 //no content

        response: outcomeHTTPResponse(status, String(), String())

      //A PATCH which is a merge
      operator :~: for :/{id}
        ->
          id as String //Assume PATH
          incomingContent as String :=: CONTENT
        <-
          response as HTTPResponse?

        repository as Repository!
        addressId <- AddressId(id)
        address <- addressFromJson(incomingContent)
        status <- 204 //no content

        if repository.addresses() not contains addressId
          status := 404 //not found
        else if not address.id?
          status := 422 //unprocessable entity
        else if address.id <> addressId
          status := 400 //the id on the url is not the same as the id in the body content
        else
          repository.addresses() :~: address

        response: outcomeHTTPResponse(status, String(), String())

      //A PUT which is a replace for an existing address
      operator :^: for :/{id}
        ->
          id as String //Assume PATH
          content as String :=: CONTENT
        <-
          response as HTTPResponse?

        repository as Repository!
        addressId <- AddressId(id)
        address <- addressFromJson(content)
        status <- 204 //no content

        if repository.addresses() not contains addressId
          status := 404 //not found
        else if not address?
          status := 422 //unprocessable entity
        else if address.id <> addressId
          status := 400 //the id on the url is not the same as the id in the body content
        else
          repository.addresses() :^: address

        response: outcomeHTTPResponse(status, String(), String())

      //Note it is now possible to use named parameters in dynamic variable capture
      //So now, we can do a simpler one liner, define the name of the property and use an expression
      //to set it up, then use the 'by' on a trait to delegate as much or as little as we want to it.
      listAll() for :/
        <- response as HTTPResponse: (
            cacheable: cacheableHTTPResponse()
          ) with trait of HTTPResponse by cacheable

          repository as Repository!

          override etag()
            <- rtn as String: repository.addresses().hash()
          override status() as pure
            <- rtn as Integer: 200
          override content()
            <- rtn as Bytes: Bytes().withUtf8(addressListToJSON(repository.addresses().listAll()))
          default operator ?

  defines component

    Repository as abstract

      addresses() as pure abstract
        <- rtn as AddressAccess?

      default operator ?

    InMemoryRepository extends Repository
      addresses as AddressAccess: LockableAddressSet()

      InMemoryRepository()
        addresses += Address(id: AddressId("a1"), street: "121 Admin Rd.", street2: String(), city: "Concord", state: "NH", zipcode: "03301")
        addresses += Address(id: AddressId("a2"), street: "67 Paperwork Ave", street2: String(), city: "Manchester", state: "NH", zipcode: "03101")
        addresses += Address(id: AddressId("a3"), street: "15 Rose St", street2: "Apt. B-1", city: "Concord", state: "NH", zipcode: "03301")
        addresses += Address(id: AddressId("a4"), street: "39 Sole St.", street2: String(), city: "Concord", state: "NH", zipcode: "03301")
        addresses += Address(id: AddressId("a5"), street: "99 Mountain Rd.", street2: String(), city: "Concord", state: "NH", zipcode: "03301")

      override addresses() as pure
        <- rtn as AddressAccess: addresses

      default operator ?

  defines application

    //SERVING wiring: this application registers the REST service, so any program using
    //it MUST create an HTTP instance. EK9 enforces that both ways — a program wiring this
    //application without HTTP is E12020 (the service could never receive a request), and
    //an HTTP program wired to an application with no services is E12021.
    AccessPoint
      register InMemoryRepository() as Repository
      register Addresses()

    //COMPONENT wiring only: no service is registered here, so a plain (non-serving)
    //program can use it. Splitting the two is the point — conflating them is what
    //leaves a REST service registered and permanently unreachable.
    RepositoryOnly
      register InMemoryRepository() as Repository

  defines program

    //Serves the Addresses service on the port given, until the process is stopped.
    ServeAddresses() with application of AccessPoint
      -> port as Integer

      try
        -> server <- HTTP(NetworkProperties(port: port, localOnly: true))
        server.serve()

    //Uses the component-only application: it exercises the repository and exits, so it
    //must NOT be wired to the service-registering AccessPoint.
    TestAddressOutput with application of RepositoryOnly
      //Expect injection
      repository as Repository!

      stdout <- Stdout()

      address1 <- Address(id: AddressId("t1"), street: "121 Admin Rd.", street2: String(), city: "Concord", state: "NH", zipcode: "03301")
      address2 <- Address(id: AddressId("t2"), street: "15 Rose St", street2: "Apt. B-1", city: "Concord", state: "NH", zipcode: "03301")

      addresses <- [address1, address2]

      iter <- addresses.iterator()
      //convert contents in iterator to a list
      theAddresses <- cat iter | collect as List of Address
      require theAddresses?

      stdout.println("Address as JSON")
      stdout.println(addressToJSON(address1))

      jsonAddress <- addressFromJson(addressToJSON(address2))

      stdout.println(`Rebuilt address is [${addressToJSON(jsonAddress)}]`)

      stdout.println("Now arrays")

      stdout.println(addressListToJSON(addresses))

      stdout.println("Done basics now all addresses")

      allAddresses <- repository.addresses().listAll()

      stdout.println(`Hash of all addresses is [${repository.addresses().hash()}]`)

      stdout.println(addressListToJSON(allAddresses))

      stdout.println("Done!")

Download webServices_addresses.ek9

Output

TestAddressOutput

Address as JSON
{
"address":
    {
    "id": "t1",
    "street": "121 Admin Rd.",
    "city": "Concord",
    "state": "NH",
    "zipcode": "03301"
    }
}
Rebuilt address is [{
"address":
    {
    "id": "t2",
    "street": "15 Rose St", "street2": "Apt. B-1",
    "city": "Concord",
    "state": "NH",
    "zipcode": "03301"
    }
}]
Now arrays
[ {
"address":
    {
    "id": "t1",
    "street": "121 Admin Rd.",
    "city": "Concord",
    "state": "NH",
    "zipcode": "03301"
    }
},{
"address":
    {
    "id": "t2",
    "street": "15 Rose St", "street2": "Apt. B-1",
    "city": "Concord",
    "state": "NH",
    "zipcode": "03301"
    }
} ]
Done basics now all addresses
Hash of all addresses is [386368B779B099210EB8DA9D15158EC4D4D412655294648E9BFBD6DE78F30875]
[ {
"address":
    {
    "id": "a1",
    "street": "121 Admin Rd.",
    "city": "Concord",
    "state": "NH",
    "zipcode": "03301"
    }
},{
"address":
    {
    "id": "a2",
    "street": "67 Paperwork Ave",
    "city": "Manchester",
    "state": "NH",
    "zipcode": "03101"
    }
},{
"address":
    {
    "id": "a3",
    "street": "15 Rose St", "street2": "Apt. B-1",
    "city": "Concord",
    "state": "NH",
    "zipcode": "03301"
    }
},{
"address":
    {
    "id": "a4",
    "street": "39 Sole St.",
    "city": "Concord",
    "state": "NH",
    "zipcode": "03301"
    }
},{
"address":
    {
    "id": "a5",
    "street": "99 Mountain Rd.",
    "city": "Concord",
    "state": "NH",
    "zipcode": "03301"
    }
} ]
Done!