Routing

GOX uses a routing by filesystem.

The location of each file within the directory pages/ automatically determines the URL from which it will be accessible.

This approach eliminates the need to record routes manually and keeps the project structure synchronized with the application structure.

pages/
├── index.gox
├── about.gox
└── users/
    ├── users.gox
    └── profile.gox

generates the following routes.

/
/about
/users
/users/profile

The pages are automatically discovered during the compilation.

General rule

Each file .gox directory pages/ It generates a route.

The route is obtained using the file location within the directory pages/.

pages/about.gox

↓

/about

pages/admin/users.gox

↓

/admin/users

The subdirectories simply add new segments to the URL.

There is no need to register the routes manually.

The main route

The file:

pages/index.gox

represents the main page of the application.

Its canonical route is:

/

Internally GOX also allows access by:

/index

However, this route exists only by compatibility with the internal operation of the server.

It is recommended to always use the root route (/) to represent the main page of an application.

Organization of directories

GOX does not interpret the directories' names in a special way.

For example:

pages/admin/index.gox

generates the route:

/admin/index

It does not automatically respond to:

/admin

The same way:

pages/blog/articles/post.gox

genera:

/blog/articles/post

Each folder adds a new segment to the URL.

Route resolution

When a route can be solved by more than one file, GOX uses a priority order.

For example:

pages/
├── users.gox
└── users/
    └── users.gox

Both files can respond to:

/users

In this case GOX uses:

pages/users.gox

The file:

pages/users/users.gox

only used when there is no equivalent route defined by pages/users.gox.

Private modules

Not all files .gox located within the directory pages/ they generate a public route.

Any file whose name contains more than one point is considered a private module.

For example:

user.menu.gox

permissions.user.gox

login.action.gox

.validation.gox

Private modules can normally be imported from other modules .goxbut they do not generate an accessible page using a URL.

Organization

The rule does not require a private module to share the name of a page.

For example, the next structure is completely valid.

pages/
└── dashboard/
    ├── user.gox
    ├── .menu.gox
    ├── otronombre.sidebar.gox
    ├── permissions.user.gox
    ├── login.action.gox
    ├── disconnect.service.gox
    └── user.validation.gox

The only public route generated by this structure is:

/dashboard/user

The other modules may contain components, helpers, services, validations or any other reusable logic.

Recommended convention

Although private modules can have any valid name, it is usually easier to organize them using the same name of the page they belong to.

pages/
└── dashboard/
    ├── user.gox
    ├── user.menu.gox
    ├── user.sidebar.gox
    ├── user.permissions.gox
    ├── user.service.gox
    └── user.validation.gox

This convention allows you to quickly identify all the modules related to a page and keep them grouped within the same directory.

It is not a system restriction, but a recommendation to improve the organization of the project.

File names

File and directory names are part of the URL.

GOX automatically normalizes all routes using small cases to maintain consistent behaviour between different operating systems and avoid duplicate routes that differ only by the use of capital letters.

For this reason, it is recommended to always use file names and directories in small cases.

Custom routing

The filesystem routing covers most applications without additional configuration.

However, GOX also allows to fully customize the routing behavior by configuring the project.

The custom routing allows:

• Create aliases for existing routes.
• Define route parameters.
• Use optional parameters.
• Use alternative segments.
• Define wildcards routes.
• Convert static routes to dynamic routes.
• Keep public URLs independent of directory organization pages/.

For example, a URL such as:

/imagen.png

you can respond using the page:

pages/images/create.gox

without changing the URL visible to the user.

In this way it is possible to maintain a simple internal structure while fully customised URLs are exposed.

See Server Configuration to learn how to set up custom routes.

Philosophy

GOX uses filesystem as the main source of information to build the routing of an application.

Instead of manually recording each route, the directory structure pages/ automatically defines the public structure of the site.

This approach reduces repetitive configuration, facilitates project navigation and keeps URLs synchronized with code organization.

When an application needs more advanced behavior, the custom routing system allows you to extend these rules without losing the advantages of routing by filesystem.

Best practices

• Organizes the pages using directories that reflect the structure of the application.
• Keep the modules related to a page together provided it facilitates the navigation of the project.
• It uses short and descriptive names for files.
• Always use file names and directories in small cases.
• Book the custom routing for cases where the routing by filesystem is not enough.
• Use pages/index.gox only for the main page of the application.

To learn more about Pages, check your documentation.

See also

• Pages
• Server Configuration

Cache for missing routes

GOX can temporarily remember a route that does not correspond to a page. 404 returned by an existing handler is not saved in this cache: a later request must be able to run the page again with other data, cookies or permissions.

The consultation of this cache is done after solving the session and applying rate limit, so that a 404-cached response does not omit those stages.

The cache supports up to 4096 routes, with an expiry of 30 seconds, and does not record skates of more than 2048 bytes. By reaching the limit it discards new entries until there is space; the request continues to be resolved normally. The observed file changes and configuration recharges invalidate the entries so that a new route or an alias does not continue to respond with a previous 404.

The disk snapshot is written at most every 30 seconds if there are changes and when the runtime is closed. It is not restored when starting: the files and rules may have changed while the server was stopped. The persistence worker stops during the closure.