Source
- acme
- user
- v2
session.proto
proto3 · package acme.user.v2
1
syntax = "proto3";3
// Session lookup for accounts defined in the Acme v1 user API.4
//5
// ## In this package6
//7
// | Type | Purpose |8
// | --- | --- |9
// | [Session](../../messages/acme.user.v2.Session/) | An account session and its expiration time. |10
// | [SessionService](../../services/acme.user.v2.SessionService/) | Read a session by identifier. |11
//12
// ## Getting started13
//14
// 1. Read the Session page for its fields and JSON representation.15
// 2. Follow SessionService to inspect the `GetSession` HTTP binding.16
// 3. Visit the [v1 user package](../acme.user.v1/) for the embedded account type.17
//18
// > **Versioning:** `acme.user.v2.Session` refers to `acme.user.v1.User`.19
// > The package version identifies the session API; it does not replace v1.20
package acme.user.v2;22
import "acme/user/v1/user.proto";23
import "google/api/annotations.proto";24
import "google/api/field_behavior.proto";25
import "google/protobuf/timestamp.proto";27
option go_package = "acme.example/user/v2;userv2";29
// A signed-in session for a v1 user account.30
//31
// ## Session fields32
//33
// | Field | Direction | Purpose |34
// | --- | --- | --- |35
// | `id` | Output only | Identifier of this session. |36
// | `user` | Required | The account associated with the session. |37
// | `expires_at` | Optional | Expiration time, when supplied. |38
//39
// The v2 session API reuses the [v1 User message](../acme.user.v1.User/).40
// A new API package can introduce session operations without duplicating the41
// account schema or changing the version of every related message.42
//43
// ## Example JSON44
//45
// This illustrates the `session` value inside a `GetSessionResponse`.46
// Timestamps use RFC 3339 strings in the47
// [ProtoJSON mapping](https://protobuf.dev/programming-guides/json/).48
//49
// ```json50
// {51
// "id": "session-example-001",52
// "user": {53
// "id": "550e8400-e29b-41d4-a716-446655440000",54
// "email": "alex@example.com",55
// "displayName": "Alex Chen",56
// "state": "USER_STATE_ACTIVE"57
// },58
// "expiresAt": "2026-01-15T10:30:00Z"59
// }60
// ```61
//62
// ## Working with expiration63
//64
// - Check whether `expires_at` is present before reading its value.65
// - Interpret a supplied timestamp as an instant, independent of display zone.66
// - Keep authentication and expiration enforcement in the service implementation.67
//68
// > **Versioning:** the embedded user still uses the v1 definition, including69
// > its validation rules and PII annotations. The session itself belongs to v2.70
message Session {71
// Session identifier. **Output only**; keep it opaque to clients.72
string id = 1 [(google.api.field_behavior) = OUTPUT_ONLY];73
// Associated account, using the shared `acme.user.v1.User` schema.74
acme.user.v1.User user = 2 [(google.api.field_behavior) = REQUIRED];75
// Expiration instant, if supplied; format with the reader's time zone.76
google.protobuf.Timestamp expires_at = 3;77
}79
// Identifies the session to read. The `id` field is **required**.80
message GetSessionRequest {81
string id = 1 [(google.api.field_behavior) = REQUIRED];82
}84
// Wraps the returned account session in the `session` field.85
message GetSessionResponse {86
Session session = 1;87
}89
// Reads active sessions.90
//91
// ## Reading a session92
//93
// 1. Put the session identifier in `GetSessionRequest.id`.94
// 2. Call `GetSession` over gRPC or use its HTTP binding.95
// 3. Inspect the returned [Session message](../../messages/acme.user.v2.Session/)96
// and its embedded [v1 User](../../messages/acme.user.v1.User/).97
//98
// | RPC | HTTP binding | Response field |99
// | --- | --- | --- |100
// | `GetSession` | `GET /v2/sessions/{id}` | `session` |101
//102
// > This is an example API definition. The generated documentation does not103
// > run a session service or issue session identifiers.104
service SessionService {105
// Read a session by its identifier, without side effects.106
//107
// ## HTTP example108
//109
// For a deployment at `https://api.example.com`:110
//111
// ```sh112
// curl --request GET \113
// 'https://api.example.com/v2/sessions/session-example-001'114
// ```115
//116
// The HTTP annotation binds `{id}` to the request field. The method is marked117
// `NO_SIDE_EFFECTS`; authentication and error responses are not specified here.118
rpc GetSession(GetSessionRequest) returns (GetSessionResponse) {119
option (google.api.http) = { get: "/v2/sessions/{id}" };120
option idempotency_level = NO_SIDE_EFFECTS;121
}122
}