NAME

Apache::iNcom - An e-commerce framework.

SYNOPSIS

- Configure Apache and mod_perl
- Create databases
- Install Apache::iNcom
- Design your e-commerce site.
- Wait for incomes.

DESCRIPTION

Apache::iNcom is an e-commerce framework. It is not a ready-to-run merchant systems. It is an integration of different components needed for e-commerce into a coherent whole.

The primary design goals of the framework are flexibility and security. Most merchant systems will make assumptions in the way your catalog's data, customer's data are structured or on how your order process works. Most also imposes severe restrictions on how the user will interface to your electronic catalog. This is precisely the kind of constraints that Apache::iNcom was designed to avoid.

Apache::iNcom provides the following infrastructure :

- Session Management
- Cart Management
- Input Validation
- Order management
- User management
- << Easy >> database access
- Internationalization
- Error handling

Most of the base functionalities of Apache::iNcom are realized by leveraging standard and well known modules like DBI(3) for generic SQL database access, HTML::Embperl(3) for dynamic page generation, Apache::Session(3) for session management, mod_perl(3) for Apache integration and Locale::Maketext(3) for localization.

Here are its assumptions :

- Data is in a SQL database which supports transactions.
- Interface is in HTML.
- Session is managed through cookies.

REQUIREMENTS

- DBI              1.13
- mod_perl         1.21
- libapreq	       0.31
- HTML::Embperl    1.2b10
- Apache::Session  1.03   + generate_id patch
- MIME::Base64
- Locale::Maketext 0.17   + currency patch
- apache	       1.3.6 or later
- Database which supports transactions. (tested with PostgreSQL 6.5.x)

CONFIGURATION

Apache::iNcom is configured using standard the Apache directives PerlSetVar. Activating Apache::iNcom for a particular virtual host is a simple as

    <VirtualHost 192.168.1.1>
	PerlInitHandler Apache::iNcom
	PerlSetVar INCOM_URL_PREFIX /incom/
	PerlSetVar INCOM_ROOT	    pages
    </VirtualHost>

This will make all URL starting with /incom/ served dynamically by Apache::iNcom.

Additionnaly different modules used by Apache::iNcom will be configured by profile files. Consult the appropriate module documentation for details.

GENERAL DIRECTIVES

INCOM_URL_PREFIX: This is the prefix that must match for the URI to be serve by Apache::iNcom. THIS PREFIX MUST ENDS WITH A SLASH (/). To make all files Apache::iNcom page, use / as prefix. This wouldn't work well for images and other binary files though. Use only / as prefix, if binary files are served by another server.
INCOM_ROOT: This is the path to the directory where Apache::iNcom requests will be mapped. For example, if you have a INCOM_URL_PREFIX of /incom/ and a INCOM_ROOT of /home/incom/site/pages, the request /incom/index.html will be mapped to /home/incom/site/pages/index.html. Default is to use the server's document root.
INCOM_INDEX: This is page that will be used when accessing directory. Defaults to index.html
INCOM_TEMPLATE_PATH: Colon separated list of directory to search when using the Include() function. (See Apache::iNcom::Request(3) for more information). Non absolute paths are relative to the server's root.

DATABASE DIRECTIVES

INCOM_DBI_DSN

The DBI(3) URL to use to open a database connection.

INCOM_DBI_USER

Username to use for the database connection.

INCOM_DBI_PASSWD

Password to use for the database connection.

INCOM_DBI_TRACE

Sets the tracing level for the connection.

INCOM_DBI_LOG

File where the DBI(3) trace output will go.

INCOM_SEARCH_PROFILE

DBIx::SearchProfiles(3) profile file that will be used to configure the $DB object accessible in Apache:iNcom pages. If non-absolute, it is relative to the server's root. Defaults to conf/search_profiles.pl relative to the server's root.

See DBIx::SearchProfiles(3) for details on the format of this file.

To turn off the use of the search profiles set this directive to NONE.

PROFILES DIRECTIVES

INCOM_INPUT_PROFILE

Sets the input profile that will be used to initialize the $Validator object. Defaults to conf/input_profiles.pl relative to server's root.

See HTML::FormValidator(3) for details on the format of this file.

To turn off the creation of an input profile set this directive to NONE.

INCOM_PRICING_PROFILE

Sets the pricing profile that will be used to initialize the $Cart object. Defaults to conf/pricing_profile.pl relative to server's root.

See Apache::iNcom::CartManager(3) for details on the format of this file.

If you don't need the cart management feature, set this directive to NONE.

INCOM_ORDER_PROFILE

Sets the order profiles file that will be used to initialize the $Order object. Defaults to conf/order_profiles.pl relative to server's root.

See Apache::iNcom::OrderManager(3) for details on the format of this file.

If you don't need this feature, you can set this directive to NONE.

USERDB DIRECTIVES

INCOM_USERDB_PROFILE: Name of the profile to use for the user database. Defaults to userdb. See DBIx::UserDB(3) for more information. To disable the use of a DBIx::UserDB object, sets this directives to NONE.
INCOM_GROUPDB_PROFILE: Name of the profile to use for the group database access. Defaults to groupdb. See DBIx::UserDB(3) for more information.
INCOM_SCRAMBLE_PASSWORD: Turn on or off scrambling of user's password in the UserDB.

LOCALIZATION DIRECTIVES

INCOM_DEFAULT_LANGUAGE: The language of the files without a language extension. Defaults to en.
INCOM_LOCALE: The package uses to create Locale::Maketext(3) instance. If this is set, an instance appropriate for the user's locale will be available through the $Locale object.

SESSION DIRECTIVES

INCOM_SESSION_SERIALIZE_ACCESS: Set this to 1 to serialize access through session. This will make sure that only one session's request is processed at a time. You should set this to 1 if your site uses frameset.
INCOM_SESSION_SECURE: Sets this to true if you want the cookie that contains the session id to be only transmitted over SSL connections. Be aware that setting this variable to true will require that all Apache::iNcom transactions be conducted over SSL.
INCOM_SESSION_DOMAIN: The domain to which the Apache::iNcom session's cookie will be transmitted. You can use this, if you are using a server farm for example.
INCOM_SESSION_PATH: The path under which the session id is valid. Defaults to INCOM_URL_PREFIX.
INCOM_SESSION_EXPIRES: The time for which the use session is valid. Defaults is for a browser session. (Once the user exists its browser session will become invalid).

ERROR HANDLING DIRECTIVES

INCOM_ERROR_PROFILE: The error profile that will be used for displaying server error.
INCOM_ERROR_ROOT: The directory which contains error pages. If a non absolute path is specified, it is relative to the server's root.

SESSION HANDLING

On the user's first request, a new session is created. Each and every other request will be part of a session which will used to track the user's cart and other such things.

The session id is returned to the user in a cookie. COOKIES MUST BE ENABLED for Apache::iNcom to function. Fortunately, Apache::iNcom detects if the user has cookies turned off and will send the user an error.

Cookies are used for security and confidentiality. The session id is a truly random 128bits number, which is make it very much unguessable. That means that you can't try to stomp into another user's session. That is a good thing since having access to the session id means having access to a whole bunch of informations. (What information is application specific.) IP address aren't used to restrict the session access because of the various problems with proxies and other Internet niceties.

Now, what has this to do with cookies ? Well, using URL rewriting was originally considered, but then two big issues cralwed in : proxies and the Referer header. Having the session id embedded in the URL means that our precious session id will be stored in various log files across multiple server (web server, proxy server, etc) This is a bad thing. Also, must request contains a Referer header which means that the session id is likely to leak to third party sites which are linked from your site (or not, Netscape used to send the header even if the user only typed in the new URL while viewing your page). This is another bad thing, and this is why we are using cookies.

APACHE::INCOM PAGES

Apache::iNcom pages are HTML::Embperl pages with some extra variables and functions available. See Apache::iNcom::Request(3) for details. You may also which to consult the HTML::Embperl documentation for syntax. Additionnaly, the normal $req_rec object in the page is an instance of Apache::Request(3) so that you can handle multipart upload.

DATABASE CONNECTIVITY

The database connection is opened once per request and shared by all modules that must use it. Database access is mediated through the use of the DBIx::SearchProfiles(3) module.

Connections are opened in commit on request mode. The database connection is commit after the page is executed. If an error occurs, the transaction will be rolled back. The application may elect to commit part of the transaction earlier.

CART MANAGEMENT

See Apache::iNcom::CartManager(3) for details.

ORDER MANAGEMENT

See Apache::iNcom::OrderManager(3) for details.

USER MANAGEMENT

User management is handled through the DBIx::UserDB(3) module.

LOCALIZATION

Apache::iNcom is designed to make it easy to adapt your e-commerce application to multiple locale.

The framework uses Locale::Maketext(3) for message formatting.

All pages may have a localized version available. The localized should have an extension describing its language. (.en for English, .fr for French, .de for German, etc.)

The user locale will be negotiated through the Accep-Language header which is part of the HTTP protocol. It can also be set explicitely by sending the user to a special link (since not many users took the time to configure their browser for language negotiation).

The URL :

I<INCOM_URL_PREFIX>/incom_set_lang/I<LANG>

This will set the language to use in the user's session.

SECURITY

Apache::iNcom has been with security has one of its primary design goal.

Session ID are 128bits truly random number.
Session ID are transmitted only by cookies to assure confidentiality.
There are no user transmitted magic variables. Form data doesn't act upon the framework. All actions are triggered by the application and not the user. All form data that should be used for action are determined by the application through the various profiles. This means that you won't be burned by a magic feature that sprung without you knowing it.
Regular access control of Apache can be used. Also see the ACLs mechanism offered by the DBIx::UserDB(3) for access control with finer resolution than URL or file based.
SSL can (and should) be used to assure confidentiality.
Executable content (pages) that shouldn't be directly accessible from the user (include file, error pages, etc) can be kept in separate directory which aren't accessible directly.

The major (current) security limitations is that the application programmer is trusted. Apache::iNcom pages have complete control over the Apache server environment in which they run. Keep this in mind when running multiple sites. Future version will use the Safe(3) module to improve on this.

MULTIPLE CATALOGS

Multiple e-commerce sites can easily be run by using the VirtualHost capability of apache.

PERFORMANCE AND SCALABILITY

No state is kept between requests which makes it easy to scale the load on Apache::iNcom across multiple server.

mod_perl general tips for improving performance should be applied. See the mod_perl guide for details (http://perl.apache.org/guide/).

ERROR HANDLING

Error are handled in a way similar to the ErrorDocument functionality. The error profile is an file which should eval to an hash reference. Keys are error number and values are the file that should be returned on error. The pages are assumed to be relative to the INCOM_ERROR_ROOT directory, or if unspecified the INCOM_ROOT.

If a localized version of the page exists, that one will be use. The page will be executed as a normal Apache::iNcom pages. Error are keyed either by the HTTP response code (404,403,500, etc) or by an arbitrary key for application specific error. In order to return an arbitrary error, you set the pnote INCOM_ERROR in the page before returning an error.

    Example: $req_rec->pnotes( "INCOM_ERROR", "validation_failed" );
	     die "validation_failed";

The page linked to the "validation_failed" key in the error profile will be used.

The "no_cookies" key is used to find the error page to return in case the user has turned off cookies.

In the case of an error handler trigerred by an error in an HTML::Embperl page. The error page will received in the @param array the error messages emitted by HTML::Embperl.

AUTHOR

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)