Errors

#!/usr/bin/env bash
# filmo-request.sh: one function for any call to the Filmo REST API.
# Needs curl and jq, and FILMO_API_KEY; FILMO_BASE_URL is optional.
#
#   filmo_request METHOD PATH [JSON_BODY]      (put the query string in PATH)
#
# Writes get an Idempotency-Key: IDEMPOTENCY_KEY if set, else a fresh UUID. The
# query POSTs (availability checks, contacts lookup, ai ask) do not declare the header, so they get none.
# Set NO_IDEMPOTENCY_KEY=1 to send none. The body goes to stdout when the call succeeds.
# Optional: ACCEPT_LANGUAGE (e.g. en) sets the language of error messages; IF_MATCH sends an ETag.
# Exit code: 0 done; 10 fix the request; 11 read the resource before anything else;
#            12 read again and redo the change (412); 13 give up.
FILMO_MAX_RETRIES=3

filmo_request() {
  local method="$1" path="$2" body="$3"
  local base="${FILMO_BASE_URL:-https://app.filmo.io}"
  local is_write=0 key="" retries=0 waits=0
  [ "$method" != "GET" ] && is_write=1
  case "${path%%[?]*}" in
    /api/v1/availability/check | /api/v1/staff/availability | /api/v1/vehicles/availability | /api/v1/contacts/lookup | /api/v1/ai/ask) is_write=0 ;;
  esac
  if [ "$is_write" = 1 ] && [ "$NO_IDEMPOTENCY_KEY" != 1 ]; then
    key="${IDEMPOTENCY_KEY:-$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)}"
  fi
  local hdr out
  hdr="$(mktemp)"
  out="$(mktemp)"

  while :; do
    set -- -sS -X "$method" -D "$hdr" -o "$out" -w '%{http_code}' \
      -H "Authorization: Bearer $FILMO_API_KEY" -H "Accept: application/json"
    [ -n "$key" ] && set -- "$@" -H "Idempotency-Key: $key" # the same key on every retry
    [ -n "$ACCEPT_LANGUAGE" ] && set -- "$@" -H "Accept-Language: $ACCEPT_LANGUAGE"
    [ -n "$IF_MATCH" ] && set -- "$@" -H "If-Match: $IF_MATCH"
    [ -n "$body" ] && set -- "$@" -H "Content-Type: application/json" --data "$body"
    local status
    status="$(curl "$@" "$base$path")" || status=000 # network failure: it may or may not have arrived

    local problem=0 code="" cause="" replay="" wait=""
    if [ "$status" != 000 ]; then
      grep -qi '^content-type:.*application/problem+json' "$hdr" && problem=1
      if [ "$problem" = 1 ]; then
        code="$(jq -r '.code // empty' "$out" 2>/dev/null)"
        cause="$(jq -r '.errors[0].code // empty' "$out" 2>/dev/null)" # why a 409 happened
      fi
      grep -qi '^idempotent-replay: true' "$hdr" && replay=true
      wait="$(grep -i '^retry-after:' "$hdr" | tail -1 | tr -d '\r' | awk '{print $2}')"
    fi

    if [ "$status" != 000 ] && [ "$status" -lt 400 ]; then
      cat "$out"
      rm -f "$hdr" "$out"
      return 0
    fi

    if [ "$status" = 429 ]; then
      # Wait as long as the server says, then retry with the same key.
      [ "$waits" -ge 5 ] && { _filmo_fail "$status" "$code" "$out" "$hdr"; return 13; }
      waits=$((waits + 1))
      sleep "$([ "${wait:-0}" -gt 0 ] 2>/dev/null && echo "$wait" || echo 1)"
      continue
    fi
    if [ "$status" = 409 ] && [ "$code" = conflict ]; then
      # errors[0].code says why. in_progress and lock_timeout clear by waiting;
      # invalid_state (the state of the resource forbids the call) never does.
      if [ "$cause" = invalid_state ] || [ "$retries" -ge "$FILMO_MAX_RETRIES" ]; then
        _filmo_fail "$status" "$code" "$out" "$hdr"
        return 11
      fi
      sleep $((1 << retries)) # 1 s, 2 s, 4 s
      retries=$((retries + 1))
      continue
    fi
    # A 500 from the API, or a platform failure (network error, or a 502/503/504 that is not a problem document).
    if [ "$status" = 500 ] || [ "$status" = 000 ] ||
      { [ "$problem" = 0 ] && { [ "$status" = 502 ] || [ "$status" = 503 ] || [ "$status" = 504 ]; }; }; then
      # The failure happened after the commit and is stored for 24 h: retrying returns it again.
      if [ "$replay" = true ] || { [ "$is_write" = 1 ] && [ -z "$key" ]; }; then
        _filmo_fail "$status" "$code" "$out" "$hdr"
        return 11
      fi
      if [ "$retries" -ge "$FILMO_MAX_RETRIES" ]; then
        _filmo_fail "$status" "$code" "$out" "$hdr"
        return 13
      fi
      sleep $((1 << retries))
      retries=$((retries + 1))
      continue
    fi
    _filmo_fail "$status" "$code" "$out" "$hdr"
    if [ "$status" = 412 ]; then return 12; fi
    if [ "$status" -ge 500 ]; then return 13; fi
    return 10
  done
}

_filmo_fail() { # status code body-file header-file
  local rid
  rid="$(grep -i '^x-request-id:' "$4" 2>/dev/null | tr -d '\r' | awk '{print $2}')"
  echo "filmo: HTTP $1 ${2:+($2) }request $rid" >&2
  cat "$3" >&2 2>/dev/null
  rm -f "$3" "$4"
}

# 207 (returnOrderLineItems with atomic false): resend only the lines that failed,
# each round with a NEW key, because the same key would replay the same 207.
# Usage: return_lines '[{"lineItemId":"...","checkInQuantity":1,"returnCondition":"good"}]'
return_lines() {
  local pending="$1" round res
  for round in 1 2 3; do
    [ "$(echo "$pending" | jq 'length')" = 0 ] && break
    res="$(IDEMPOTENCY_KEY="$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)" \
      filmo_request POST /api/v1/orders/line-items/returns \
      "$(jq -c '{items: ., atomic: false}' <<<"$pending")")" || return $?
    # Keep only the elements that failed (their index in what we sent).
    pending="$(jq -c --argjson sent "$pending" \
      '[.data[] | select(.status == "failed") | $sent[.index]]' <<<"$res")"
  done
  echo "$pending" # the lines that still failed; [] when everything was returned
}

// filmo-request.mjs: one function for any call to the Filmo REST API.
// Node 22+, no dependencies. Needs FILMO_API_KEY; FILMO_BASE_URL is optional.
const BASE = process.env.FILMO_BASE_URL ?? "https://app.filmo.io";
const MAX_RETRIES = 3; // conflicts, 500s and platform errors
const MAX_RATE_LIMIT_WAITS = 5;

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
// 0.5 s, 1 s, 2 s... with jitter, capped at 30 s.
const backoff = (retry) => Math.min(30_000, 500 * 2 ** retry) * (0.5 + Math.random() / 2);

export class FilmoError extends Error {
  // action: "fix-request" | "read-resource" | "reread-and-redo" | "give-up"
  constructor(message, { action, status, problem, requestId }) {
    super(message);
    Object.assign(this, { action, status, problem, requestId });
  }
}

// Query POSTs do not declare Idempotency-Key, so they never get one.
const QUERY_POSTS = [
  "/api/v1/availability/check",
  "/api/v1/staff/availability",
  "/api/v1/vehicles/availability",
  "/api/v1/contacts/lookup",
  "/api/v1/ai/ask",
];

export async function filmoRequest(method, path, { query, body, idempotencyKey, ifMatch, language, headers: extra } = {}) {
  const isWrite = method !== "GET" && !QUERY_POSTS.includes(path.split("?")[0]);
  // Every write that declares the header carries a key. Pass idempotencyKey: null to send none on purpose.
  const key = !isWrite ? null : idempotencyKey === undefined ? crypto.randomUUID() : idempotencyKey;

  const url = new URL(path, BASE);
  for (const [name, value] of Object.entries(query ?? {})) {
    for (const v of [].concat(value)) url.searchParams.append(name, String(v));
  }
  const headers = { Authorization: `Bearer ${process.env.FILMO_API_KEY}`, Accept: "application/json" };
  if (body !== undefined) headers["Content-Type"] = "application/json";
  if (key) headers["Idempotency-Key"] = key; // the same key on every retry of this call
  if (ifMatch) headers["If-Match"] = ifMatch; // the ETag you read
  if (language) headers["Accept-Language"] = language; // language of error messages, e.g. "en"
  Object.assign(headers, extra);

  let retries = 0;
  let waits = 0;
  for (;;) {
    let res = null;
    try {
      res = await fetch(url, {
        method,
        headers,
        body: body === undefined ? undefined : JSON.stringify(body),
      });
    } catch {
      // Network failure: the request may or may not have arrived.
    }
    const status = res ? res.status : 0;
    const text = res ? await res.text() : "";
    if (res && status < 400) {
      return { status, headers: res.headers, body: text ? JSON.parse(text) : null };
    }

    let problem = null;
    if (res?.headers.get("content-type")?.includes("application/problem+json")) {
      try {
        problem = JSON.parse(text);
      } catch {}
    }
    const fail = (action) =>
      new FilmoError(method + " " + path + " -> " + (status || "network error") + (problem ? " " + problem.code : ""), {
        action,
        status,
        problem,
        requestId: res?.headers.get("x-request-id") ?? problem?.requestId,
      });

    if (status === 429) {
      // Wait as long as the server says, then retry with the same key.
      if (waits++ >= MAX_RATE_LIMIT_WAITS) throw fail("give-up");
      const seconds = Number(res.headers.get("retry-after"));
      await sleep((seconds > 0 ? seconds : 1) * 1000);
      continue;
    }
    if (status === 409 && problem?.code === "conflict") {
      // errors[0].code says why. "in_progress" and "lock_timeout" clear by waiting;
      // "invalid_state" (the state of the resource forbids the call) never does.
      const cause = problem.errors?.[0]?.code;
      if (cause === "invalid_state" || retries >= MAX_RETRIES) throw fail("read-resource");
      await sleep(backoff(retries++));
      continue;
    }
    // A 500 from the API, or a platform failure (network error, or a 502/503/504 that is not a problem document).
    const platform = status === 0 || (!problem && [502, 503, 504].includes(status));
    if (status === 500 || platform) {
      // The failure happened after the commit and is stored for 24 h: retrying returns it again.
      if (res?.headers.get("idempotent-replay") === "true") throw fail("read-resource");
      // Without a key a retry could write twice.
      if (isWrite && !key) throw fail("read-resource");
      if (retries >= MAX_RETRIES) throw fail("give-up");
      await sleep(backoff(retries++));
      continue;
    }
    if (status === 412) throw fail("reread-and-redo");
    throw fail(status >= 500 ? "give-up" : "fix-request"); // validation, 413, 422, 503 service_unavailable...
  }
}

// 207 (returnOrderLineItems with atomic: false): resend only the lines that failed,
// each round with a NEW key, because the same key would replay the same 207.
export async function returnLines(items, rounds = 3) {
  let pending = items;
  const returned = [];
  for (let round = 0; round < rounds && pending.length > 0; round++) {
    const res = await filmoRequest("POST", "/api/v1/orders/line-items/returns", {
      body: { items: pending, atomic: false },
      idempotencyKey: crypto.randomUUID(),
    });
    const failed = [];
    for (const result of res.body.data) {
      if (result.status === "returned") returned.push(result.id);
      else failed.push(pending[result.index]);
    }
    pending = failed;
  }
  return { returned, failed: pending };
}

# filmo_request.py: one function for any call to the Filmo REST API.
# Python 3 with requests. Needs FILMO_API_KEY; FILMO_BASE_URL is optional.
import os
import random
import time
import uuid

import requests

BASE = os.environ.get("FILMO_BASE_URL", "https://app.filmo.io")
MAX_RETRIES = 3  # conflicts, 500s and platform errors
MAX_RATE_LIMIT_WAITS = 5
_UNSET = object()


class FilmoError(Exception):
    """action: fix-request | read-resource | reread-and-redo | give-up"""

    def __init__(self, message, action, status, problem, request_id):
        super().__init__(message)
        self.action, self.status = action, status
        self.problem, self.request_id = problem, request_id


def backoff(retry):
    # 0.5 s, 1 s, 2 s... with jitter, capped at 30 s.
    return min(30, 0.5 * 2**retry) * (0.5 + random.random() / 2)


# Query POSTs do not declare Idempotency-Key, so they never get one.
QUERY_POSTS = {
    "/api/v1/availability/check",
    "/api/v1/staff/availability",
    "/api/v1/vehicles/availability",
    "/api/v1/contacts/lookup",
    "/api/v1/ai/ask",
}


def filmo_request(
    method, path, query=None, body=None, idempotency_key=_UNSET, if_match=None, language=None, extra_headers=None
):
    is_write = method != "GET" and path.split("?")[0] not in QUERY_POSTS
    # Every write that declares the header carries a key. Pass idempotency_key=None to send none on purpose.
    if not is_write:
        key = None
    else:
        key = str(uuid.uuid4()) if idempotency_key is _UNSET else idempotency_key
    headers = {
        "Authorization": f"Bearer {os.environ['FILMO_API_KEY']}",
        "Accept": "application/json",
    }
    if key:
        headers["Idempotency-Key"] = key  # the same key on every retry of this call
    if if_match:
        headers["If-Match"] = if_match  # the ETag you read
    if language:
        headers["Accept-Language"] = language  # language of error messages, e.g. "en"
    headers.update(extra_headers or {})

    retries = waits = 0
    while True:
        try:
            res = requests.request(
                method, BASE + path, params=query, json=body, headers=headers, timeout=30
            )
        except requests.RequestException:
            res = None  # Network failure: the request may or may not have arrived.
        status = res.status_code if res is not None else 0
        if res is not None and status < 400:
            return status, res.headers, (res.json() if res.content else None)

        problem = None
        if res is not None and "application/problem+json" in res.headers.get("Content-Type", ""):
            try:
                problem = res.json()
            except ValueError:
                pass

        def fail(action):
            label = "network error" if status == 0 else str(status)
            if problem:
                label += " " + problem["code"]
            request_id = (res.headers.get("X-Request-Id") if res is not None else None) or (
                problem or {}
            ).get("requestId")
            return FilmoError(method + " " + path + " -> " + label, action, status, problem, request_id)

        if status == 429:
            # Wait as long as the server says, then retry with the same key.
            if waits >= MAX_RATE_LIMIT_WAITS:
                raise fail("give-up")
            waits += 1
            try:
                seconds = float(res.headers.get("Retry-After", ""))
            except ValueError:
                seconds = 0
            time.sleep(seconds if seconds > 0 else 1)
            continue
        if status == 409 and problem and problem["code"] == "conflict":
            # errors[0].code says why. in_progress and lock_timeout clear by waiting;
            # invalid_state (the state of the resource forbids the call) never does.
            cause = ((problem.get("errors") or [{}])[0]).get("code")
            if cause == "invalid_state" or retries >= MAX_RETRIES:
                raise fail("read-resource")
            time.sleep(backoff(retries))
            retries += 1
            continue
        # A 500 from the API, or a platform failure (network error, or a 502/503/504 that is not a problem document).
        platform = status == 0 or (problem is None and status in (502, 503, 504))
        if status == 500 or platform:
            # The failure happened after the commit and is stored for 24 h: retrying returns it again.
            if res is not None and res.headers.get("Idempotent-Replay") == "true":
                raise fail("read-resource")
            # Without a key a retry could write twice.
            if is_write and not key:
                raise fail("read-resource")
            if retries >= MAX_RETRIES:
                raise fail("give-up")
            time.sleep(backoff(retries))
            retries += 1
            continue
        if status == 412:
            raise fail("reread-and-redo")
        raise fail("give-up" if status >= 500 else "fix-request")  # validation, 413, 422, 503 service_unavailable...


def return_lines(items, rounds=3):
    """207 (returnOrderLineItems with atomic False): resend only the lines that failed,
    each round with a NEW key, because the same key would replay the same 207."""
    pending, returned = items, []
    for _ in range(rounds):
        if not pending:
            break
        _, _, res = filmo_request(
            "POST",
            "/api/v1/orders/line-items/returns",
            body={"items": pending, "atomic": False},
            idempotency_key=str(uuid.uuid4()),
        )
        failed = []
        for result in res["data"]:
            if result["status"] == "returned":
                returned.append(result["id"])
            else:
                failed.append(pending[result["index"]])
        pending = failed
    return returned, pending