Corteza Documentation

The corredor package serves as an interface to the Corredor script runner service. It is used to manage script execution and event-driven workflows within the Corteza ecosystem. It provides three primary capabilities:

1. Connection to Corredor service: Establishes the communication link with the script runner.
2. Subscriber service: Handles events raised from various Corteza services, allowing for reactive logic.
3. Scheduling service: Manages deferred events, supporting both one-time scheduled events and recurring interval-based events.

The Corteza authentication subsystem manages the following security and identity workflows:

• Sign-up protocol: Handling new user registration.
• Local login: Facilitating local authentication via the OAuth2 protocol.
• Password management: Protocols for setting and resetting user passwords.
• Email authentication: Managing authentication flows that rely on email verification.
• Session management: Handling user sessions and lifecycle.
• Identity federation: Allowing users to log in via external identity providers.
• OAuth2 flows: Supporting various OAuth2 authentication flows.

A Handler is a combination of event matching rules (constraints) and a callback function. The callback is executed when a fired event satisfies all registered rules and constraints.

Constraints and Matching Logic

• Matching: The Matcher function is called once for each constraint registered to a handler.
• Short-circuiting: All constraints must match for the handler to trigger. The first constraint that does not match will break the checking procedure.
• Default Behavior: A handler registered without any constraints is considered a match for any event that satisfies the basic resource and event type filtering.

Execution Order

• Weight: Use the Weight property to control the order in which multiple handlers are executed.

Corteza Discovery uses an EventBus to monitor resource lifecycles. It listens for afterCreate, afterUpdate, and afterDelete events to update the indexable resources table.

Soft-delete behavior:

• For resources that support soft-delete, they are removed from public and protected indexes.
• However, the private index retains deleted resources to allow for continued searching through them.

Corteza uses a specific numeration scheme for provisioning files to categorize resources and prevent collisions. When creating or managing configuration files, follow these prefix rules:

• 0xx: Base resources, configuration, and access control rules.
• 1xx: Additional resources.
• 2xx through 6xx: Reserved for internal use.
• 7xx: Reserved for extensions.
• 8xx: Reserved for custom or user-defined configuration.
• 9xx: Reserved for temporary, deprecated, or obsolete files.

Corteza Discovery uses specific authentication clients, roles, and users to manage how resources are indexed based on their visibility. When Discovery is installed, three distinct combinations are provisioned to allow an indexing service to connect with restricted privileges:

1. Public indexing: For resources accessible to everyone.
2. Protected indexing: For resources with restricted access.
3. Private indexing: For sensitive resources.

Security implementation details:

• Auth clients use the client_credentials grant.
• Auth clients are restricted to the discovery scope.
• Each role is configured as a 'forced role' on the client, and each client acts as an 'impersonated user'.
• This allows an indexer to configure multiple indexes with different credentials to control data availability and schema per index.

Index access restrictions, referred to as iar, determine the visibility level of a resource. The possible values are:

• public
• protected
• private

Note: Some resource types cannot be accessed via the public restriction.

Index Naming Convention: Index names follow a logical structure: <prefix-for-distinction>-<iar>-<resource-like-suffix>.

Examples:

• corteza-private-system-users
• corteza-private-compose-records-1-2 (where 1 is the namespaceID and 2 is the moduleID)

Developers looking to contribute to the Corteza Server should refer to the Developer Guide/Corteza Server for details on:

• Development Setup: How to configure your local machine for server development.
• Project Structure: Understanding the codebase organization.
• Feature Insight: Documentation on specific features and implementation details.

To log and measure database activities (connections, queries, executions, and transactions) and their durations, you must append the debug parameter to your Database Source Name (DSN).

Warning: This feature is intended for development environments only. Do not enable this in production as it logs all database activities.

DB_DSN="postgres+debug://crust:crust@localhost:5432/crust?sslmode=disable&"

To upgrade an existing Corteza installation, you must consult both the version history and the specific procedure for your version:

1. Check the changelog for changes and breaking updates.
2. Follow the upgrade guide for step-by-step instructions.