syntax = "proto3";

package at_jet.example;

import "google/protobuf/field_mask.proto";

// User message
message User {
  int32 id = 1;
  string name = 2;
  string email = 3;
  int64 created_at = 4;
}

// Create user request
message CreateUserRequest {
  string name = 1;
  string email = 2;
}

// Update user request
//
// Why FieldMask instead of 'optional' keyword?
// -------------------------------------------------
// Proto3 introduced the 'optional' keyword for explicit field presence in protoc 3.15
// (released Feb 2021). However, many LTS Linux distributions still ship older versions:
//   - Ubuntu 20.04: protoc 3.6
//   - Ubuntu 22.04: protoc 3.12
//   - Debian 11:    protoc 3.12
// These versions reject 'optional' with: "Explicit 'optional' labels are disallowed
// in the Proto3 syntax."
//
// FieldMask is the standard, protoc-version-agnostic pattern for partial updates,
// widely used in Google APIs. It works with any proto3-compatible protoc version.
//
// How to use update_mask:
//   - If update_mask is empty, all fields will be updated
//   - If update_mask contains specific paths (e.g., ["name"]), only those fields are updated
//
// Example usage:
//   To update only the name:  { id: 1, name: "new_name", update_mask: { paths: ["name"] } }
//   To update both fields:    { id: 1, name: "new_name", email: "new@email.com", update_mask: { paths: ["name", "email"] } }
message UpdateUserRequest {
  int32 id = 1;
  string name = 2;
  string email = 3;
  // Specifies which fields to update. If empty, all fields will be updated.
  google.protobuf.FieldMask update_mask = 4;
}

// List users request
message ListUsersRequest {
  int32 page = 1;
  int32 page_size = 2;
}

// List users response
message ListUsersResponse {
  repeated User users = 1;
  int32 total = 2;
  int32 page = 3;
  int32 page_size = 4;
}

// Delete user response
message DeleteUserResponse {
  bool success = 1;
  string message = 2;
}

// Empty message for requests/responses with no body
message Empty {}
