Migrating to GoAhead 3/4

GoAhead 3 is a major upgrade from GoAhead 2. It incorporates new features and upgrades to existing capabilities. It also changes many APIs and interfaces. GoAhead 4 is a evolutionary upgrade to GoAhead 3 and is highly compatible with GoAhead 3.

Compatibility with GoAhead 3/4

We make every effort to preserve compatibility, but with GoAhead 3, we needed to make some important improvements that necessitated breaking compatibility with GoAhead 2. Rather than make several ongoing compatibility breaks we decided to make all the changes in one release. In this way we can ensure that GoAhead 3 quickly becomes a stable platform going forward and that GoAhead 4 is highly compatible with GoAhead 3. Please see our Compatibility Policy.

Legacy Support

To aid migrating existing GoAhead 2.X applications, GoAhead 3.X can be built to support the old GoAhead 2.X APIs. This is called legacy mode. In this mode, the old APIs are mapped to new APIs via compiler defines and shim APIs. For full details of the API mappings, see the ME_GOAHEAD_LEGACY section in src/goahead.h.

GoAhead 3.X is built by default without legacy mode. You can enable legacy mode by configuring via:

configure --set goahead.legacy=true

or if building via make:

make ME_GOAHEAD_LEGACY=1

This will enable the legacy APIs and type names. However, You are strongly encouraged to fully migrate your application to the GoAhead 3/4 APIs and to transition off the old GoAhead 2 APIs. Note: GoAhead 2 is now officially "end-of-life".

Changes in GoAhead 3/4

GoAhead 3 and 4 provide equivalent or greater functionality to that in GoAhead 2. While GoAhead 3 may have a different interface or API, the capabilities of GoAhead 2 have been continued in GoAhead 3, and in many cases, the features have been enhanced.

New Capabilities

The following new capabilities have been added to GoAhead 3 for which there is no equivalent in GoAhead 2. These additions should not require adjustment for applications developed under GoAhead 2.

• HTTP 1.1 chunking
• IPv6
• PUT, DELETE, OPTIONS and TRACE HTTP methods
• Request routing
• New web form-based authentication
• Session state storage
• New User/Role/Ability authorization framework
• Extended security sandbox limits
• Flexible request tracing and logging

Changed Capabilities

The following capabilities have been changed and may impact your GoAhead 3 applications.

• The GoAhead 2.X User Management authentication has been upgrade to the User/Role/Ability framework
• The EMF database has been removed. The new authentication framework does not utilize it.
• The GoForm facility has been upgrade to the GoAction handler. The calling sequence for GoForms has been modified and simplified.
• POST request form data is only stored in the query field of the Webs structure if Legacy mode is enabled. Without legacy mode, query data and form body data are stored separately. Form data is stored in the 'input' field of the Webs structure. Code that accesses wp->query for GoForms will need to be modified. In legacy mode, the input is also copied to the wp->query field.
• Request parameter variables are only created for POST requests if the request Content-Type is set to application/x-www-form-urlencoded.
• The build system is upgraded and simplified. It now uses the MakeMe build system. New configure options and cross compiling capabilities have been added.
• In GoAhead 2, the websHeader routine was used to write a fixes set of HTTP response headers. This was inflexible and did not permit easy custom modification of headers. GoAhead 3/4 supports user-definable response headers via the new API websWriteHeader. Consequently, the websHeader and websFooter APIs are removed.

Changed APIs

The internal APIs in GoAhead 3/4 have been upgraded. Some have been renamed and others modified. GoAhead 3/4 APIs have been renamed/converted on a function by function basis to equivalent APIs in GoAhead 2. Often, the APIs have very similar names to the previous counterpart.

Here is a partial list of changed APIs in GoAhead 3.X and 4.X:

• balloc memory allocation routines renamed to walloc
• g*() string routines mapped back to standard C library and Posix routines
• hAlloc*() handle allocation routines mapped to wallocHandle
• ASP renamed to JSP and websAsp* renamed to websJst*
• GoForms renamed to Actions, /goforms renamed to /action
• ringq*() renamed to buf*
• sym*() renamed to hash*

For a complete list, see the ME_GOAHEAD_LEGACY section at the end of goahead.h for a list of all the API name mappings. It is strongly recommended that you refactor your application to use the new API naming.

Routes

GoAhead 3/4 uses a flexible URI routing mechanism to direct client requests to the appropriate handler. In GoAhead 2, this was done by hard-coded handlers. The routing framework is controlled by the route.txt configuration file. The routing framework has more flexibility and allows URI parsing and routing.

See Request Routing for more details.