|
| 1 | +--- |
| 2 | +summary: "Persisted Drive changes and Docs comment polling" |
| 3 | +read_when: |
| 4 | + - Running gog as a local Drive or Docs event poller |
| 5 | + - Wiring Drive changes or Docs comments to shell hooks |
| 6 | +--- |
| 7 | + |
| 8 | +# Drive and Docs polling |
| 9 | + |
| 10 | +`gog` can poll Drive changes or Google Docs comments while persisting the API |
| 11 | +cursor in a local JSON file: |
| 12 | + |
| 13 | +```bash |
| 14 | +gog drive changes poll \ |
| 15 | + --state-file ~/.local/state/gog/drive-changes.json \ |
| 16 | + --interval 30s \ |
| 17 | + --json |
| 18 | + |
| 19 | +gog docs comments poll <docId> \ |
| 20 | + --state-file ~/.local/state/gog/doc-comments.json \ |
| 21 | + --interval 30s \ |
| 22 | + --json |
| 23 | +``` |
| 24 | + |
| 25 | +Both commands poll immediately, then wait for `--interval`. Use |
| 26 | +`--max-iterations N` for bounded jobs and tests. `SIGINT` and `SIGTERM` stop the |
| 27 | +poller; completed iterations have already persisted their cursor. |
| 28 | + |
| 29 | +## State |
| 30 | + |
| 31 | +State files are written atomically with mode `0600`. Missing and empty state |
| 32 | +files initialize without replaying existing history: |
| 33 | + |
| 34 | +- Drive stores a fresh start page token before its first changes request. |
| 35 | +- Docs stores the current time as its initial comment watermark. |
| 36 | + |
| 37 | +Drive state is scoped to `--drive`. Docs state is scoped to the document and |
| 38 | +the `--include-resolved` setting. Delete the state file or choose a new path to |
| 39 | +start a new stream. Run only one poller against a state file; concurrent writers |
| 40 | +can overwrite each other's cursor. |
| 41 | + |
| 42 | +The Drive comments API time filter is inclusive. State therefore records both |
| 43 | +the latest timestamp and comment IDs already delivered at that timestamp. |
| 44 | +Comments that share a modified time are delivered once without moving the |
| 45 | +watermark past an unseen peer. |
| 46 | + |
| 47 | +## Output |
| 48 | + |
| 49 | +With `--json`, stdout is newline-delimited JSON: one object per non-empty Drive |
| 50 | +batch or Docs comment. Plain and human modes emit one tab-separated line per |
| 51 | +change or comment. Empty polls produce no stdout. |
| 52 | + |
| 53 | +`drive changes poll --filter-file <fileId>` filters emitted changes and hook |
| 54 | +payloads, while the underlying Drive page token still advances. |
| 55 | + |
| 56 | +## Shell hooks |
| 57 | + |
| 58 | +Hooks are explicit trusted local shell commands: |
| 59 | + |
| 60 | +```bash |
| 61 | +gog drive changes poll \ |
| 62 | + --state-file drive.json \ |
| 63 | + --on-change './handle-drive-batch' |
| 64 | + |
| 65 | +gog docs comments poll <docId> \ |
| 66 | + --state-file comments.json \ |
| 67 | + --on-new './handle-comment' |
| 68 | +``` |
| 69 | + |
| 70 | +Payload JSON is passed on stdin. Google-provided text is never interpolated |
| 71 | +into the command string. Hook stdout and stderr go to `gog` stderr so event |
| 72 | +stdout remains parseable. |
| 73 | + |
| 74 | +Hooks run through the platform shell and are not sandboxed. Use only fixed, |
| 75 | +operator-controlled commands; do not build the hook string from Google content. |
| 76 | + |
| 77 | +Drive invokes `--on-change` once per non-empty filtered batch. Docs invokes |
| 78 | +`--on-new` once per comment, in modified-time and comment-ID order. Hooks run |
| 79 | +sequentially. |
| 80 | + |
| 81 | +State advances only after output and all hooks succeed. Output or hook failure |
| 82 | +returns an error and retains the previous cursor, so the event is retried on |
| 83 | +the next run. Consumers must tolerate duplicate delivery. |
| 84 | + |
| 85 | +Command pages: |
| 86 | + |
| 87 | +- [`gog drive changes poll`](commands/gog-drive-changes-poll.md) |
| 88 | +- [`gog docs comments poll`](commands/gog-docs-comments-poll.md) |
0 commit comments