Settings

Available Settings

These are the default settings for DSG, with explanations provided below. These settings should be defined under the GRPC_FRAMEWORK variable in django settings.

See the documentation on django settings if your not familiar with it: Django settings documentation.

GRPC_FRAMEWORK = {
  "ROOT_HANDLERS_HOOK": None,
  "SERVER_INTERCEPTORS": None,
  "SERVER_OPTIONS": None,
  "DEFAULT_AUTHENTICATION_CLASSES": [],
  "DEFAULT_FILTER_BACKENDS": [],
  "DEFAULT_PAGINATION_CLASS": None,
  "DEFAULT_PERMISSION_CLASSES": [],
  "GRPC_ASYNC": False,
  "GRPC_CHANNEL_PORT": 50051,
  "SEPARATE_READ_WRITE_MODEL": True,
  "GRPC_MIDDLEWARE": [
    "django_socio_grpc.middlewares.log_requests_middleware",
    "django_socio_grpc.middlewares.close_old_connections_middleware",
  ],
  "ROOT_GRPC_FOLDER": "grpc_folder",
  "MAP_METADATA_KEYS": {
    "HEADERS": "HEADERS",
    "PAGINATION": "PAGINATION",
    "FILTERS": "FILTERS",
  },
  "LOG_OK_RESPONSE": False,
  "IGNORE_LOG_FOR_ACTION": [],
  "FILTER_BEHAVIOR": "METADATA_STRICT",
  "PAGINATION_BEHAVIOR": "METADATA_STRICT",
  "DEFAULT_MESSAGE_NAME_CONSTRUCTOR": "django_socio_grpc.protobuf.message_name_constructor.DefaultMessageNameConstructor",
  "ENABLE_HEALTH_CHECK": False,
}

ROOT_HANDLERS_HOOK

This setting points to the grpc_handlers function responsible for registering all gRPC Services for the project’s applications.

This function runs just before the start of the server, making it useful for any other kind of initialization

See Register services section in the Getting Started documentation for quick example of Service Registry for complete understanding and recommandation.

For a project named “my_project” with the grpc_handlers function inside my_project/handlers.py, the configuration would be:

"ROOT_HANDLERS_HOOK": "my_project.handlers.grpc_handlers"

SERVER_INTERCEPTORS

Note

SERVER_INTERCEPTORS settings allow you to make actions at the grpc request level. To have all the DSG functionnalities like request.user and more please use GRPC_MIDDLEWARE setting

This setting specifies a list of gRPC server interceptors. Interceptors allow you to run custom code before or after a gRPC method gets executed. Common uses for interceptors include logging, authentication, and request/response transformations.

Example:

Consider you have two interceptors, LoggingInterceptor and AuthenticationInterceptor. These interceptors would be added to the SERVER_INTERCEPTORS setting as:

"SERVER_INTERCEPTORS": [LoggingInterceptor(), AuthenticationInterceptor()],

With this configuration, every gRPC method invocation will first pass through the LoggingInterceptor and then the AuthenticationInterceptor before the actual gRPC method is executed.

See the ServerInterceptor documentation for Python : sync and async.

SERVER_OPTIONS

This setting defines a list of key-value pairs specifying options for the gRPC server. These options help configure server behavior, such as setting limits on the size of incoming or outgoing messages.

Example if you want to set the maximum size for sending and receiving messages to 100MB, you can configure the SERVER_OPTIONS as:

"SERVER_OPTIONS": [
  ("grpc.max_send_message_length", 100 * 1024 * 1024),
  ("grpc.max_receive_message_length", 100 * 1024 * 1024),
],

The above configuration allows the gRPC server to send and receive messages up to a size of 100MB.

For more options, see the grpc documentation.

DEFAULT_AUTHENTICATION_CLASSES

Defines the list of authentication classes the gRPC server uses to validate incoming requests. Requests are authenticated based on the methods provided by these classes, in the order they are listed.

Example if you want to set a custom Authentication class your_project.auth.JWTAuthentication, you can configure the DEFAULT_AUTHENTICATION_CLASSES as:

"DEFAULT_AUTHENTICATION_CLASSES": [
  "your_project.auth.JWTAuthentication"
]

For more details, see the DRF documentation on auth as DSG use the same system.

DEFAULT_FILTER_BACKENDS

This setting designates the default filtering backends that gRPC services should use. Filtering backends allow requests to be filtered based on query parameters.

For instance, to use django-filter backend (doc):

"DEFAULT_FILTER_BACKENDS": ["django_filters.rest_framework.DjangoFilterBackend"]

For more details, see the DRF documentation on filters as DSG use the same system.

DEFAULT_PAGINATION_CLASS

Defines the default pagination class for gRPC services. This class will be used to paginate large datasets in the response.

Example configuration to use the PageNumberPagination <https://www.django-rest-framework.org/api-guide/pagination/#pagenumberpagination> class:

"DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination"

For more details, see the DRF documentation on doc as DSG use the same system.

DEFAULT_PERMISSION_CLASSES

This setting defines the list of default permissions classes that will be used for gRPC services. Each class specified in this list will be responsible for verifying the identity of the user making the request.

For a hypothetical project that uses DRF IsAuthenticated and a custom HasServiceAccess permissions :

"DEFAULT_PERMISSION_CLASSES": [
    "rest_framework.permissions.IsAuthenticated",
    "your_project.permissions.HasServiceAccess",
]

For more details, see the DRF documentation on permissions as DSG use the same system.

Note

All DRF permissions are supported out of the box.

GRPC_ASYNC

This setting determines the running mode of the gRPC server. If set to True, the server will operate in asynchronous mode. When in asynchronous mode, the server is capable of handling multiple concurrent requests using Python’s asyncio.

This setting is overriden to True when running the project with grpcrunaioserver command and to False when running the project with grpcrunaioserver.

Please consider to always use async as it may become the only accepted behavior in DSG 1.0.

"GRPC_ASYNC": True

GRPC_CHANNEL_PORT

This is the default port on which the gRPC server will listen for incoming requests. You can change this if your server needs to listen on a different port.

This settigns will only be used if grpcrunaioserver or grpcrunaioserver parameter address is not used.

"GRPC_CHANNEL_PORT": 50051

SEPARATE_READ_WRITE_MODEL

The SEPARATE_READ_WRITE_MODEL setting determines whether to use separate request and response messages for a model, primarily to activate the read_only and write_only properties of a serializer. This ensures more granular control over serialized data, where some fields can be made read-only or write-only.

By enabling this option (set to True), it ensures that specific fields in a model can be set to be write-only during a write operation and will not be exposed during a read operation, and vice versa for read-only fields. This is particularly useful when certain data should be kept private or when different sets of data should be exposed for reading vs. writing.

For instance, if you have fields in your model that should only be updated but never retrieved in a response, you can mark them as write_only. Similarly, fields that should be displayed but never modified can be marked as read_only.

Please consider to always separate read/write model as it may become the only accepted behavior in DSG 1.0.

"SEPARATE_READ_WRITE_MODEL": True

GRPC_MIDDLEWARE

This setting defines a list of middleware classes specifically tailored for the gRPC framework. Middleware in gRPC can be seen as a series of processing units that handle both incoming requests and outgoing responses. They can be used for various tasks like logging, authentication, data enrichment, and more.

Middlewares are processed in the order they are defined. Each middleware should adhere to the gRPC middleware structure, having methods to process requests and responses. More details about middlewares.

The difference with a gRPC Interceptor is that the middlewares occur at the Django level, meaning the request has already been wrapped into a Django-like request. Interceptors handle pure gRPC calls.

For instance, you could have a generic logging middleware that logs every gRPC request and a middleware to handle connection issues:

"GRPC_MIDDLEWARE": [
    "your_project.middlewares.GenericLoggingMiddleware",
    "your_project.middlewares.ConnectionHandlingMiddleware",
]

ROOT_GRPC_FOLDER

This setting specifies the root directory name where all the generated proto files of external services are outputted. More details about how to define proto and service in a shared library.

"ROOT_GRPC_FOLDER": "my_root_grpc_folder"

MAP_METADATA_KEYS

This setting defines where the framework should look within the metadata for specific pieces of information like headers, pagination data, and filters. Essentially, it provides mapping keys that indicate where to extract certain types of metadata.

For a standard configuration, you might have:

"MAP_METADATA_KEYS": {
    "HEADERS": "HEADERS",
    "PAGINATION": "PAGINATION",
    "FILTERS": "FILTERS",
}

This means that when the framework encounters metadata, it knows to look for a HEADERS key to retrieve headers, a PAGINATION key to fetch pagination data, and a FILTERS key for filtering details.

Note

See specific documentation for each:

HEADERS : Authentication
FILTERS: Filters
PAGINATION: Coming soon

LOG_OK_RESPONSE

This setting enables the logging of requests that return an OK. (see logging) Default is False. Being in DEBUG mode enables it.

"LOG_OK_RESPONSE": True

IGNORE_LOG_FOR_ACTION

When using Log requests middleware allow to specify a list of action that we do not want to automatically log.

"IGNORE_LOG_FOR_ACTION": ["Service1.Action1", "Service1.Action1"]

PRIVATE_KEY_CERTIFICATE_CHAIN_PAIRS_PATH

List of pair of key/server certificate to use gRPC secure port mechanisme. See Work with secure port.

"PRIVATE_KEY_CERTIFICATE_CHAIN_PAIRS_PATH": [("/path/to/server-key.pem", "/path/to/server.pem")]

ROOT_CERTIFICATES_PATH

Client root certificate path that server will use to verify client authentication. See Work with secure port.

"ROOT_CERTIFICATES_PATH": "/path/to/certificates.pem"

REQUIRE_CLIENT_AUTH

A boolean indicating whether or not to require clients to be authenticated. May only be True if ROOT_CERTIFICATES_PATH is not None. See Work with secure port.

"REQUIRE_CLIENT_AUTH": True

FILTER_BEHAVIOR

Warning

Default behavior will change in 1.0.0 to accept only request filtering. If you start a new project please consider setting FILTER_BEHAVIOR to REQUEST_STRUCT_STRICT

Variable allowing user to configure how the filter work.

The differents options are described in django_socio_grpc.settings.FilterAndPaginationBehaviorOptions()

from django_socio_grpc.settings import FilterAndPaginationBehaviorOptions

"FILTER_BEHAVIOR": FilterAndPaginationBehaviorOptions.METADATA_STRICT

PAGINATION_BEHAVIOR

Warning

Default behavior will change in 1.0.0 to accept only request filtering. If you start a new project please consider setting PAGINATION_BEHAVIOR to REQUEST_STRUCT_STRICT

Variable allowing user to configure how the pagination work.

The differents options are described in django_socio_grpc.settings.FilterAndPaginationBehaviorOptions()

from django_socio_grpc.settings import FilterAndPaginationBehaviorOptions

"PAGINATION_BEHAVIOR": FilterAndPaginationBehaviorOptions.METADATA_STRICT

DEFAULT_MESSAGE_NAME_CONSTRUCTOR

Variable that indicate the class used to generate the name of the proto messages. Default is DefaultMessageNameConstructor.

For more informations see the documentation

"DEFAULT_MESSAGE_NAME_CONSTRUCTOR": "django_socio_grpc.protobuf.message_name_constructor.DefaultMessageNameConstructor"

DEFAULT_GENERATION_PLUGINS

List of class inherited from BaseGenerationPlugin to specify plugin that are used globally for all actions.

See documentation

"DEFAULT_GENERATION_PLUGINS": ["django_socio_grpc.protobuf.generation_plugin.FilterGenerationPlugin"]

ENABLE_HEALTH_CHECK

A boolean indicating wether or not the health checking is enabled. Default is False.

For more informations see the documentation

"ENABLE_HEALTH_CHECK": False