Potlatch 1/Development overview/Server overview

From OpenStreetMap Wiki
Jump to: navigation, search

The server code that does all the heavy database lifting is sites/rails_port/app/controllers/amf_controller.rb.

It's in Ruby and uses AMF to talk to the client. You can safely ignore the AMF code (very start and end of the file), which is predictable and stable. The real work is done in the methods. Many are simple, but the putway, deleteway, and various history functions deserve careful study.

Some general notes

  • As ever, node co-ordinates are projected on their way to and from the client (but bounding boxes aren't).
  • For many methods, you can send an error message back to the client like this:
 return -1,"You are not logged in"
  • For debugging, you can write to the Rails log like this:
 RAILS_DEFAULT_LOGGER.info("  Message: putway, id=#{originalway}")
  • Several methods can be batched within one HTTP request/response. Therefore it is important that some variables persist across methods. In particular, if Potlatch node id -5 has been given the server id 97671 in one 'putway', another way that uses the same node will need to know that.

Simple methods


Reads tag config files and returns in arrays/hashes.


Given a bounding box, returns a list of all way ids in that box, and full details of all POIs in that box.


Given a bounding box, returns a list of all deleted ways with deleted nodes in that box.


Given a way id, return full details for that way, including all constituent nodes, and tags.


Given a way id, return a list of previous versions for that way, including timestamp and user.


Get a POI from the server. (Only ever used on revert; usually, POIs are retrieved by whichways.)


Save a POI (new or old) to the database, or (if visible=0) deletes it. If the latter, removes it from any relations.


As getway, but retrieves previous version of the way.

If the version is -1, get the last deleted version ("undelete"): if the version is 1+, get that version ("revert"). Behaviour is different for revert and undelete:

  • undelete will always use the most recent version of each constituent node (even if it's moved)
  • revert will use the historic version of each constituent node, but if that node is still visible and has moved somewhere else, it will generate a new node ID


putway is perhaps the single most complex piece of code within Potlatch.

Given a way (with id, point array, key/value hash), it writes it, and its consituent nodes, to the database. It returns the new IDs for this way and its constituent nodes (if any of them are new).

This might sound sensible in itself, but these are the provisos:

  • Nodes are not rewritten unless they have changed
  • Any nodes that were previously in this way alone ("unique nodes"), and are not in the new version, are deleted
  • Deleted nodes are also removed from any relations they're in
  • Special handling if the user is writing an undeleted/reverted way
  • Uses minimum number of queries

More details at Potlatch/Remote_calls/putway_SQL.


This is similar to putway in many ways, and has the same provisos.

In addition, if the way was part of any relations, it is removed from them.