SDK

배포한 코드에서 JustDeploy를 호출하는 공식 라이브러리입니다. 데이터베이스, 파일, 이메일 발송을 다루며, 배포된 앱은 키가 전혀 필요 없습니다. JustDeploy가 이미지에 신원을 넣어 두고 라이브러리가 그것을 사용합니다.

서버 코드용입니다. 앱을 배포만 하고 앱 안에서 JustDeploy를 호출하지 않는다면 이 페이지의 내용은 필요하지 않습니다.

설치

npm install @justdeploy/sdk@0.2.2

python -m pip install justdeploy-sdk==0.2.2

Python 패키지는 justdeploy-sdk로 설치하고 justdeploy으로 import합니다. 두 패키지 모두 저희 저장소에서 게시하며 같은 버전을 사용합니다.

인증 방식

클라이언트는 인자 없이 생성합니다. API URL도, 키도, 설정 파일도 넘기지 않습니다.

import { JustDeploy } from '@justdeploy/sdk'

const justdeploy = new JustDeploy()
const result = await justdeploy.databases.query('your-database-id', 'SELECT * FROM orders')

from justdeploy import JustDeploy

with JustDeploy() as justdeploy:
    result = justdeploy.databases.query("your-database-id", "SELECT * FROM orders")

Python은 같은 메서드를 await로 쓰는 AsyncJustDeploy도 함께 제공합니다.

다음 순서로 고정되어 있습니다.

• 환경에 JUSTDEPLOY_ACCESS_KEY와 JUSTDEPLOY_SECRET_KEY가 모두 있으면 짧게 유효한 세션으로 교환합니다. 내 컴퓨터에서 코드를 실행할 때 쓰는 경로입니다.
• 없으면 JustDeploy가 빌드하면서 넣어 둔 배포 신원을 사용합니다. 배포된 앱이 쓰는 경로이고 따로 준비할 것이 없습니다.
• 둘 다 없으면 추측하지 않고 인증 오류로 중단합니다.

두 변수 중 하나만 설정하면 오류입니다. 거부된 키가 조용히 배포 신원으로 넘어가는 일도 없습니다. 이미 키를 등록해 둔 앱은 그 키를 계속 사용하며, 그대로 두어도 빌드는 달라지지 않습니다.

사용할 수 있는 기능

세 영역이며 두 언어에서 이름이 같습니다. Python 메서드 이름은 snake case라서 listTables는 list_tables입니다.

justdeploy.databases.list()
justdeploy.databases.query(databaseId, 'SELECT * FROM orders')
justdeploy.databases.listTables(databaseId)
justdeploy.databases.createTable(databaseId, { ... })
justdeploy.databases.updateTable(databaseId, 'orders', { ... })
justdeploy.databases.deleteTable(databaseId, 'orders')

justdeploy.storages.list()
justdeploy.storages.upload(storageId, { ... })
justdeploy.storages.createUploadUrl(storageId, { name: 'image.jpg', mime: 'image/jpeg' })
justdeploy.storages.listFiles(storageId, { limit: 50 })
justdeploy.storages.getFile(storageId, fileId)
justdeploy.storages.download(storageId, fileId)
justdeploy.storages.deleteFile(storageId, fileId)

justdeploy.mail.send({ ... })
justdeploy.mail.list({ limit: 50 })
justdeploy.mail.get(mailId)

형태만 보고 짐작하기 어려운 두 가지가 있습니다. query는 데이터 구문만 받으므로 스키마 변경은 테이블 메서드로 하세요. 업로드는 영구 URL이 아니라 파일 id를 돌려주므로, id를 저장해 두고 링크가 필요할 때 getFile을 호출하세요.

재시도 가능성이 있는 이메일 발송에는 idempotencyKey를 넘기세요. 발송 성공은 전달이 아니라 접수를 뜻하므로, 전달 여부가 중요하면 나중에 status를 다시 확인하세요.

SQL과 입력값을 분리하세요. 값마다 따옴표 없는 ?를 하나씩 쓰고, 직접 이스케이프하거나 문자열에 끼워 넣지 마세요. 호출 하나는 문장 하나이며, 여러 호출이 하나의 트랜잭션이 되지는 않습니다.

const result = await justdeploy.databases.query(databaseId,
  'SELECT * FROM orders WHERE customer = ?', { params: [customer] })

result = justdeploy.databases.query(database_id,
    "SELECT * FROM orders WHERE customer = ?", params=[customer])

입력값은 문자열, 유한한 숫자, 참·거짓, null을 받습니다. 큰 정수와 정확한 소수는 문자열로 보내세요. 테이블·컬럼 이름은 고정하세요. LIMIT ?는 지원하지 않으므로 범위가 제한된 정수인지 확인한 뒤 SQL에 LIMIT 숫자를 넣으세요.

브라우저 파일은 Storage로 직접 보냅니다. 앱 서버가 사용자의 업로드 권한을 확인한 뒤 createUploadUrl(Python: create_upload_url)을 호출하고, Cache-Control: no-store와 함께 업로드 정보만 반환하세요. SDK는 서버에만 둡니다.

const upload = await justdeploy.storages.createUploadUrl(storageId, {
  name: 'image.jpg', mime: 'image/jpeg',
})
// Return { fileId, url, method, headers, expiresAt } to the authorized browser.

const response = await fetch(upload.url, {
  method: upload.method, headers: upload.headers, body: selectedFile,
  credentials: 'omit', redirect: 'error',
})
if (!response.ok) throw new Error('Upload failed (' + response.status + ').')
// Save upload.fileId through your app API. No active-state wait is needed.

브라우저에 Credential이나 세션 토큰을 보내지 말고, 업로드에 Authorization이나 Content-Length를 추가하지 마세요. URL은 임시 권한이며 일회용 링크나 강제 크기 제한이 아닙니다. 로그나 저장소에 남기지 마세요. 준비 요청마다 새 파일이 생기므로 응답을 받지 못했다고 무작정 재시도하면 안 됩니다.

서버가 이미 파일 바이트나 스트림을 가지고 있으면 upload를 쓰세요. PUT 성공은 메타데이터가 pending이어도 바이트가 도착했다는 뜻입니다. 브라우저 다운로드는 서버에서 파일을 받아 중계하지 말고 getFile의 URL로 리다이렉트하세요.

삭제 성공은 삭제 요청이 수락됐다는 뜻이며, GET과 목록 정보는 나중에 반영될 수 있습니다. 직후 조회에 파일이 남아 있어도 삭제 실패가 아닙니다. 업로드가 실패하면 미완료 기록 정리를 시도하되, 정리 오류가 안전하게 정리된 SDK 전송 오류나 취소를 덮어쓰지는 않습니다.

호출이 실패할 때

SDK 오류는 JustDeployError으로 처리하세요. API 오류에는 status, retryAfter, requestId, details가 포함될 수 있습니다. 진단 로그에는 status와 requestId만 남기고 오류 전체, 요청, SQL, 파일 내용, 인증 정보는 기록하지 마세요. 취소된 요청도 서버 데이터를 이미 변경했을 수 있으므로 쓰기를 무작정 재시도하지 마세요.

오류 진단 정보는 유효한 JSON 필드를 우선 사용하고, 없거나 잘못된 값이면 Retry-After와 X-Request-Id 헤더를 사용합니다. JSON이 아닌 응답도 같습니다. 대기 시간은 양의 정수 초이며, 대기 시간이 있어도 요청을 자동으로 반복하지 않습니다. 401 응답 뒤 인증을 갱신해 한 번 재시도하는 동작은 GET에만 적용되고, 쓰기는 자동 재시도하지 않습니다.

인증 제한은 10초, 일반 API 요청별 제한은 30초입니다. 전체 호출의 제한 시간이 아니라 각각의 제한입니다. 앱의 시간 제한은 두 단계를 고려해 정하고, 시간 초과를 숨기려고 모든 제한을 없애지 마세요.

다루지 않는 것

• 서버 코드 전용입니다. 브라우저, edge runtime, Deno, Bun은 지원하지 않습니다. 브라우저 코드에 담긴 키는 이미 남에게 준 키입니다.
• Node.js와 Python만 지원합니다. 그 외 언어에서는 인증 문서의 헤더로 API를 직접 호출하세요.
• 데이터베이스와 파일, 이메일만 다룹니다. 빌드와 프로젝트, 로그 등은 API로 호출합니다.
• 명령줄 도구는 없고, 원하는 URL로 임의의 요청을 보내는 기능도 없습니다.

presigned 업로드와 다운로드에는 인증 정보가 실리지 않으므로 파일 전송으로 키가 새지 않습니다. 업로드가 아직 끝나지 않은 파일을 요청하면 반쯤 쓰인 응답 대신 잠시 후 다시 시도하라는 오류를 받습니다. 헤더 직접 호출은 인증, 키 관리는 인증 정보를 보세요.